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 for the eCommerce world.
Step 1 — Submit a POST report request
Make a POST call request with a JSON body or attached as a file as multipart/form-data.
https://api.similarweb.com/batch/v5/request-report
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 bodies
{
"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"
}
{
"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"
}
{
"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
domains | Characters in domain name can include letters, numbers, dashes, and hyphens. | amazon.com |
metrics | See the list of supported metrics above. | |
category_ids | Full list of supported categories is available in the Shopper Intelligence reference. Data is only returned for categories included in your subscription. Customers subscribed to full domains do not need to include category_ids when requesting brand metrics. | CategoryID |
start_date, end_date | Daily granularity uses YYYY-MM-DD; monthly granularity uses YYYY-MM. | Weekly: 2023-06-30 / Monthly: 2023-06 |
granularity | Time series granularity. | monthly, weekly_sunday |
response_format | Output of the API call. | JSON, csv, parquet, orc |
Optional parameters
brands | Choose brands from the list of supported brands. | Amazon, etc. |
limit | Number of results returned. The limit is per month of data. See the Shopper Intelligence metric table for details. | Integer |
all_history | Boolean. Default is false. | true / false |
webhook_url | A URL to ping when the status of your report changes. | URL |
Step 2 — Get the report status
After submitting your request and receiving a report ID, use the Request Report Status endpoint to check progress.
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 responses
{
"data_points_count": 1779429,
"download_url": "example_url.com",
"status": "completed",
"used_quota": 35589
}
{
"status": "pending"
}
The download link remains valid for 30 days. We recommend saving it for some time in case you need our help troubleshooting.
On this page
- Set Up Shopper Intelligence API