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 bodyRequest 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
Request Method | Synchronous GET requests | Asynchronous POST job submission |
Response Time | Immediate (seconds) | Minutes to hours depending on volume |
Response Format | JSON | CSV |
Max Domains Per Request | Typically 1-100 depending on endpoint | Up to 1,000,000 |
Historical Data | Up to 37 months | Up to 7 years |
Data Granularity | Daily, Weekly, Monthly | Daily, Weekly, Monthly |
Rate Limits | 10 requests per second | No rate limits on job submission |
Typical Use Case | Real-time queries, dashboards | Large-scale analysis, data warehouses |
Direct Database Delivery | No | Yes (S3, Snowflake, Databricks) |
Still unsure which API is right for you?
Contact your Similarweb Account Manager for personalized guidance based on your specific use case and data requirements.
What made this section unhelpful for you?
On this page
- REST API vs Batch API