This guide provides a step-by-step walkthrough for using Similarweb’s Batch API to make a report request. You’ll submit a batch job, check its status, and finally download the results once processing is complete.

1

Batch API Request Endpoint

The Batch API request is a POST request to this endpoint. It will initiate the batch job.

JSON

 
curl --location 'https://api.similarweb.com/batch/v5/request-report' \

2

Request Headers

The POST request has the following headers: API-key: Include your unique API key in the request header.

Content-Type: Set to application/json to indicate you are sending JSON data.

JSON

 
--header 'api-key: {{API_KEY}}' \
--header 'Content-Type: application/json' \

3

Request Body

The actual request is incorporated in the body. In this section you can configure all the report parameters such as the dataset, metrics, dates, and more

JSON

 
--data '{
  "delivery_information": {
    "response_format": "csv",
    "delivery_method": "download_link"
  },
  "report_query": {
    "tables": [
      {
        "vtable": "traffic_and_engagement",
        "granularity": "monthly",
        "filters": {
          "domains": [
            "amazon.com",
            "ebay.com",
            "etsy.com",
            "aliexpress.com"
          ],
          "countries": [
            "WW"
          ],
          "include_subdomains": true
        },
        "metrics": [
          "all_traffic_visits",
          "mobile_visits",
          "desktop_visits",
          "desktop_unique_visitors",
          "mobile_unique_visitors",
          "all_page_views"
        ],
        "start_date": "2024-04",
        "end_date": "2024-09"
      }
    ]
  }
}'

4

Delivery Information

Here you can configure output definitions such as response format (e.g., csv) and delivery method for the report (download link, integrations, etc)

JSON

 
  "delivery_information": {
    "response_format": "csv",
    "delivery_method": "download_link"
  },

5

Dataset / Data Table

Define the dataset you're looking to query (vtable). For a full list of available datasets use the Batch Describe endpoint.

JSON

 
        "vtable": "traffic_and_engagement",

6

Build you Report / Query

Based on the dataset you chose, you can now build your report including: granularity, filters (e.g., domains, countries, subdomains), metrics, and date range for the data you want to pull.

JSON

 
        "granularity": "monthly",
        "filters": {
          "domains": [
            "amazon.com",
            "ebay.com",
            "etsy.com",
            "aliexpress.com"
          ],
          "countries": [
            "WW"
          ],
          "include_subdomains": true
        },
        "metrics": [
          "all_traffic_visits",
          "mobile_visits",
          "desktop_visits",
          "desktop_unique_visitors",
          "mobile_unique_visitors",
          "all_page_views"
        ],
        "start_date": "2024-04",
        "end_date": "2024-09"

7

Submit the Request

Submit the request using a tool like cURL, Postman, or any API client.

Upon successful submission, you'll receive a response with a report_id. This report_id is crucial for the next steps, as it allows you to track the report's progress.

JSON

 
{
  "report_id": "845d6850-79d1-4125-964e-eaef0d6923e5",
  "status": "pending"
}

8

Monitor Request Status

Use the /request-status endpoint to check if your batch job is complete.

In your request to /request-status, provide the request_id received in the previous step.

Poll the request status endpoint periodically until you receive a status of complete. This indicates that the report is ready.

JSON

 
curl --location 'https://api.similarweb.com/v3/batch/request-status/{report_id}' \
--header 'api-key: {{API_KEY}}' \
--header 'Content-Type: application/json' \
---------------------------------------------------------------------------------------

9

Retrieve the Report

Once the job status is complete, you'll receive a response with a download link.

Use the provided download link to access your report.

JSON

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

Sections

Batch API - Datasets

On this page

Ask an AI

Code with AI