REST API vs Batch API

Overview

We offer two distinct API architectures designed for different use cases and integration patterns. Understanding which API to use is key for successful implementation and optimal performance.

This guide provides an in-depth comparison to help you choose the right API for your specific needs and explains how to leverage both APIs together for comprehensive solutions.

Which API Is Right For You?

REST API

The REST API provides synchronous, real-time access to Similarweb data through individual HTTP requests.

How It Works:

• Make individual HTTP GET requests to specific endpoints
• Receive immediate JSON responses
• Query data for one or multiple domains per request
• Access current and recent historical data

Request Example:

GET https://api.similarweb.com/v5/website-analysis/websites/traffic-and-engagement

 
curl --location 'https://api.similarweb.com/v5/website-analysis/websites/traffic-and-engagement?domain=amazon.com&start_date=2025-06&end_date=2025-08&granularity=monthly&web_source=desktop&country=us&format=json' \
--header 'api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json'

Response:

 
{
  "meta": {
    "request": {
      "format": "json",
      "domain": "amazon.com",
      "start_date": "2025-06",
      "end_date": "2025-08",
      "granularity": "monthly",
      "web_source": "total",
      "country": "us",
      "metrics": [
        "visits, bounce_rate, average_visit_duration"
      ],
      "mtd": false,
      "main_domain_only": false
    },
    "status": "success",
    "error_code": null,
    "error_message": "",
    "last_update": "",
    "data_type": "not_applicable"
  },
  "data": [
    {
      "date": "",
      "visits": 251251616,
      "bounce_rate": 0.36,
      "average_visit_duration": 1.521,
      "pages_per_visit": null,
      "page_views": null,
      "unique_visitors": null,
      "new_users": null,
      "returning_users": null
    }
  ]
}

Use REST API when you need:

• Real-time or near-real-time data
• Data for a small number of domains (under 100)
• Interactive user experiences
• Immediate validation or verification
• Current month metrics

Batch API

The Batch API provides asynchronous, large-scale data extraction through scheduled report generation.

How It Works:

• Submit a POST request with a JSON configuration defining your data requirements
• Receive a report_id to track the job
• Poll the status endpoint to check completion
• Download results as CSV when ready

Request Example:

POST https://api.similarweb.com/batch/v4/request-report

Request header:

 
curl --location 'https://api.similarweb.com/batch/v4/request-report' \
--header 'api-key: {{API_KEY}}' \
--header 'Content-Type: application/json' \
--request POST \
--data body

Request body (defining tables, metrics, domains, date ranges):

 
body{
  "delivery_information": {
    "response_format": "csv",
    "delivery_method_params": {
      "retention_days": 60
    }

Response Format: CSV file delivered via download URL or directly to your data warehouse (S3, Snowflake, Databricks)

Use Batch API when you need:

• Large amounts of historical data (multiple months or years)
• Large-scale analysis (hundreds to thousands of domains)
• Scheduled automated reports
• Data warehouse integration
• Maximum efficiency for bulk queries

Full Comparison Table