get_geographic_breakdown

Instructions

Implementation Reference

• src/kaltura_mcp/tools/analytics.py:698-801 (handler)

  The primary handler function for the 'get_geographic_breakdown' tool. It fetches raw geographic data from the core analytics module, enhances it with percentage calculations, top locations sorting, and adds insights like coverage statistics. Returns formatted JSON suitable for geographic visualizations and analysis.

  async def get_geographic_breakdown(
      manager: KalturaClientManager,
      from_date: str,
      to_date: str,
      granularity: str = "country",
      region_filter: Optional[str] = None,
      metrics: Optional[List[str]] = None,
  ) -> str:
      """
      Get analytics broken down by geographic location.
  
      This function provides location-based analytics at various levels of
      granularity, from global overview to city-level detail.
  
      USE WHEN:
      - Understanding global content reach
      - Planning regional content strategies
      - Analyzing market penetration
      - Optimizing CDN configuration
      - Compliance with regional requirements
  
      Args:
          manager: Kaltura client manager
          from_date: Start date (YYYY-MM-DD)
          to_date: End date (YYYY-MM-DD)
          granularity: Level of geographic detail:
              - "world": Global overview
              - "country": Country-level breakdown (default)
              - "region": State/province level
              - "city": City-level detail
          region_filter: Optional filter for specific region:
              - Country code (e.g., "US") for region/city views
              - Continent name for country views
          metrics: Optional list of metrics to include
  
      Returns:
          JSON with geographic distribution data:
          {
              "granularity": "country",
              "top_locations": [
                  {
                      "location": "United States",
                      "code": "US",
                      "metrics": {
                          "views": 45678,
                          "unique_viewers": 12345,
                          "avg_watch_time": 234.5,
                          "percentage": 35.2
                      }
                  },
                  ...
              ],
              "map_data": {...},  // GeoJSON format for visualization
              "insights": {
                  "fastest_growing": ["India", "Brazil"],
                  "highest_engagement": ["Canada", "UK"],
                  "coverage": "127 countries"
              }
          }
  
      Examples:
          # Global country breakdown
          get_geographic_breakdown(manager, from_date, to_date)
  
          # US state-level analysis
          get_geographic_breakdown(manager, from_date, to_date,
                                 granularity="region", region_filter="US")
  
          # City-level for California
          get_geographic_breakdown(manager, from_date, to_date,
                                 granularity="city", region_filter="US-CA")
      """
      from .analytics_core import get_geographic_analytics
  
      result = await get_geographic_analytics(
          manager=manager,
          from_date=from_date,
          to_date=to_date,
          level=granularity,
          country_filter=region_filter,
      )
  
      # Enhance with insights
      data = json.loads(result)
      if "data" in data and len(data.get("data", [])) > 0:
          # Add percentage calculations
          total = sum(float(item.get("count_plays", 0)) for item in data["data"])
          for item in data["data"]:
              plays = float(item.get("count_plays", 0))
              item["percentage"] = round((plays / total * 100) if total > 0 else 0, 2)
  
          # Sort by plays and add top locations
          data["top_locations"] = sorted(
              data["data"], key=lambda x: float(x.get("count_plays", 0)), reverse=True
          )[:10]
  
          # Add insights
          data["insights"] = {
              "total_countries": len(data["data"]),
              "coverage": f"{len(data['data'])} locations",
          }
  
      return json.dumps(data, indent=2)

• src/kaltura_mcp/server.py:262-291 (schema)

  MCP tool schema definition including input parameters validation (from_date, to_date required; granularity enum; etc.) and detailed usage description for the get_geographic_breakdown tool.

  name="get_geographic_breakdown",
  description="Analyze viewer LOCATIONS and regional performance. USE WHEN: Understanding global reach, planning regional strategies, checking market penetration, optimizing CDN, compliance checks. RETURNS: Views/viewers by country/region/city with percentages. EXAMPLES: 'Which countries watch our content?', 'Show US state breakdown', 'Find top 10 cities for viewership'. Includes map-ready data.",
  inputSchema={
      "type": "object",
      "properties": {
          "from_date": {
              "type": "string",
              "description": "Start date in YYYY-MM-DD format (e.g., '2024-01-01')",
          },
          "to_date": {
              "type": "string",
              "description": "End date in YYYY-MM-DD format (e.g., '2024-01-31')",
          },
          "granularity": {
              "type": "string",
              "enum": ["world", "country", "region", "city"],
              "description": "Location detail level (default: 'country'): 'world' = continents, 'country' = nations, 'region' = states/provinces, 'city' = cities. Higher detail requires region_filter.",
          },
          "region_filter": {
              "type": "string",
              "description": "Zoom into specific area: For region view use country code (e.g., 'US' for US states), for city view use 'US-CA' for California cities. Required for region/city granularity.",
          },
          "metrics": {
              "type": "array",
              "items": {"type": "string"},
              "description": "Metrics to include",
          },
      },
      "required": ["from_date", "to_date"],
  },

• src/kaltura_mcp/server.py:511-512 (registration)

  Tool dispatch registration in the MCP server's call_tool handler, mapping the tool name to its execution with the Kaltura manager.

  elif name == "get_geographic_breakdown":
      result = await get_geographic_breakdown(kaltura_manager, **arguments)

• src/kaltura_mcp/tools/__init__.py:56-56 (registration)

  Tool export and registration in the tools module __all__ list, making it available for import in the server.

  "get_geographic_breakdown",

• src/kaltura_mcp/tools/analytics.py:872-881 (helper)

  Helper documentation in list_analytics_capabilities function, providing purpose, use cases, and example for the tool.

      "function": "get_geographic_breakdown",
      "purpose": "Location-based analytics",
      "use_cases": [
          "Global reach analysis",
          "Regional content strategy",
          "Market penetration",
          "CDN optimization",
      ],
      "example": "get_geographic_breakdown(manager, from_date, to_date, granularity='country')",
  },