Getting Started

Brands Top Competitors

Returns time-series data of competitor brands with the highest audience overlap, ranked by affinity to a given brand within a category.

Variants:

Time-series (this endpoint): GET /v5/shopper-analysis/brands/top-competitors — data broken down by date for trend analysis.
Aggregated: GET /v5/shopper-analysis/brands/top-competitors/aggregated — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a date field per record; the aggregated response omits it and returns one consolidated row.

Possible output fields:

date: Date of the data point (time-series only)
competitor_brand: Name of the competitor brand
affinity: Audience affinity score between the queried brand and the competitor
views: Number of product views for the competitor brand
units_sold: Number of units sold by the competitor brand
revenue: Revenue generated by the competitor brand (local currency)
revenue_in_usd: Revenue generated by the competitor brand (USD)
competitive_overlap: Degree of audience overlap between the queried brand and the competitor
brand_share_of_competition: The queried brand's share relative to the competitor

Constraints:

domain, category, and brand are required
granularity supports monthly or weekly
Supports pagination (limit, offset, sort, asc)

This endpoint uses data credits. See the data credits guide to estimate costs.

Header Parameters

api-keystring

Query Parameters

domainstring Required

Amazon domain. Supported domains: amazon.com, amazon.co.uk, amazon.it, amazon.fr, amazon.de, amazon.ca. All category IDs, brands, and ASINs are domain-specific and must match the selected domain

granularitystring

Time granularity for the returned values

Enum values:

monthlyweekly

start_datestring

Start date in 'YYYY-MM' or 'YYYY-MM-DD' format. For weekly granularity, automatically adjusted to the first Sunday of the specified month.

end_datestring

End date in 'YYYY-MM' or 'YYYY-MM-DD' format. For weekly granularity with MTD=true, automatically set to the latest available Saturday. For weekly granularity with MTD=false, automatically adjusted to the last Saturday of the specified month.

metricsarray

Comma-separated list of metrics: competitor_brand, affinity, views, units_sold, revenue, revenue_in_usd, competitive_overlap, brand_share_of_competition

Enum values:

competitor_brandaffinityviewsunits_soldrevenuerevenue_in_usdcompetitive_overlapbrand_share_of_competition

mtdboolean

When true with weekly granularity, end_date is set to the latest available Saturday. NOT supported for monthly granularity.

categorystring Required

Amazon category ID (numeric string, e.g., '679182011'). Category IDs are domain-specific and cannot be used across different Amazon domains. Use the category search endpoint to find valid IDs for your domain

brandstring Required

Brand name. Use brand search or top brands endpoints to discover available brands for your domain

formatstring

Format in which the reply should be returned

Enum values:

jsonxml

limitinteger

Sets how many results to return.

offsetinteger

Defines the number of results to skip

ascboolean

Orders the results by ascending or descending

Nullable:

True

sortstring

Selects a specific metric to order results by

Response

200

Object

Success

Response Attributes

metaobject

Show child attributes

dataarray

Nullable:

True

Show child attributes

Sections

Brands Top Competitors

Header Parameters

Query Parameters

Response

Response Attributes

What made this section helpful for you?

What made this section unhelpful for you?

Response

What made this section helpful for you?

What made this section unhelpful for you?

Sections

Brands Top Competitors

Header Parameters

Query Parameters

ResponseExpand all

Response Attributes

What made this section helpful for you?

What made this section unhelpful for you?

Response

What made this section helpful for you?

What made this section unhelpful for you?

Ask an AI

Code with AI

Response