Set Up Shopper Intelligence API

AKA Shoppers intelligence

The following metrics are available exclusively to Similarweb Shopper Intelligence customers with Batch API access.

Shopper Intelligence, Similarweb’s eCommerce data, helps companies monitor consumer demand, analyze shopper behavior, and optimize search strategies to win in the eCommerce world.

Similar to regular Batch API calls, this are the steps you need to do to make an API call:

1. Make a POST call request with a JSON in the body or attached as a file as multipart/form-data.

POST

https://api.similarweb.com/v3/batch/shopper/request-report

Python

import requests

url = "https://api.similarweb.com/v3/batch/shopper/request-report"

payload={'request': '/Users/Batchexample.json'}
files=[

]
headers = {
  'api-key': '{{your_api_key}}'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

Example JSON

Category level

{
    "domains":[
        "amazon.com"
    ],
    "category_ids": [2335752011],
    "metrics":[
        "category_sales_performance_product_views",
        "category_sales_performance_units_sold",
        "category_sales_performance_revenue",
        "category_sales_performance_cvr"
    ],
    "start_date": "2021-09",
    "end_date": "2021-11",
    "granularity": "monthly",
    "response_format": "csv"
}

Brand Level

{
    "domains":[
        "amazon.com"
    ],
    "brands": [2335752011],
    "metrics":[
        "brand_sales_performance_product_views",
        "brand_sales_performance_units_sold",
        "brand_sales_performance_revenue",
        "brand_sales_performance_cvr",
        "brand_sales_performance_revenue_1P",
        "brand_sales_performance_revenue_3P",
        "brand_sales_performance_units_sold_1P",
        "brand_sales_performance_units_sold_3P"
    ],
    "start_date": "2021-09",
    "end_date": "2021-11",
    "granularity": "monthly",
    "response_format": "csv"
}

Top Brands

{
    "domains":[
        "amazon.com"
    ],
    "metrics":[
        "brand_sales_performance_top_products_units_sold",
        "brand_sales_performance_top_products_revenue",
        "brand_sales_performance_top_products_product_views",
        "brand_sales_performance_top_products_average_unit_price",
        "brand_sales_performance_top_products_reviews",
        "brand_sales_performance_top_products_rating"
    ],
    "start_date": "2021-09",
    "end_date": "2021-11",
    "granularity": "monthly",
    "response_format": "csv"
}

Mandatory Parameters:

Parameters	Description	Acceptable values
domains	Characters in domain name can include letters, numbers, dashes, and hyphens.	amazon.com
metrics	See list of metrics supported above.
category_ids	Full list of supported categories can be found here. Note: data will only be returned for categories included in your subscription package. Customers subscribed to full domains do not need to include category_ids parameter at all when requesting brand metrics.	CategoryID
start_date, end_date	For daily granularity, format the start-and-end date like this: YYYY-MM-DD. For monthly granularity, format the start-and-end date like this- YYYY-MM	Daily: 2023-06-30 Monthly: 2023-06
granularity	Time series granularity	monthly, weekly, daily
response_format	Output of the API call	JSON, csv, parquet, orc

Optional parameters:

Parameters	Description	Acceptable values
brands	Choose the brands you want from the list of supported brands.	Amazon, etc
limit	Define the number of results that are returned. The limit is per month of data. See Shopper Intelligence metric table for details.	Integer
all_history	Boolean, valid values true or false, default is false.	true/false
webhook_url	Enter a URL you'd like us to ping when the status of your report changes.

2. After you made your request and got your report ID, use the Request Report Status to receive report status.

Upon completion, you will need to request the report status.

GET Request Report Status

GET

https://api.similarweb.com/v3/batch/request-status/{{generated_report_id}}

Python

import requests

url = "https://api.similarweb.com/v3/batch/request-status/{{generated_report_id}}"

payload={}
headers = {
  'api-key': '{{your_api_key}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Example Response:

Completed Request

{
    "data_points_count": 1779429,
    "download_url": "example_url.com",
    "status": "completed",
    "used_quota": 35589
}

In Progress

{
    "status": "pending"
}

👍

The download link will remain valid for 30 days. We recommend saving these for a certain time period just in case you will need our assistance to troubleshoot any issue that may occur.