The Category Share by Brand report provides brand category share analysis across product categories.

¶ Report Details

Report Type ID: GR_CATEGORY_SHARE_BY_BRAND

Use Cases:

• Brand market share analysis
• Category performance insights
• Competitive positioning

Filters:

• brand: Brand name filter

Dimensions:

• sales_channel: Distribution channel
• l1_category_name, l2_category_name, l3_category_name, l4_category_name: Product category hierarchy
  • L1 example: “Beverages and Drink Mixes”
  • L2 example: “Alcoholic Beverages”
  • L3 example: “Hard Cider”
  • L4 example: “Perry”

Important: Metrics are calculated at the granularity of the lowest category level dimension selected:

• L2 dimension (with or without L1): Returns metrics at L2 level (e.g., “Alcoholic Beverages”)
• L3 dimension (with or without L1, L2): Returns metrics at L3 level (e.g., “Hard Cider”)
• L4 dimension (with or without L1, L2, L3): Returns metrics at L4 level (e.g., “Perry”)

Note: L1 dimension alone is not supported.

Supported Time Units: DAILY, WEEKLY, MONTHLY, SUMMARY

¶ Available Metrics

• sales_category_share
• orders_category_share
• units_category_share

¶ Time Range Configuration

When configuring time ranges, follow these guidelines for proper aggregation:

Daily and Summary Reports

• Start Date: Any valid date
• End Date: Any valid date after start date
• Example: "start_time": "2025-07-15T00:00:00Z", "end_time": "2025-07-20T00:00:00Z"

Weekly Reports

• Start Date: Must be a Monday
• End Date: Must be the next Monday
• Example: "start_time": "2025-07-21T00:00:00Z", "end_time": "2025-07-28T00:00:00Z"

Monthly Reports

• Start Date: Must be the first day of a month
• End Date: Must be the first day of the next month
• Example: "start_time": "2025-07-01T00:00:00Z", "end_time": "2025-08-01T00:00:00Z"

¶ Filter Operators

Supported operators: EQUAL, NOT_EQUAL, IN

¶ Example Request

curl -X POST "https://api.uber.com/v1/ads/{account_id}/reporting/report" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -d '{
    "report_type": "GR_CATEGORY_SHARE_BY_BRAND",
    "time_range": {
      "start_time": "2024-01-01T00:00:00Z",
      "end_time": "2024-01-31T00:00:00Z"
    },
    "columns": [
      "sales_channel",
      "l1_category_name",
      "l2_category_name",
      "l3_category_name",
      "sales_category_share",
      "orders_category_share",
      "units_category_share"
    ],
    "time_unit": "SUMMARY",
    "file_format": "CSV",
    "filters": [
      {
        "column": "brand",
        "operator": "EQUAL",
        "values": ["Premium Brand Co"]
      }
    ]
  }'

¶ Example Response

{
  "report_id": "8a2e38b2-59fb-5242-a0ec-e913a42150b5"
}

¶ Related Reports

• Category Share by Brand Owner - Brand owner market share analysis
• Total Sales - Product-level sales performance