Similarweb

Getting Started

The Similarweb API delivers digital intelligence at scale, powering smarter business decisions for the world's most innovative companies. Whether you're building competitive dashboards, AI applications and agents, enriching CRM data, or conducting market research, our API provides the foundational data you need to outperform your competition.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>This documentation is for the latest version of our API (V5) and is currently in beta. Check out <a href="68b3660110ed4447ddbb157f/68b5af433726dd7779a34d16" target="">what's new in V5</a>.</p>
  <p>You can access V4 documentation <a href="https://developers.similarweb.com/" target="_blank">here</a></p>
</Callout>

Available Data
--------------

Similarweb API provides access to an unmatched breadth of digital intelligence metrics, including:

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>100M+ websites</p>
<p>Website traffic data, engagement metrics, audience and demographic insights</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>4M+ Apps</p>
<p>Mobile app performance, download estimates, app rankings, user engagement</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>5B+ Keywords</p>
<p>Keyword research, SERP analysis, SEO competitive data, rankings, and more</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>30M+ Companies</p>
<p>Company data, technographics, and lead enrichment</p></description>
</Card>
</CardGroup>

Global Coverage
---------------

We cover **190+ countries and territories** with comprehensive digital intelligence data, including **US state-level data** for enhanced local market analysis.

Historical Data
---------------

Access up to **7 years of historical data** for trend analysis and long-term strategic research across all data types.

Flexible API Architecture
-------------------------

Similarweb API provides both real-time and bulk data access to match your specific use case:

*   **REST API**: Perfect for real-time dashboards, applications, and on-demand queries
    
*   **Batch API**: Ideal for large-scale analysis, data warehouses, and historical research
    

Ready to Get Started?
---------------------

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title=""><p>Gain access to our API</p><p>All Similarweb <a href="https://www.similarweb.com/packages/marketing/" target="_blank">paid subscriptions</a> include API access.</p></Step><Step stepNumber="2" title=""><p>Create an API key</p><p>It only takes a minute. Follow the steps in the <a href="68b3660110ed4447ddbb157f/68b5adaf6c50fdd809747571" target="">Authentication guide</a></p></Step><Step stepNumber="3" title=""><p>Make your first request</p><p><a href="68b3660110ed4447ddbb157f/68b5af2f6c50fdd80975f4da" target="">Follow the steps in this guide</a> to make your first successful API request</p></Step></Steps>

Introduction

Main Improvements
-----------------

V5 introduces major improvements for better developer experience and performance making integration faster, more flexible, and more powerful. These improvements maintain full compatibility with existing API pricing while delivering better performance and usability.

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>AI and MCP Ready</p>
<p>Detailed specifications designed for AI agents and applications + MCP support</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Advanced Request Capabilities</p>
<p>Flattened data structure and flexible metric selection</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title></title>
  <description><p>Unified API Standards</p>
<p>Standardized response formats, authentication, and request patterns</p></description>
</Card>
</CardGroup><Divider />

AI and MCP Ready
----------------

V5 includes comprehensive specifications designed for AI agents and applications, LLMs, automation tools, and vibe-coding platforms. Check the following guides to learn more about how you can connect Similarweb data to your AI tools and use our data more efficiently:

*   [**MCP Server integration guide**](689c7b93dd190b3ba8717733/689c7c36dd190b3ba8717a0e)
    

<Divider />

Advanced Request Capabilities
-----------------------------

### Flexible Metric Selection

Choose exactly the metrics you need - from a single data point to comprehensive multi-metric analysis in one request.

<Callout attributes='{"isFitToPage":false,"dataType":"error","style":{"width":"60%","minWidth":"60%"}}'>
  <strong class="slate-bold">Previous versions</strong>
  <p>Single metric per request → Multiple API calls required</p>
</Callout>
<Callout attributes='{"isFitToPage":false,"dataType":"success","style":{"width":"60%","minWidth":"60%"}}'>
  <strong class="slate-bold">API V5</strong>
  <p>Multiple metrics per request → Unified, efficient data retrieval</p>
</Callout>

**What does it mean for you:**

*   **Reduced API Calls**: Get related metrics in single requests
    
*   **Faster Dashboards**: Build comprehensive views with fewer API calls.
    

### Single API Key (Batch and REST)

Unlike in V4, where separate keys were required for REST and Batch endpoints, you can now pull data from any endpoint using a single key

<Divider />

Unified API Standards
---------------------

Consistent behavior across all endpoints - V5 standardizes response formats, error handling, and request patterns across every endpoint. This means once you learn one endpoint, you understand them all.

<Callout attributes='{"isFitToPage":false,"dataType":"info","style":{"width":"60%","minWidth":"60%"}}'>
  <p>To see response examples and test all the available endpoints visit the <a href="https://docs.similarweb.com/api-runner/similarweb/api-v5" target="">API Explorer</a>.</p>
</Callout>
<Divider />

Automatic Changelog
-------------------

New endpoints and features will be added to the [changelog](https://docs.similarweb.com/changelog/similarweb/api-v5) as they become available so you can stay updated in real-time.

What's New in V5

Secure API Access with API Keys
-------------------------------

All Similarweb API requests require authentication using API keys. This guide covers everything you need to know about creating, managing, and using your API keys securely.

<Divider />

Before You Begin
----------------

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <ul class="slate-ul "><li class="slate-li "><div style="position:relative">Active Similarweb account with API access (contact your Account Manager if you need access)</div></li><li class="slate-li "><div style="position:relative">Admin-level permissions (required for API key generation and management)</div></li></ul>
</Callout>

API Keys Creation
-----------------

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title="Access Your Account Settings"><ol class="slate-ol "><li class="slate-li "><div style="position:relative">Log in to your <a href="https://pro.similarweb.com" target="_blank">Similarweb platform</a></div></li><li class="slate-li "><div style="position:relative">Navigate to <strong class="slate-bold">Settings</strong> → <strong class="slate-bold">Account</strong> from the left menu</div></li><li class="slate-li "><div style="position:relative">Look for the <strong class="slate-bold">Data Tools</strong> section</div></li></ol></Step><Step stepNumber="2" title="Generate Your API Key"><ol class="slate-ol "><li class="slate-li "><div style="position:relative">Select either <strong class="slate-bold">REST API or Batch API</strong></div></li><li class="slate-li "><div style="position:relative">Scroll down and click <strong class="slate-bold">Generate a new API key</strong></div></li><li class="slate-li "><div style="position:relative">Give your API key a name</div></li><li class="slate-li "><div style="position:relative">Select the primary use for this key (your email or another user)</div></li><li class="slate-li "><div style="position:relative">Click <strong class="slate-bold">Create</strong></div></li><li class="slate-li "><div style="position:relative">Your new API key will appear in the <strong class="slate-bold">Generated Keys table</strong> under the user name you selected</div></li><li class="slate-li "><div style="position:relative">Make sure the <strong class="slate-bold">Activation</strong> toggle is enabled (switched on)</div></li></ol><Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"style":{"width":"100%","minWidth":"100%"},"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Important</strong>: Only activated API keys can access data. If your key shows as inactive, you'll receive "Invalid API key" errors.</p>
</Callout>
</Step></Steps>

<Image url="https://d24lr4zqs1tgqh.cloudfront.net/d13fccb0-3ff2-48a6-a0df-5eacd16a0b14.jpg" alt="Genrating an API key" caption="" attributes='{"width":"1497px","height":"768px"}'/>

API Keys Management
-------------------

<span style="color:rgb(56, 66, 72)">Admins can create and manage API keys for the entire account.</span>

1.  <span style="color:rgb(56, 66, 72)">Every user can have up to 3 active keys.</span>
    
2.  <span style="color:rgb(56, 66, 72)">There's no expiry date on active keys.</span>
    
3.  <span style="color:rgb(56, 66, 72)">When a user is removed from the account his API key is revoked, there’s also an option of specifically removing users API keys.</span>
    
4.  <span style="color:rgb(56, 66, 72)">Admins can set credit limits per user under each API, for example a user can have 10K on REST API and 10K on Batch API. Only Admins can control limits. The limits are per user and not per key.</span>
    

<Image url="https://d24lr4zqs1tgqh.cloudfront.net/f56e1522-2b1b-4673-aaac-c52c09317226.jpg" alt="Admin panel showing credit limits" caption="" attributes='{"width":"1497px","height":"737px"}'/>

Authentication

### Getting Started

<Callout attributes='{"isFitToPage":true,"dataType":"success","style":{"width":"100%","minWidth":"100%"}}'>
  <p>You need a valid API key to authenticate your requests. If you don't have one yet, follow the instructions in the <a href="68b3660110ed4447ddbb157f/68b5adaf6c50fdd809747571" target="">Authentication</a> section to obtain yours.</p>
</Callout>

To make your first API request, follow these steps:

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title=""><p>Authentication</p><p>Acquire your API key by following the instructions in the Authentication section</p></Step><Step stepNumber="2" title=""><p>Construct the Endpoint Request</p><p>All API requests start with a base URL followed by the specific endpoint you want to access. Refer to the relevant API endpoint in the <a href="689b19656ab85ee91a592926" target="">API Reference </a>for the correct URL structure.</p></Step><Step stepNumber="3" title=""><p>Send the request</p><p>Use your preferred programming language or tool to send an HTTP GET or POST request to the constructed endpoint. Don't forget to include your API key in the request headers.</p></Step><Step stepNumber="4" title=""><p>Receive the Response</p><p>The API will respond with data in JSON format. You can parse this data to extract the insights you need for your analysis</p></Step></Steps><Divider />

### Request Example

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"shell","label":"CURL"}'>
  <CodeLine>curl -X GET "https://api.similarweb.com/v5/website-analysis/websites/traffic-and-engagement" \
  -H "api-key: YOUR_API_KEY" \
  -G \
  -d "domain=nike.com" \
  -d "metrics=visits,bounce_rate,pages_per_visit" \
  -d "granularity=monthly" \
  -d "start_date=2024-10-01" \
  -d "end_date=2024-12-31"</CodeLine>
  <CodeLine>curl -X GET "https://api.similarweb.com/v5/website-analysis/websites/traffic-and-engagement" \
  -H "api-key: YOUR_API_KEY" \
  -G \
  -d "domain=nike.com" \
  -d "metrics=visits,bounce_rate,pages_per_visit" \
  -d "granularity=monthly" \
  -d "start_date=2024-10-01" \
  -d "end_date=2024-12-31"</CodeLine>
</CodeBlock>

### Response Example

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>{
  "meta": {
    "request": {
      "domain": "nike.com",
      "metrics": ["visits", "bounce_rate", "pages_per_visit"],
      "granularity": "monthly",
      "start_date": "2024-10-01",
      "end_date": "2024-12-31",
      "country": "WW"
    },
    "status": "Success",
    "last_updated": "2025-01-15"
  },
  "data": [
    {
      "date": "2024-10-01",
      "visits": 89234567,
      "bounce_rate": 0.2891,
      "pages_per_visit": 4.32
    },
    {
      "date": "2024-11-01", 
      "visits": 94123456,
      "bounce_rate": 0.2734,
      "pages_per_visit": 4.67
    },
    {
      "date": "2024-12-01",
      "visits": 102345678,
      "bounce_rate": 0.2645,
      "pages_per_visit": 4.89
    }
  ]
}</CodeLine>
  <CodeLine>{
  "meta": {
    "request": {
      "domain": "nike.com",
      "metrics": ["visits", "bounce_rate", "pages_per_visit"],
      "granularity": "monthly",
      "start_date": "2024-10-01",
      "end_date": "2024-12-31",
      "country": "WW"
    },
    "status": "Success",
    "last_updated": "2025-01-15"
  },
  "data": [
    {
      "date": "2024-10-01",
      "visits": 89234567,
      "bounce_rate": 0.2891,
      "pages_per_visit": 4.32
    },
    {
      "date": "2024-11-01", 
      "visits": 94123456,
      "bounce_rate": 0.2734,
      "pages_per_visit": 4.67
    },
    {
      "date": "2024-12-01",
      "visits": 102345678,
      "bounce_rate": 0.2645,
      "pages_per_visit": 4.89
    }
  ]
}</CodeLine>
</CodeBlock>
<Divider />

### API Options: Choose the API that best suits your needs

#### REST API

This is what we used in the example above. REST API is perfect for:

*   **Real-time dashboards** requiring up-to-date data
    
*   **Application integration** with on-demand queries
    
*   **Quick analysis** of specific domains or time periods
    
*   **Small to medium data volumes** (single/few domains)
    

#### Batch API

If you're looking for large-scale analysis, this is the API for you. It's ideal for:

*   **Historical analysis** requiring months/years of data
    
*   **Bulk domain research** (hundreds to millions of domains)
    
*   **Data warehouse loading** with direct S3/Snowflake delivery
    
*   **Automated reporting** with scheduled data updates
    

### Example Batch Request

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"shell","label":"CURL"}'>
  <CodeLine>curl -X POST "https://api.similarweb.com/batch/v4/request-report" \
  -H "api-key: YOUR_BATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "report_query": {
      "tables": [{
        "vtable": "traffic_and_engagement",
        "granularity": "monthly", 
        "filters": {
          "domains": ["nike.com", "adidas.com", "underarmour.com"],
          "countries": ["US", "GB", "DE"]
        },
        "metrics": ["visits", "bounce_rate", "pages_per_visit"],
        "start_date": "2020-01-01",
        "end_date": "2024-12-31"
      }]
    }
  }'</CodeLine>
  <CodeLine>curl -X POST "https://api.similarweb.com/batch/v4/request-report" \
  -H "api-key: YOUR_BATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "report_query": {
      "tables": [{
        "vtable": "traffic_and_engagement",
        "granularity": "monthly", 
        "filters": {
          "domains": ["nike.com", "adidas.com", "underarmour.com"],
          "countries": ["US", "GB", "DE"]
        },
        "metrics": ["visits", "bounce_rate", "pages_per_visit"],
        "start_date": "2020-01-01",
        "end_date": "2024-12-31"
      }]
    }
  }'</CodeLine>
</CodeBlock>

Learn more about the differenes between Batch and REST APIs and how to use them by visiting this [guide](68b5f6f7d688be390d72048c/68b5add5d688be390d5e5af0).

<Divider />

### Next Steps

Now that you've made your first successful request:

#### **Recommended Actions**

1.  [**Check your credit balance**](68b5f6f7d688be390d72048c/68b36d640ffb10e152353cfa/68b363d8cca117a351a9c0a1) - Monitor usage and costs
    
2.  [**Browse popular use cases**](68b5cb5a46df0833c3a6612a) - Learn about additional ways to leverage our data
    
3.  [**Understand error handling**](68b5f6f7d688be390d72048c/68b5c0743726dd7779aea825) - Get familiar with the different erros
    

<Divider />

**Questions or Need Help?** Our [support team](https://www.similarweb.com/corp/contact-us/) is ready to help you build successful integrations and maximize the value of your API access.

Making Your First Request

Guides

Available Data

Overview
--------

Similarweb API enables you to integrate digital intelligence data directly into your workflows, tools, and applications. This guide presents common use cases across different industries and technical implementations to help you identify the best approach for your specific needs.

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>

</CardGroup><CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>

</CardGroup><Divider />

Competitive Intelligence and Market Research
--------------------------------------------

### Competitor Benchmarking

Monitor competitor digital performance and compare against your own metrics.

**Key Metrics**:

*   Traffic volume and growth trends
    
*   Traffic source breakdown
    
*   Search keyword performance
    
*   Referring domains and partnerships
    

**Typical Implementation**:

*   Pull monthly competitor metrics
    
*   Compare traffic sources to identify channel opportunities
    
*   Track keyword rankings for strategic search terms
    
*   Monitor technology adoption and site changes
    

**Endpoints/Datasets to Explore**:

*   Website Traffic & Engagement
    
*   Traffic Sources
    
*   Keyword Analysis
    
*   Referrals
    

<Divider />

### Market Research and Industry Analysis

Quantify total addressable market and identify expansion opportunities in new regions / industries.

**Key Metrics**:

*   Traffic volume across market segments
    
*   Geographic distribution of traffic
    
*   Seasonal trends and growth patterns
    
*   Audience and Demographics
    

**Typical Implementation**:

*   Define target market by category or keyword
    
*   Pull a report for all relevant domains
    
*   Aggregate traffic data to calculate total market size
    
*   Identify underserved geographies or segments
    

<Divider />

Digital Marketing Optimization
------------------------------

### SEO and Content Strategy

Discover keyword opportunities and optimize search visibility.

**Key Metrics**:

*   Organic keyword rankings
    
*   Search traffic volume
    
*   Keyword difficulty and opportunity
    
*   Competitor keyword gaps
    

**Typical Implementation**:

*   Query keyword data for your domain and competitors
    
*   Identify high-volume, low-competition keywords
    
*   Track ranking changes for target keywords
    
*   Monitor competitor content strategies
    

<Divider />

### Campaign Performance Analysis

Measure digital campaign effectiveness and optimize media spend.

**Key Metrics**:

*   Traffic volume during campaign periods
    
*   Traffic source changes
    
*   Engagement metrics (bounce rate, pages per visit, duration)
    
*   Geographic distribution of campaign impact
    

**Typical Implementation**:

*   Pull daily traffic metrics during active campaigns
    
*   Compare pre-campaign and during-campaign traffic patterns
    
*   Analyze traffic source mix to measure channel effectiveness
    
*   Calculate engagement lift for campaign periods
    

<Divider />

Business Intelligence and Reporting
-----------------------------------

### Executive Dashboard Creation

Build automated executive dashboards with key digital performance indicators.

**Key Metrics**:

*   Traffic trends over time
    
*   Market share evolution
    
*   Competitive positioning
    
*   Key performance indicators aligned to business goals
    

**Typical Implementation**:

*   Initial data load: Batch API for 12-24 months of history
    
*   Ongoing updates: REST API for current month metrics
    
*   Integrate with BI tools (Looker, Tableau, Power BI)
    
*   Schedule daily or weekly automated refreshes
    

<Divider />

### Automated Client Reporting

Generate scheduled reports for clients or stakeholders.

**Key Metrics**:

*   Customizable based on client needs
    
*   Comparative metrics across time periods
    
*   Benchmarking against competitors or industry standards
    
*   Trend analysis and forecasting
    

**Typical Implementation**:

*   Create templated JSON requests for each client
    
*   Schedule Batch API reports (daily, weekly, monthly)
    
*   Deliver results to S3 or Snowflake
    
*   Generate formatted reports via business intelligence tools
    
*   Set up email notifications for report completion
    

<Divider />

Data Enrichment for SaaS and AI Products
----------------------------------------

Enhance your product offerings with Similarweb digital intelligence data.

**Key Metrics**:

*   Any metrics aligned to your product value proposition
    
*   Real-time competitive data
    
*   Market intelligence overlays
    
*   Enriched company profiles
    

**Typical Implementation**:

*   Embed REST API calls within your application
    
*   Cache frequently requested data to optimize performance
    
*   Implement rate limiting and error handling
    
*   Design user experiences around data freshness and availability
    

<Divider />

### Lead Scoring and Qualification

Enrich CRM data with digital intelligence to prioritize sales opportunities.

**Key Metrics**:

*   Website traffic volume as company size indicator
    
*   Traffic growth as momentum indicator
    
*   Technology stack for solution fit assessment
    
*   Geographic traffic for territory alignment
    

**Typical Implementation**:

*   Monthly Batch API enrichment of entire CRM database
    
*   REST API lookups for new leads as they enter pipeline
    
*   Score leads based on digital metrics
    
*   Route high-potential leads to appropriate sales teams
    

<Divider />

Technology and Partner Analysis
-------------------------------

### Technology Stack Analysis

Identify companies using specific technologies for targeted outreach.

**Key Metrics**:

*   Technology categories (CMS, analytics, e-commerce platforms, etc.)
    
*   Specific technology vendors
    
*   Technology adoption trends
    
*   Technology stack combinations
    

**Typical Implementation**:

*   Define target technologies for your use case
    
*   Request Batch API report with Technologies dataset
    
*   Filter results by technology criteria
    
*   Combine with traffic data for prioritization
    
*   Export prospect lists for sales or marketing activation
    

<Divider />

Investment Research and Due Diligence
-------------------------------------

### Portfolio Company Monitoring

Track the digital performance of companies in your investment portfolio with automated monitoring and reporting.

**Key Metrics**:

*   Traffic trends and visitor engagement
    
*   Market share within industry verticals
    
*   Geographic expansion indicators
    
*   Competitive positioning changes
    

**Typical Implementation**:

*   Schedule daily Batch API reports for all portfolio domains
    
*   Deliver results directly to Snowflake or S3
    
*   Create automated dashboards in Looker or Tableau
    
*   Set up alerts for significant traffic changes or ranking shifts
    

### Pre-Investment Analysis

Conduct comprehensive digital due diligence on potential investment targets.

**Key Metrics**:

*   Historical traffic trends (up to 5 years)
    
*   Traffic source composition and sustainability
    
*   Competitive landscape positioning
    
*   Audience demographics and geography
    

**Typical Implementation**:

*   Schedule daily Batch API reports for all portfolio domains
    
*   Deliver results directly to Snowflake or S3
    
*   Create automated dashboards in Looker or Tableau
    
*   Set up alerts for significant traffic changes or ranking shifts
    

<Divider />

E-commerce and Shopper Intelligence
-----------------------------------

### Competitive Product Monitoring

Track competitor product catalogs, pricing, and performance.

**Key Metrics**:

*   Product-level traffic and engagement
    
*   Pricing trends and promotional activity
    
*   Conversion funnel performance
    
*   On-site search behavior
    

**Typical Implementation**:

*   Schedule Batch API reports for competitor domains
    
*   Analyze Shopper Intelligence and Product datasets
    
*   Track new product launches and catalog changes
    
*   Monitor seasonal patterns and promotional periods
    

<Divider />

### Category and Market Trend Analysis

Identify emerging product categories and shifting consumer demand.

**Key Metrics**:

*   Search keyword trends
    
*   Category traffic growth
    
*   Seasonal demand patterns
    
*   Geographic variations in demand
    

**Typical Implementation**:

*   Define product categories and keywords
    
*   Run historical Batch API analysis
    
*   Identify growth categories and declining segments
    
*   Forecast future demand based on trends
    

<Divider />

Popular Use Cases

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.

<Divider />

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`

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"shell","label":"CURL"}'>
  <CodeLine>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'</CodeLine>
  <CodeLine>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'</CodeLine>
</CodeBlock>

**Response**:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>{
  "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
    }
  ]
}</CodeLine>
  <CodeLine>{
  "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
    }
  ]
}</CodeLine>
</CodeBlock>

**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
    

<Divider />

### 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:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"shell","label":"CURL"}'>
  <CodeLine>curl --location 'https://api.similarweb.com/batch/v4/request-report' \
--header 'api-key: {{API_KEY}}' \
--header 'Content-Type: application/json' \
--request POST \
--data body</CodeLine>
  <CodeLine>curl --location 'https://api.similarweb.com/batch/v4/request-report' \
--header 'api-key: {{API_KEY}}' \
--header 'Content-Type: application/json' \
--request POST \
--data body</CodeLine>
</CodeBlock>

<span style="color:rgb(51, 51, 51);background-color:inherit">Request body (</span>defining tables, metrics, domains, date ranges)<span style="color:rgb(51, 51, 51);background-color:inherit">:</span>

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>body{
  "delivery_information": {
    "response_format": "csv",
    "delivery_method_params": {
      "retention_days": 60
    }
</CodeLine>
  <CodeLine>body{
  "delivery_information": {
    "response_format": "csv",
    "delivery_method_params": {
      "retention_days": 60
    }
</CodeLine>
</CodeBlock>

**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
    

<Divider />

### Full Comparison Table

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"6c97b919-f331-4a6a-b7f9-4594846dd118","title":"Feature"},{"id":"b87dc530-89ae-4fbd-b094-baa522c9a0be","title":"REST API"},{"id":"1d6b8b7d-f257-408b-8ad4-bf2a04f9355b","title":"Batch API"}]'>
  <table-row>
    <table-cell>Request Method</table-cell>
    <table-cell>Synchronous GET requests</table-cell>
    <table-cell>Asynchronous POST job submission</table-cell>
  </table-row>
  <table-row>
    <table-cell>Response Time</table-cell>
    <table-cell>Immediate (seconds)</table-cell>
    <table-cell>Minutes to hours depending on volume</table-cell>
  </table-row>
  <table-row>
    <table-cell>Response Format</table-cell>
    <table-cell>JSON</table-cell>
    <table-cell>CSV</table-cell>
  </table-row>
  <table-row>
    <table-cell>Max Domains Per Request</table-cell>
    <table-cell>Typically 1-100 depending on endpoint</table-cell>
    <table-cell>Up to 1,000,000</table-cell>
  </table-row>
  <table-row>
    <table-cell>Historical Data</table-cell>
    <table-cell>Up to 37 months</table-cell>
    <table-cell>Up to 7 years</table-cell>
  </table-row>
  <table-row>
    <table-cell>Data Granularity</table-cell>
    <table-cell>Daily, Weekly, Monthly</table-cell>
    <table-cell>Daily, Weekly, Monthly</table-cell>
  </table-row>
  <table-row>
    <table-cell>Rate Limits</table-cell>
    <table-cell>10 requests per second</table-cell>
    <table-cell>No rate limits on job submission</table-cell>
  </table-row>
  <table-row>
    <table-cell>Typical Use Case</table-cell>
    <table-cell>Real-time queries, dashboards</table-cell>
    <table-cell>Large-scale analysis, data warehouses</table-cell>
  </table-row>
  <table-row>
    <table-cell>Direct Database Delivery</table-cell>
    <table-cell>No</table-cell>
    <table-cell>Yes (S3, Snowflake, Databricks)</table-cell>
  </table-row>
</Table>

<Divider />
<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Still unsure which API is right for you?</strong></p>
  <p>Contact your Similarweb Account Manager for personalized guidance based on your specific use case and data requirements.</p>
</Callout>

<Divider />

REST API vs Batch API

Learn how Similarweb API data credits work. Calculate usage with our simple formula, track consumption in real-time, and optimize your API spend with transparent pricing.

What Are Data Credits?
----------------------

**Data Credits** are Similarweb's standard unit for API consumption. Each data point (or result) returned in an API response costs a specific number of credits, depending on the endpoint and data type you're requesting.

This model replaces the previous "hits-based" pricing with a more transparent approach:

*   **You pay for what you receive** — you can pay as little as 1 credit or pull 1M credits worth of data. it all depends on how much data you need
    
*   **Pricing is transparent** — every endpoint lists its credit cost upfront
    

<Divider />

How Data Credits Are Calculated
-------------------------------

### The Core Formula

For most Similarweb API endpoints, data credit consumption follows this calculation:

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Total Credits = Domains × Endpoint Base Cost × Granularity Multiplier × Country Filters × Time Range × Results per Domain</p>
</Callout>

**Real World Examples:**

**Example #1:**

*   Request: `visits` for `amazon.com` in `US` for `6 months` (monthly granularity)
    
*   Calculation: `1 domain x 6 months × 1 country × 1 result = 6 credits`
    

**Example #2:**

*   Request: `traffic sources` for `walmart.com` in `US,CA` for `3 months` (weekly granularity)
    
*   Calculation: `8 results x 1 domain x 2 countries x 3 months × 12 weeks = 576 credits`
    

**Let's break down each variable:**

<Table style="width:100%;min-width:100%" colSizes='["234px","472px","503px"]' isHeaderAdded='true' tableHeader='[{"id":"11905c54-3992-456e-a065-68683ddd4851","title":"Variable"},{"id":"5842e101-67a2-4ac5-a2b2-434aef3036f2","title":"Description"},{"id":"faebe61a-fc46-47ac-970a-6fc4f45465fc","title":"Example Values"}]'>
  <table-row>
    <table-cell>Domains</table-cell>
    <table-cell>Number of domains analyzed in your request</table-cell>
    <table-cell>1 domain = multiply by 15 domains = multiply by 5</table-cell>
  </table-row>
  <table-row>
    <table-cell>Endpoint Base Cost</table-cell>
    <table-cell>The base credit cost per data point for that endpoint. This varies by endpoint and is listed in the API documentation.</table-cell>
    <table-cell>Traffic & Engagement: 1 credit per resultKeywords: 0.01 credits per result (1:100 ratio)</table-cell>
  </table-row>
  <table-row>
    <table-cell>Granularity</table-cell>
    <table-cell>How frequently you're requesting data</table-cell>
    <table-cell>Monthly = 1 result per monthWeekly = ~4 results per monthDaily = ~30 results per month</table-cell>
  </table-row>
  <table-row>
    <table-cell>Countries</table-cell>
    <table-cell>Number of countries (or "Worldwide") in your request</table-cell>
    <table-cell>1 country (US) = multiply by 13 countries (US, GB, DE) = multiply by 3</table-cell>
  </table-row>
  <table-row>
    <table-cell>Time Periods</table-cell>
    <table-cell>Number of time periods you're querying based on granularity</table-cell>
    <table-cell>1 month = multiply by 16 months = multiply by 6</table-cell>
  </table-row>
  <table-row>
    <table-cell>Results per Request</table-cell>
    <table-cell>Number of records returned per domain (varies by endpoint)</table-cell>
    <table-cell>Domain visits = 1 resultTop 100 referring sites = 100 results</table-cell>
  </table-row>
</Table>

<Divider />

Credit Consumption by Endpoint Type
-----------------------------------

### Standard Endpoints (1:1 Ratio)

Most endpoints charge **1 credit per data point (result)**.

Examples:

*   Traffic & Engagement metrics (visits, bounce rate, pages per visit)
    
*   Traffic Sources (search, social, referrals)
    
*   Conversion Analysis
    
*   App Analytics (installs, DAU, retention)
    
*   Audience Demographics
    
*   Gen AI Prompt Tracking
    

**Calculation:** `1 data point = 1 credit`

<Divider />

### Keywords Endpoints (1:100 Ratio)

Keyword-related endpoints offer a **discounted rate** due to the large volume of results they return.

**Ratio:** `100 data points = 1 credit`

Examples:

*   Organic Keywords
    
*   Paid Keywords
    
*   Landing Pages (with keywords)
    

**Calculation:** `100 keyword results = 1 credit` `1,000 keyword results = 10 credits`

This makes keyword analysis highly cost-efficient, even when pulling thousands of terms.

<Divider />

FAQ
---

### When am I not charged credits?

You are **not charged** in the following scenarios:

*   **Error responses** (401, 403, 429, or any 4xx/5xx error)
    
*   **No data available** (e.g., domain has insufficient traffic)
    
*   **Free endpoints** (e.g., `/capabilities`, `/describe`, webhooks)
    

This "no data, no charge" policy ensures you only pay for valid, successful data transactions.

<Divider />

### How do I estimate credits before making a request?

1.  **Review endpoint documentation** for base cost and any special rates (like 1:100 for keywords)
    
2.  **Count your variables:**
    
3.  How many domains?
    
4.  How many countries?
    
5.  What time range?
    
6.  How many results per request?
    
7.  **Apply the formula** outlined above
    
8.  **For Batch API:** Use the `/request-validate` endpoint to get exact credit estimates before submitting a report
    

<Divider />

### What happens if I exceed my credit limit?

If you exceed your monthly allowance, additional API requests will be throttled or blocked with a `**429 Too Many Requests**` error. Contact your Account Manager to increase your allocation.

<Divider />

### Do credits roll over to the next month?

No. Unused credits expire at the end of each billing cycle. Plan your usage accordingly and consider spreading large queries across multiple months if needed.

<Divider />

### Can I see a breakdown of my credit usage?

Yes. you can see usage by user in the **Data** **Credits Management dashboard in the Similarweb platform.** Go to the ‘[Check Credit Balance](68b5f6f7d688be390d72048c/68b36d640ffb10e152353cfa/68b363d8cca117a351a9c0a1)’ article to learn more.

<Image url="https://d24lr4zqs1tgqh.cloudfront.net/6a2e6f3f-0cec-4ed9-a4a1-0f6b21bf6f7d.jpg" alt="Data Credits management" caption="" attributes='{"width":"800px","height":"371px"}'/>

<Divider />

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Questions?</strong> Reach out to your Similarweb Account Manager or visit our <a href="https://support.similarweb.com" target="_blank">Support Center</a> for personalized assistance.</p>
</Callout>

API Pricing & Data Credits

### REST API

Here are the various HTML responses you may receive when using Similarweb REST API:

<Table style="width:100%;min-width:100%" colSizes='["105px","476px","423px"]' isHeaderAdded='true' tableHeader='[{"id":"e84e238a-7b7a-4676-a5af-8ccfb261dbf9","title":"Title"},{"id":"96da713b-e2ad-4a6b-92b2-a7f32585ede7","title":"Description"},{"id":"6b79e636-ac0d-4716-8ef8-8519afc54332","title":"Title"}]'>
  <table-row>
    <table-cell>Code</table-cell>
    <table-cell>Description</table-cell>
    <table-cell>Solution</table-cell>
  </table-row>
  <table-row>
    <table-cell>401</table-cell>
    <table-cell>Data not found This error occurs when the requested data cannot be found, which may be due to a faulty or incorrectly entered domain (e.g., 'fsdfsdfdsf.com' or 'CNN.COM' instead of 'cnn.com').</table-cell>
    <table-cell>Double-check the domain name for accuracy. Ensure it is entered correctly and in the proper format (e.g., lowercase for domains and without additional paths like '/sports').</table-cell>
  </table-row>
  <table-row>
    <table-cell>403</table-cell>
    <table-cell>Invalid API key / No Credits This error is triggered when the API key used is invalid or your account has run out of data credits.</table-cell>
    <table-cell>Visit the API management page on the Similarweb platform to verify your API key and check the remaining data credits. Ensure your key is correctly entered and your account has sufficient credits.</table-cell>
  </table-row>
  <table-row>
    <table-cell>429</table-cell>
    <table-cell>Too many requests This error is returned when your account exceeds the permissible limit of requests per second.</table-cell>
    <table-cell>Reduce the frequency of your requests to stay within the limits. Consider spacing out your requests or implementing a rate limiter to avoid this error.</table-cell>
  </table-row>
  <table-row>
    <table-cell>101</table-cell>
    <table-cell>Dates not in range This error indicates that the requested granularity level is not supported by the AP</table-cell>
    <table-cell>Refer to the error message for the dates available within your package’s range and adjust your request accordingly.</table-cell>
  </table-row>
  <table-row>
    <table-cell>102</table-cell>
    <table-cell>Granularity not supported This error indicates an unexpected issue on our server. It's a server-side problem.</table-cell>
    <table-cell>Review the API documentation to verify the supported granularity levels and adjust your request to match these specifications.</table-cell>
  </table-row>
  <table-row>
    <table-cell>103</table-cell>
    <table-cell>Country not available Occurs when you request data for a country not included in your package (e.g., requesting data for Germany when your package only supports the United States).</table-cell>
    <table-cell>Use the 'Check Capabilities' endpoint to confirm the countries included in your package. Ensure your requests are limited to these countries.</table-cell>
  </table-row>
</Table>

### Batch API

Here are the various HTML responses you may receive when using Similarweb Batch API:

<Table style="width:100%;min-width:100%" colSizes='["102px","initial","469px"]' isHeaderAdded='true' tableHeader='[{"id":"1dbb01f3-1ccc-49e2-93f4-6c1e3af4e304","title":"Title"},{"id":"b4121e3d-6af0-430f-add7-5ac069dae174","title":"Description"},{"id":"fa7f9322-ea59-4635-96d8-e96e4db2aa9e","title":"Title"}]'>
  <table-row>
    <table-cell>Code</table-cell>
    <table-cell>Description</table-cell>
    <table-cell>Solution</table-cell>
  </table-row>
  <table-row>
    <table-cell>400</table-cell>
    <table-cell>Bad request This error occurs when certain parameters in your request are incorrect or missing. It's a client-side issue that requires manual correction.</table-cell>
    <table-cell>Review and correct the parameters in your request. For the given example, you need to adjust the start date to a month and year that is within the available data range. Example: Request failed due to invalid start/end date. Historical data for monthly granularity is available as of 2020-07. You have requested 2019-12. Please pick a later date.</table-cell>
  </table-row>
  <table-row>
    <table-cell>401</table-cell>
    <table-cell>Unauthorized Access This error signifies that your API key is invalid or your Similarweb account is not active.</table-cell>
    <table-cell>Ensure that your API key is correctly entered and that your account is active. If you continue to experience issues or need assistance with your API key, please reach out to our support team.</table-cell>
  </table-row>
  <table-row>
    <table-cell>429</table-cell>
    <table-cell>Too Many Requests This error is returned when your account exceeds the limit of allowed pending requests.</table-cell>
    <table-cell>Reduce the frequency of your requests to stay within the limits of your account. Consider reviewing your request strategy or upgrade your account for higher limits if necessary.</table-cell>
  </table-row>
  <table-row>
    <table-cell>500</table-cell>
    <table-cell>Internal error This error indicates an unexpected issue on our server. It's a server-side problem.</table-cell>
    <table-cell>Implement a retry policy. You can either manually resubmit your request after some time or utilize our 'retry' endpoint to automatically resubmit your request. If the error persists, contact our support team for further assistance.</table-cell>
  </table-row>
</Table>

Error Handling & Troubleshooting

API Reference

REST API - NEW ENDPOINTS

The Web Intelligence API provides comprehensive web analytics across desktop and mobile platforms, enabling you to analyze website performance, user engagement, traffic sources, and competitive positioning. Access detailed metrics on visits, page views, bounce rates, marketing channels, and audience behavior.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Historical Data Availability</strong></p>
  <p>Access up to 61 months of historical data, depending on your subscription plan</p>
</Callout>

### What You Can Track

*   **Traffic & Engagement**: Visits, page views, bounce rates, session duration, and user behavior metrics
    
*   **Marketing Channels & Traffic Sources**: Traffic source analysis across organic search, paid search, direct, social, and more
    
*   **Geographic Distribution**: Country-level traffic breakdown and regional performance
    
*   **Similar Sites**: Competitive analysis and market positioning
    
*   **Referrals**: Referral traffic metrics showing visits from referring websites to target domains, including both incoming and outgoing referral data.
    
*   **Popular Pages**: Percentage of total website traffic that each page receives.
    
*   **Website description**: Estimated e-commerce revenue and site meta description analysis
    

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"externalLink":"https://docs.similarweb.com/api-v5/similarweb-api/website-analysis-api/website-performance/get-traffic-and-engagement-metrics-over-time-for-a-specific-website","isNewTab":false}'>
  <title>Website Performance</title>
  <description><p>Website performance Endpoints provide key traffic metrics including ranking, traffic & engagement, marketing channels, geographic regions, Similarsites and more.</p></description>
</Card><CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>

</CardGroup>

Web Intelligence API

Discover the website keywords driving traffic to uncover search opportunities and help build your winning digital marketing strategy. Keyword Analysis provides a deep-dive into any keyword on the web to discover the competitive landscape for any search tervm.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Historical Data Availability</strong></p>
  <p>Historical data available from January 2023, depending on your subscription plan</p>
</Callout>

### What You Can Track

*   **Keyword Metrics**: Search volume, CPC, and difficulty scores
    
*   **Website Keywords**: Click metrics from search results for specific keywords leading to website visits
    
*   **Zero-Click Analysis**: Understanding searches that don't result in clicks
    
*   **SERP Features**: Tracking which features appear for keywords
    
*   **Device-Specific Data**: Desktop vs mobile keyword performance
    
*   **Competitive Positioning**: URLs and positions for organic and paid results
    

### Batch API data tables

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title>SERP Players</title>
  <description><p>The top websites driving search traffic for a specified keyword or custom keyword list.</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title>Keyword Competitors</title>
  <description><p>Provides an overview of keyword or keyword list performance, offering insights such as search volume, click distribution, competition metrics, and other key indicators.</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title>Website Keywords</title>
  <description><p>Returns the keywords driving search clicks for a specified domain.</p></description>
</Card>
</CardGroup>

Search Intelligence API

The Sales Intelligence API delivers programmatic access to company, website, and contact enrichment and search, enabling you to retrieve structured traffic insights, firmographic data and decision-maker details. Access company-level metrics, website performance data, firmographic attributes, and prioritized contact details sorted by seniority, department, and location.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Historical Data Availability</strong></p>
  <p>Access up to 12 months of historical data, depending on your subscription plan</p>
</Callout>

### What You Can Track

*   **Firmographics:** Company name, industry, domain list, HQ details, employee count, revenue, and B2B/B2C classification.
    
*   **Business Metrics:** Online revenue, online transactions, site types, and company industry classification.
    
*   **Website & Company Performance:** Monthly visits, unique visitors, engagement metrics, traffic splits, and MoM/YoY changes.
    
*   **Traffic Sources:** Direct, email, referrals, social, organic search, paid search, and display traffic volumes and trends.
    
*   **Geographic Data:** Top countries, international visits, and traffic distribution by region.
    
*   **Competitive Context:** Top competitor domains.
    
*   **Audience Breakdown:** Age and gender distribution for website audiences.
    
*   **Contact Discovery:** Find contacts by company, job title, seniority, department, and geography.
    
*   **Contact Details:** Names, titles, seniority, departments, locations, LinkedIn URLs, emails, and phone numbers.
    

<Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"externalLink":"https://app.theneo.io/similarweb/api-v5/api-reference/company-analysis-api/lead-enrichment/enrich-website","isNewTab":false}'>
  <title>Lead Enrichment</title>
  <description></description>
</Card><Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"externalLink":"https://docs.similarweb.com/api-v5/similarweb-api/company-analysis-api/contacts/contacts-search","isNewTab":false}'>
  <title>Search Contacts</title>
  <description></description>
</Card><Card attributes='{"isFitToPage":true,"style":{"width":"100%"},"externalLink":"https://docs.similarweb.com/api-v5/similarweb-api/company-analysis-api/contacts/contacts-enrichemnt","isNewTab":false}'>
  <title>Contacts Enrichment</title>
  <description></description>
</Card>

Sales Intelligence API

The App Intelligence API provides comprehensive app intelligence across iOS and Android platforms, enabling you to analyze app performance, user behavior, competitive positioning, and technology adoption.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Historical Data Availability</strong></p>
  <p>Access up to 37 months of historical data, depending on your subscription plan</p>
</Callout>
<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p>You need to have an active <a href="https://www.similarweb.com/packages/app/" target="_self">App Intelligence subscription</a> in order to access this API</p>
</Callout>

### What you can track

*   **App Performance**: Monthly active users, downloads, session data, and engagement metrics
    
*   **User Demographics**: Age and gender breakdowns for app audiences
    
*   **Technology Stack**: SDKs and third-party integrations within apps
    
*   **User Retention**: 30-day retention rates for Android apps
    
*   **App Store Rankings**: Historical placement data for both iOS and Android
    
*   **App Affinity**: User overlap between apps for partnership and competitive analysis
    

### Batch API data tables

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title>App Intelligence</title>
  <description><p>Core app performance metrics, user engagement, and demographics</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title>App Technographics</title>
  <description><p>Technology stack analysis and SDK adoption tracking</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title>App Retention</title>
  <description><p>User retention analysis and app stickiness measurement</p></description>
</Card>
<Card attributes='{"isFitToPage":false,"style":{}}'>
  <title>App Ranking History</title>
  <description><p>App store performance tracking and competitive ranking analysis</p></description>
</Card>
</CardGroup>

App Intelligence API

Retail Intelligence API

The Batch API Web Intelligence Dataset provides comprehensive web analytics across desktop and mobile platforms, enabling you to analyze website performance, user engagement, traffic sources, and competitive positioning. Access detailed metrics on visits, page views, bounce rates, marketing channels, and audience behavior.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Access up to 61 months of historical data, depending on your subscription plan.</p>
</Callout>

### What You Can Track

*   Traffic & Engagement: Visits, page views, bounce rates, session duration, and user behavior metrics
    
*   Marketing Channels & Traffic Sources: Traffic source analysis across organic search, paid search, direct, social, and more
    
*   Geographic Distribution: Country-level traffic breakdown and regional performance
    
*   Similar Sites: Competitive analysis and market positioning\\
    
*   Referrals: Referral traffic metrics showing visits from referring websites to target domains, including both incoming and outgoing referral data.
    
*   Popular Pages: Percentage of total website traffic that each page receives.
    
*   Website description: Estimated e-commerce revenue and site meta description analysis
    


-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Available Tables (vtables)

Batch API

Gen AI Intelligence API

Similarweb MCP

<Image url="https://d24lr4zqs1tgqh.cloudfront.net/91ab0900-27fc-45fe-8416-9afead05481e.jpg" alt="Similarweb MCP Integrations" caption="" attributes='{"width":"1133px","height":"672px"}'/>

### Overview

The **Similarweb Model Context Protocol (MCP) Server** provides seamless access to Similarweb's digital intelligence datasets through a standardized protocol. This integration enables AI assistants like Claude to directly access web analytics, traffic data, and competitive intelligence metrics without custom implementation requirements.

### What is MCP?

The Model Context Protocol (MCP) is an open standard that creates universal connections between AI applications and external data sources. Think of it as a standardized adapter that allows AI assistants like Claude to securely interact with business tools and datasets through natural language requests.

### Getting Started

The Similarweb MCP server is pre-configured and ready to use. The integration provides direct access to Similarweb's data through standardized tool calls.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>MCP Server Endpoint: <strong class="slate-bold">https://mcp.similarweb.com</strong></p>
</Callout>

### What you'll need

*   **Similarweb subscription with API access**: API-only, Business, or Enterprise plans.
    
*   **MCP-compatible client**: Claude, Cursor, Copilot, or other MCP-enabled application
    
*   **API key**: Active Similarweb API key (available in your Account Settings)
    

### Available Integrations

You can integrate the Similarweb MCP server to any AI tool or application supporting MCP. We've prepared a number of guides covering some of the more popular tools :

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>

</CardGroup>

ChatGPT and additional integrations are coming soon!

<Callout attributes='{"isFitToPage":true,"dataType":"success","style":{"width":"100%","minWidth":"100%"}}'>
  <p>If you're interested in connecting Similarweb data to other AI agents and LLM tools through MCP, reach out to Similarweb Support and we'll assist you.</p>
</Callout>

### Data Credits & Usage

MCP uses the same data credits as standard API calls. Credit consumption varies based on your prompts and which data endpoints the AI agent accesses. More complex queries that pull multiple data types will consume more credits accordingly.

### Available Metrics

<Table style="width:100%;min-width:100%" colSizes='["214px","288px","565px"]' isHeaderAdded='true' tableHeader='[{"id":"1fd1df8d-f590-4e66-91eb-ce19c06dd822","title":"Tool Name"},{"id":"9b663ea0-1aaf-497d-98f0-b334194f7b47","title":"Description"},{"id":"faf3d7ff-73f4-4190-a489-d558afca77f4","title":"Available Metrics"}]'>
  <table-row>
    <table-cell>Traffic and Engagement</table-cell>
    <table-cell>Get traffic and engagement metrics over time for a specific website</table-cell>
    <table-cell>visits, average_visit_duration, pages_per_visit, bounce_rate, page_views, unique_visitors, new_users, returning_users</table-cell>
  </table-row>
  <table-row>
    <table-cell>Traffic Sources</table-cell>
    <table-cell>Get traffic metrics broken down by marketing channels (direct, display ads, mail, organic search, paid search, referrals, and social)</table-cell>
    <table-cell>visits, average_visit_duration, pages_per_visit, bounce_rate</table-cell>
  </table-row>
  <table-row>
    <table-cell>Website Rank</table-cell>
    <table-cell>Get website rank over time for a specific website</table-cell>
    <table-cell>country_rank, category, category_rank</table-cell>
  </table-row>
  <table-row>
    <table-cell>Subdomains</table-cell>
    <table-cell>Get subdomain traffic share data for a website</table-cell>
    <table-cell>subdomain, share</table-cell>
  </table-row>
  <table-row>
    <table-cell>Similar Sites</table-cell>
    <table-cell>Get similar websites for a specific domain, showing domains with similar audience and traffic patterns</table-cell>
    <table-cell>rank, affinity, has_adsense</table-cell>
  </table-row>
  <table-row>
    <table-cell>Referrals</table-cell>
    <table-cell>Get incoming or outgoing referral websites for a specific website, showing traffic sources or destinations</table-cell>
    <table-cell>share, change</table-cell>
  </table-row>
  <table-row>
    <table-cell>Audience Interests</table-cell>
    <table-cell>Get audience-interests (also-visited websites) for a specific website</table-cell>
    <table-cell>affinity, overlap, pop_change, has_adsense, domain</table-cell>
  </table-row>
  <table-row>
    <table-cell>Audience Overlap</table-cell>
    <table-cell>Get audience overlap data by comparing between 2 to 5 websites</table-cell>
    <table-cell>overlap, union</table-cell>
  </table-row>
  <table-row>
    <table-cell>Deduplicated Audience</table-cell>
    <table-cell>Get deduplicated audience metrics for a specific website</table-cell>
    <table-cell>total_deduplicated_audience, desktop_only_audience_share, desktop_only_audience_visitors, mobile_web_only_audience_share, mobile_web_only_audience_visitors, desktop_and_mobile_web_audience_share, desktop_and_mobile_web_audience_visitors</table-cell>
  </table-row>
  <table-row>
    <table-cell>Leading Folders</table-cell>
    <table-cell>Get leading folders traffic share data for a specific website</table-cell>
    <table-cell>folder, share, change</table-cell>
  </table-row>
  <table-row>
    <table-cell>Popular Pages</table-cell>
    <table-cell>Get popular pages metrics for a specific website</table-cell>
    <table-cell>share, change</table-cell>
  </table-row>
  <table-row>
    <table-cell>PPC Spend</table-cell>
    <table-cell>Get money spent monthly on paid search advertising for a specific website</table-cell>
    <table-cell>ppc_spend</table-cell>
  </table-row>
  <table-row>
    <table-cell>Segment Traffic and Engagement</table-cell>
    <table-cell>Get traffic and engagement metrics over time for a specific segment of a website</table-cell>
    <table-cell>visits, bounce_rate, page_views, average_visit_duration, pages_per_visit, share, unique_visitors</table-cell>
  </table-row>
  <table-row>
    <table-cell>Segment Traffic Sources</table-cell>
    <table-cell>Get segment traffic and engagement metrics over time for a specific segment of a website, broken down by marketing channels</table-cell>
    <table-cell>visits, bounce_rate, page_views, average_visit_duration, pages_per_visit</table-cell>
  </table-row>
  <table-row>
    <table-cell>Ad Networks</table-cell>
    <table-cell>Get incoming or outgoing ad networks data for a specific website</table-cell>
    <table-cell>share, visits</table-cell>
  </table-row>
  <table-row>
    <table-cell>Geography</table-cell>
    <table-cell>Get traffic and engagement metrics over time for a specific website, broken down by country</table-cell>
    <table-cell>country, country_name, rank, share, visits, average_visit_duration, pages_per_visit, bounce_rate</table-cell>
  </table-row>
  <table-row>
    <table-cell>Technologies</table-cell>
    <table-cell>Get current technologies used by a specific domain</table-cell>
    <table-cell>sub_category, pricing_model, description, first_seen_date</table-cell>
  </table-row>
  <table-row>
    <table-cell>Demographics</table-cell>
    <table-cell>Get demographics metrics for a specific website</table-cell>
    <table-cell>age_18_to_24_share, age_25_to_34_share, age_35_to_44_share, age_45_to_54_share, age_55_to_64_share, age_65_plus_share, male_share, female_share</table-cell>
  </table-row>
  <table-row>
    <table-cell>Traffic by Demographics</table-cell>
    <table-cell>Get traffic metrics for a certain demographics group</table-cell>
    <table-cell>share, pages_per_visit, bounce_rate, visit_duration</table-cell>
  </table-row>
</Table>

<Table style="width:100%;min-width:100%" colSizes='["216px","293px","550px"]' isHeaderAdded='true' tableHeader='[{"id":"fbef2872-e339-4cfb-8188-528d74ef6623","title":"Tool Name"},{"id":"6e436e69-8540-475b-872b-c5059ab5a668","title":"Description"},{"id":"275f5bfa-a0a6-4eaf-ad76-46ddaeb4b0e3","title":"Available Metrics"}]'>
  <table-row>
    <table-cell>SERP Players</table-cell>
    <table-cell>The top websites driving search traffic for a specified keyword or custom keyword list</table-cell>
    <table-cell>site, domain name, clicks, traffic share, serp_features, position, top_url</table-cell>
  </table-row>
  <table-row>
    <table-cell>SERP Clicks</table-cell>
    <table-cell>Clicks trend over time for each website from the top websites for their keyword or keyword groups</table-cell>
    <table-cell>site, domain name, clicks, traffic share, serp_features, position, top_url</table-cell>
  </table-row>
  <table-row>
    <table-cell>Keywords Overview</table-cell>
    <table-cell>Provides an overview of keyword or keyword list performance</table-cell>
    <table-cell>search volume, click distribution, competition metrics, and other key indicators</table-cell>
  </table-row>
  <table-row>
    <table-cell>Website Keywords</table-cell>
    <table-cell>Returns the keywords driving search clicks for a specified domain.</table-cell>
    <table-cell>keyword, clicks, traffic_share, difficulty, competition, primary_intent, secondary_intent, volume, cpc, zero_clicks_share, position, serp_features, top_url</table-cell>
  </table-row>
</Table>

<Table style="width:100%;min-width:100%" colSizes='["217px","297px","541px"]' isHeaderAdded='true' tableHeader='[{"id":"988200a9-7f6f-4172-bb5a-6808dfe57086","title":"Tool Name"},{"id":"ef9acf46-ba1d-4502-8527-3788cefb93d4","title":"Description"},{"id":"a5c7c7d2-45c1-4b43-a90a-9f213128c1b7","title":"Available Metrics"}]'>
  <table-row>
    <table-cell>App Install Penetration</table-cell>
    <table-cell>Get the percentage of devices in a specific country with the app installed</table-cell>
    <table-cell>installs %</table-cell>
  </table-row>
  <table-row>
    <table-cell>App Store Rank</table-cell>
    <table-cell>Get app store rank over time for a specific mobile app</table-cell>
    <table-cell>Android and iOS store ranks</table-cell>
  </table-row>
  <table-row>
    <table-cell>App Details</table-cell>
    <table-cell>Get detailed information about a mobile app by its ID</table-cell>
    <table-cell>title, image, publisher, price, main category, main category ID, and rating</table-cell>
  </table-row>
</Table>

<Callout attributes='{"isFitToPage":true,"dataType":"error","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Important Disclaimers</strong></p>
  <p>AI-generated insights and recommendations based on Similarweb MCP-delivered data or any AI-generated outputs may be:</p>
  <ul class="slate-ul "><li class="slate-li "><div style="position:relative"><strong class="slate-bold">Incomplete, inaccurate, subject to omissions, or contextually limited</strong> based on the specific request parameters, the scope of data provided, or system behavior.</div></li><li class="slate-li "><div style="position:relative"><strong class="slate-bold">Subject to AI interpretation</strong> and may not reflect all nuances, limitations, or the evolving nature of the underlying data.</div></li></ul>
  <p>Use of the MCP Server and any AI-generated outputs is at the user’s sole risk. Similarweb does not guarantee and expressly disclaims all warranties, including accuracy, completeness, reliability, fitness for a particular purpose, or merchantability of MCP-delivered data or any AI-generated outputs or recommendations and shall not be responsible or liable, for any business outcomes, decisions, actions, losses, damages, or other consequences arising out of or relating to reliance upon MCP-delivered data or any AI-generated outputs or recommendations.</p>
</Callout>

Access Similarweb's digital data directly inside various AI tools using our MCP Server:

<CardGroup attributes='{"isFitToPage":true,"style":{"width":"100%","minWidth":"540px"}}'>

</CardGroup>

MCP Integrations

API Integrations

Overview

Data Visualization

Productivity & Analytics

CRM & Marketing

Cloud & Data Platforms

Webhooks

Support and FAQ

Find quick answers to the most common questions about Similarweb API.

Getting Started
---------------

### What is Similarweb API?

Similarweb API provides programmatic access to the world's leading digital intelligence data. You can integrate traffic, engagement, search, app, and audience data directly into your applications, dashboards, and data pipelines.

### How do I get an API key?

Admin users can generate API keys directly from the Similarweb platform:

1.  Log in to your Similarweb account
    
2.  Navigate to **Settings** > **Account**
    
3.  Under **API**, select **Standard API** or **Batch API**
    
4.  Click **Generate a new API key**
    
5.  Ensure the key is activated (toggle should be ON)
    

Only account admins can generate new API keys. Learn more in our [Authentication Guide](68b3660110ed4447ddbb157f/68b5adaf6c50fdd809747571).

### What's the difference between REST API and Batch API?

**REST API** is ideal for:

*   Real-time data retrieval (latency under 1 second)
    
*   Small to medium-scale queries (1-50 domains)
    
*   Interactive applications and dashboards
    
*   Up to 10 requests per second
    

**Batch API** is optimized for:

*   Large-scale analysis (up to 1 million domains)
    
*   Historical data exports (up to 5 years)
    
*   Scheduled data pipelines
    
*   Direct integration with data warehouses (Snowflake, S3, Databricks)
    
*   20-40% cost savings on large datasets
    

[Read our detailed comparison →](68b5f6f7d688be390d72048c/68b36d640ffb10e152353cfa)

<Divider />

Pricing & Credits
-----------------

### How does data credits pricing work?

Data credits are Similarweb's currency—you pay for the actual data you receive, not just API calls.

**Example:**

*   10 domains × 5 metrics × 12 months × 2 countries = 1,200 data credits
    

Each endpoint shows its pricing in the API Reference. Use the **Request Validate** endpoint to estimate costs before running large queries.

### Can I get a refund if I make a mistake?

Unfortunately, data credits cannot be refunded. However:

*   **No charges apply** if you encounter errors (401, 403, 429, 101, 102, 103)
    
*   **Zero-value responses** are not charged
    
*   You can use the `/request-validate` endpoint (Batch API) to preview costs before executing
    

### How do I check my remaining credits?

**On the Similarweb Platform:**

1.  Go to **Settings** > **Account** > **Credit Management**
    
2.  View remaining credits for both REST and Batch APIs
    

**Via API:**

*   **REST API:** Call the `/capabilities` endpoint (free)
    
*   **Batch API:** Call the `/user-capabilities` endpoint (free)
    
*   **User-level:** Call `/user-capabilities` for allocated allowances
    

### Do credits expire?

Yes, data credits typically reset monthly. Check your subscription terms or contact your Account Manager for details on your specific plan.

<Divider />

Rate Limits & Performance
-------------------------

### What are the rate limits?

**REST API:**

*   Maximum of **10 requests per second** per account
    
*   Exceeding this limit returns a `429: Too Many Requests` error
    

**Batch API:**

*   Maximum of **20 pending requests** per user
    
*   Reports can process millions of data points in a single request
    

### What happens if I exceed rate limits?

You'll receive an HTTP `429` error. To avoid this:

*   Implement rate limiting in your integration (cap at 10 RPS)
    
*   Add delays between requests
    
*   For large-scale needs, switch to Batch API
    

**No data credits are charged** when you receive rate limit errors.

### Can I increase my rate limits?

Enterprise customers can request higher rate limits. Contact your Account Manager to discuss custom solutions for high-volume use cases.

<Divider />

Data & Coverage
---------------

### How often is data updated?

*   **Daily data:** Released within 72 hours (most endpoints)
    
*   **Monthly data:** Released by the 10th of the following month
    
*   **Real-time data:** Not available; Similarweb measures actual user behavior, not live traffic
    

### What countries are supported?

Similarweb covers **190+ countries** using standard ISO 3166-1 country codes.

Use `WW` for worldwide data or two-letter codes like `US`, `GB`, `JP`.

Check your package's country availability:

*   Call the `/capabilities` endpoint
    
*   View the [Country Codes reference](#)
    

### Why does my domain return "data not found"?

Common reasons:

1.  **Domain format error** — Use `example.com`, not `www.example.com` or `https://example.com`
    
2.  **Case sensitivity** — Use lowercase (e.g., `cnn.com` not `CNN.COM`)
    
3.  **Insufficient traffic** — The domain may not meet minimum traffic thresholds
    
4.  **Recent domain** — New websites need time to accumulate data
    

### What is "main\_domain\_only"?

This parameter controls subdomain inclusion:

*   `true` — Analyze only the main domain (e.g., `google.com`)
    
*   `false` (default) — Include all subdomains (e.g., `maps.google.com`, `docs.google.com`)
    

<Divider />

Technical Questions
-------------------

### Can I use the API with Excel, Google Sheets, or Looker?

Yes! Similarweb offers native integrations:

*   **Excel:** Install the Similarweb Add-in from Microsoft AppSource
    
*   **Google Sheets:** Install the Similarweb Add-on from Google Workspace Marketplace
    
*   **Looker Studio:** Use the Similarweb Website Analysis Connector
    

These integrations allow non-technical teams to pull data without writing code. [Learn more about integrations →](#)

### Can I schedule automated data refreshes?

**REST API:**

*   Use task schedulers (cron jobs, Windows Task Scheduler)
    
*   Implement webhooks for data availability notifications
    
*   Use Google Sheets Apps Script for timed refreshes
    

**Batch API:**

*   Schedule batch jobs via your data pipeline
    
*   Subscribe to webhooks for automatic triggers
    
*   Integrate with Snowflake for scheduled table updates
    

### How do I handle pagination?

Many aggregated endpoints support pagination with these parameters:

*   `limit` — Number of results per page (default: 100, max varies by endpoint)
    
*   `offset` — Page number (starts at 1)
    
*   `sort` — Order results by a specific metric
    
*   `asc` — Sort direction (true = ascending, false = descending)
    

<Divider />

Security & Authentication
-------------------------

### Is my API key secure?

Protect your API key like a password:

*   Never commit keys to public repositories
    
*   Use environment variables in your code
    
*   Rotate keys periodically
    
*   Deactivate unused keys in your account settings
    

### Can I regenerate my API key?

Yes, admins can:

1.  Deactivate the old key
    
2.  Generate a new key
    
3.  Update your integrations with the new key
    

Old keys stop working immediately upon deactivation.

### Can I restrict API key usage?

API keys are tied to your Similarweb account and inherit the account's data access permissions. For more granular controls, contact your Account Manager about user-level allowances.

<Divider />

Error Handling
--------------

### Common error codes and solutions

**Important:** No credits are charged for error responses.

[See full error code guide →](68b5f6f7d688be390d72048c/68b5c0743726dd7779aea825)

<Divider />

Products & Integrations
-----------------------

### What's the difference between the API and the Similarweb platform?

The **Similarweb Platform** is a web-based UI for ad-hoc analysis and reporting.

The **Similarweb API** provides programmatic access for:

*   Automation and scale
    
*   Integration with your own tools and systems
    
*   Custom analysis pipelines
    
*   Data warehouse connectivity
    

Both access the same underlying datasets.

### Can I use the API to build a product for external users?

Yes! Similarweb offers **OEM licensing** for product builders who want to embed digital intelligence into their own software.

Contact [**oem@similarweb.com**](https://mailto:oem@similarweb.com) to discuss licensing terms.

### Are there SDKs or client libraries available?

Similarweb API follows standard REST principles, making it compatible with any HTTP client.

<Divider />

Learning & Support
------------------

### Where can I find code examples?

*   **API Reference:** Each endpoint includes request/response examples
    
*   **Getting Started Guides:** Step-by-step tutorials
    
*   **Integration Guides:** Platform-specific examples (Excel, Looker, etc.)
    
*   **Developer Blog:** Use case deep-dives and best practices
    

Contact your Account Manager to schedule a session.

### Can I test the API before subscribing?

You'll need an active subscription with API access in order to use our API.

<Divider />

Country Codes

#### This endpoint provides a detailed overview of your account's current capabilities based on your subscription package.

**The endpoint returns the following:**

*   Remaining data credits at the account level.
    
*   Available country filters.
    
*   Accessible historical data.
    

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Price: </strong>There is no cost in terms of data credits for querying this endpoint. It's free to use as part of your account management.</p>
</Callout>

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

**Endpoint URL:** https://api.similarweb.com/capabilities?api\_key={{YOUR\_SIMILARWEB\_API\_KEY}}

Replace {{YOUR\_SIMILARWEB\_API\_KEY}} with your actual API key.

**Parameters:**

api\_key: Your unique Similarweb API key. Enter it without the {{ }} brackets.

**Example Request:**

`curl --location -g 'https://api.similarweb.com/capabilities?api_key={{YOUR_SIMILARWEB_API_KEY}}'`

**Example Response:**

The response provides a JSON object detailing your available credits, data access ranges, and countries. Here's a truncated example:

<CodeBlock attributes='{"isFitToPage":false,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>{</CodeLine>
  <CodeLine>  "remaining_hits": 24763083,</CodeLine>
  <CodeLine>  "web_desktop_data": {</CodeLine>
  <CodeLine>    "snapshot_interval": {</CodeLine>
  <CodeLine>      "start_date": "2020-10-01",</CodeLine>
  <CodeLine>      "end_date": "2023-10-31"</CodeLine>
  <CodeLine>    },</CodeLine>
  <CodeLine>    "countries": [</CodeLine>
  <CodeLine>      {"code": "AR", "name": "Argentina"},</CodeLine>
  <CodeLine>      {"code": "AU", "name": "Australia"},</CodeLine>
  <CodeLine>      // Additional countries...</CodeLine>
  <CodeLine>    ]</CodeLine>
  <CodeLine>  },</CodeLine>
  <CodeLine>  // Additional data categories such as web_mobile_data, app_data...</CodeLine>
  <CodeLine>} </CodeLine>
</CodeBlock>

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Note</strong></p>
  <p>The response includes comprehensive data such as available countries and data ranges for web desktop data, web mobile data, app data, and app engagement data, with corresponding start and end dates for each category.</p>
</Callout>

--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Check Capabilities

Similarweb API empowers companies to accelerate and scale their analysis workflow by providing market-leading insights across millions of websites - transforming the way business-critical decisions are made.

We continuously work to optimize the performance and stability of our API. This is why our system limits the number of requests users can make to 10 requests per second. This ensures we can:

⌛ Reduce the risk of downtimes ⏱ Minimize latency 📈 Enhance system stability

Users exceeding 10 requests per second may receive an HTTP code error: 429 “Too many requests”.

In order to avoid this, you may need to adjust your API integration with a cap of 10 requests per second. Alternatively, speak to us to hear about our Batch API - optimized for bulk data reports of up to 1 million domains at once.

For more information, or to get assistance from one of our technical specialists, reach out to us [here](https://www.similarweb.com/corp/contact-support/).

Rate limits

#### Returns the remaining data credits for users with an allocated allowance.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Price:</strong> Querying this endpoint does not cost any credits.</p>
</Callout>

**Endpoint URL:**

[https://api.similarweb.com/user-capabilities?api\_key={{similarweb\_api\_key}}](https://api.similarweb.com/user-capabilities?api_key=%7B%7Bsimilarweb_api_key%7D%7D)

Replace {{similarweb\_api\_key}} with your actual API key.

**Parameters**:

api\_key: Your unique Similarweb API key. Enter it without the {{ }} brackets.

**Example Request:**

`curl --location -g 'https://api.similarweb.com/user-capabilities?api_key={{similarweb_api_key}}'`

**Example Response:**

The response provides a JSON object detailing the current data credit allowance and remaining credits. Here's an example:

`{"allowance": 10000, "user_remaining": 4989 }`

Usage Tracking

Retail Intelligence endpoints (/v5/shopper-*).

Retail Intelligence

Assets

Brand Search

**Search Brands**

**Possible output fields:**

- `brand`: Display name of the brand
- `units_sold`: Average number of units sold over the last 3 complete months

**Constraints:**

- `domain` and `search_term` are required
- `granularity` supports `monthly` only

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Search Brands

Returns time-series data of competitor brands with the highest audience overlap, ranked by affinity to a given brand within a category.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-analysis/brands/top-competitors` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-analysis/brands/top-competitors/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `competitor_brand`: Name of the competitor brand
- `affinity`: Audience affinity score between the queried brand and the competitor
- `views`: Number of product views for the competitor brand
- `units_sold`: Number of units sold by the competitor brand
- `revenue`: Revenue generated by the competitor brand (local currency)
- `revenue_in_usd`: Revenue generated by the competitor brand (USD)
- `competitive_overlap`: Degree of audience overlap between the queried brand and the competitor
- `brand_share_of_competition`: The queried brand's share relative to the competitor

**Constraints:**

- `domain`, `category`, and `brand` are required
- `granularity` supports `monthly` or `weekly`
- Supports pagination (`limit`, `offset`, `sort`, `asc`)

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Brands Top Competitors

Category Search

**Search Categories**

**Possible output fields:**

- `category_id`: Unique identifier for the category
- `category_name`: Display name of the category
- `category_path`: Full path of the category in the hierarchy (e.g., `Books > Fiction > Mystery`)
- `category_depth`: Depth level of the category in the hierarchy (0 \= root)
- `parent_category_id`: Unique identifier of the parent category
- `parent_category_name`: Display name of the parent category

**Constraints:**

- `domain` and `search_term` are required
- `granularity` supports `monthly` only
- Higher `children_depth` values may significantly increase response size

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Search Categories

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

/v5/shopper-analysis/categories/search/describe

On-site Search

Returns time-series on-site search clicks share data for a brand within a category.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-on-site-search/brands/clicks/share` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-on-site-search/brands/clicks/share/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `brand`: Name of the brand
- `brand_total_clicks`: Total number of clicks on the brand's products within the category
- `brand_paid_clicks`: Number of paid clicks on the brand's products
- `brand_organic_clicks`: Number of organic clicks on the brand's products
- `category_paid_clicks`: Total paid clicks across all brands in the category
- `category_total_clicks`: Total clicks across all brands in the category
- `category_organic_clicks`: Total organic clicks across all brands in the category
- `brand_total_share_in_category`: Brand's share of total clicks in the category
- `brand_paid_share_in_category`: Brand's share of paid clicks in the category
- `brand_organic_share_in_category`: Brand's share of organic clicks in the category
- `branded_ratio`: Ratio of branded vs. non-branded search clicks for the brand

**Constraints:**

- `domain`, `category`, and `brand` are required
- `granularity` supports `monthly` or `weekly`

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Brand Clicks Share

Returns list of top on-site search keywords for a brand, ranked by selected metrics.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-on-site-search/brands/top-keywords` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-on-site-search/brands/top-keywords/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `keyword`: The search keyword
- `branded_type`: Whether the keyword is branded or non-branded
- `associated_brand`: The brand most associated with this keyword
- `brand_clicks`: Total clicks on the brand from this keyword
- `brand_organic_clicks`: Organic clicks on the brand from this keyword
- `brand_paid_clicks`: Paid clicks on the brand from this keyword
- `keyword_total_clicks`: Total clicks across all brands for this keyword
- `brand_price_numerator`: Numerator used to calculate the brand's average price
- `brand_price_denominator`: Denominator used to calculate the brand's average price
- `brand_average_price`: Average price of the brand's products for this keyword
- `brand_organic_ratio`: Brand's share of organic clicks for this keyword
- `brand_paid_ratio`: Brand's share of paid clicks for this keyword
- `brand_share`: Brand's overall share of clicks for this keyword
- `others_average_price`: Average price of competing brands' products for this keyword
- `total_price_numerator`: Numerator used to calculate the overall average price
- `total_price_denominator`: Denominator used to calculate the overall average price

**Constraints:**

- `domain`, `category`, and `brand` are required
- `granularity` supports `monthly` or `weekly`
- Supports pagination (`limit`, `offset`, `sort`, `asc`)

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Brand Top Keywords

Returns time-series on-site search performance metrics for a category over the selected time period.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-on-site-search/categories/performance` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-on-site-search/categories/performance/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `category_id`: Unique identifier of the category
- `category_paid_clicks`: Total paid clicks in the category
- `category_organic_clicks`: Total organic clicks in the category
- `brand_organic_clicks`: Organic clicks attributed to a specific brand in the category
- `brand_paid_clicks`: Paid clicks attributed to a specific brand in the category
- `total_clicks`: Total clicks (paid \+ organic) in the category
- `search_volume`: Total number of on-site search queries in the category

**Constraints:**

- `domain` and `category` are required
- `granularity` supports `monthly` or `weekly`

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Category Performance

Returns list of top on-site search keywords in a category, ranked by selected metrics.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-on-site-search/categories/top-keywords` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-on-site-search/categories/top-keywords/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `keyword`: The search keyword
- `associated_brand`: The brand most associated with this keyword
- `branded_type`: Whether the keyword is branded or non-branded
- `keyword_total_clicks`: Total clicks across all products for this keyword
- `keyword_organic_clicks`: Organic clicks for this keyword
- `keyword_paid_clicks`: Paid clicks for this keyword
- `keyword_average_price`: Average product price for this keyword
- `top_brand_organic_ratio`: Top brand's share of organic clicks for this keyword
- `top_brand_paid_ratio`: Top brand's share of paid clicks for this keyword
- `top_brand_share`: Top brand's overall share of clicks for this keyword
- `top_brand`: The brand with the highest click share for this keyword
- `top_brand_clicks`: Total clicks for the top brand on this keyword
- `top_brand_organic_clicks`: Organic clicks for the top brand on this keyword
- `top_brand_paid_clicks`: Paid clicks for the top brand on this keyword

**Constraints:**

- `domain` and `category` are required
- `granularity` supports `monthly` or `weekly`
- Supports pagination (`limit`, `offset`, `sort`, `asc`)

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Category Top Keywords

/v5/shopper-on-site-search/describe

Returns time-series on-site search performance data for a specific keyword on Amazon.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-on-site-search/keywords/performance` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-on-site-search/keywords/performance/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `clicks`: Total clicks for this keyword
- `paid_clicks`: Paid clicks for this keyword
- `organic_clicks`: Organic clicks for this keyword
- `search_volume`: Total number of searches for this keyword
- `associated_brand`: The brand most associated with this keyword
- `top_brand`: The brand with the highest click share for this keyword
- `top_brand_share`: Top brand's share of total clicks for this keyword

**Constraints:**

- `domain` and `keyword` are required
- `granularity` supports `monthly` or `weekly`

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Keyword Performance

Returns list of top brands for an on-site search keyword, ranked by selected metrics.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-on-site-search/keywords/top-brands` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-on-site-search/keywords/top-brands/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `brand`: Name of the brand
- `clicks`: Total clicks for this brand on the keyword
- `search_volume`: Total number of searches for this keyword
- `keyword_organic_clicks`: Total organic clicks across all brands for this keyword
- `keyword_paid_clicks`: Total paid clicks across all brands for this keyword
- `brand_clicks`: Total clicks attributed to this brand for the keyword
- `brand_organic_clicks`: Organic clicks attributed to this brand for the keyword
- `brand_paid_clicks`: Paid clicks attributed to this brand for the keyword

**Constraints:**

- `domain` and `keyword` are required
- `granularity` supports `monthly` or `weekly`
- Supports pagination (`limit`, `offset`, `sort`, `asc`)

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Keyword Top Brands

Returns list of top products for an on-site search keyword, ranked by selected metrics.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-on-site-search/keywords/top-products` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-on-site-search/keywords/top-products/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `asin`: Amazon Standard Identification Number of the product
- `name`: Product name
- `brand`: Brand name of the product
- `category_id`: Category ID the product belongs to
- `category_name`: Category name the product belongs to
- `clicks`: Total clicks on this product for the keyword
- `organic_clicks`: Organic clicks on this product for the keyword
- `paid_clicks`: Paid clicks on this product for the keyword
- `organic_rank`: Organic search rank of the product for this keyword
- `page_one_rate`: Percentage of time the product appears on page one
- `relevancy`: Relevancy score of the product for this keyword
- `units_sold`: Number of units sold via this keyword
- `revenue`: Revenue from this product via this keyword (local currency)
- `revenue_in_usd`: Revenue from this product via this keyword (USD)
- `views`: Number of product page views
- `price`: Product price as a string
- `price_value`: Product price as a numeric value
- `price_last_scraped_date`: Date when the price was last recorded
- `average_unit_price`: Average selling price per unit
- `rating`: Product rating score
- `reviews`: Number of customer reviews
- `thumbnail`: URL of the product thumbnail image
- `parent_asin`: ASIN of the parent product (for variants)
- `related_keywords`: List of related keywords for this product
- `best_seller_rank`: Product's best seller rank
- `best_seller_category_id`: Category ID in which the product is a best seller
- `best_seller_category_name`: Category name in which the product is a best seller
- `prime`: Whether the product is available with Amazon Prime
- `amazon_brand`: Whether the product is an Amazon private label brand
- `amazon_exclusive`: Whether the product is exclusive to Amazon
- `amazons_choice_keyword`: Keyword for which this product has the "Amazon's Choice" badge
- `small_business`: Whether the product is from a small business seller
- `climate_pledge_friendly`: Whether the product has the Climate Pledge Friendly badge

**Constraints:**

- `domain` and `keyword` are required
- `granularity` supports `monthly` or `weekly`
- Supports pagination (`limit`, `offset`, `sort`, `asc`)

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Keyword Top Products

Returns list of top on-site search keywords for a product (ASIN), ranked by selected metrics.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-on-site-search/products/top-keywords` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-on-site-search/products/top-keywords/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `keyword`: The search keyword
- `associated_brand`: The brand most associated with this keyword
- `branded_type`: Whether the keyword is branded or non-branded
- `organic_rank`: Organic search rank of the product for this keyword
- `relevancy`: Relevancy score of the product for this keyword
- `share_of_clicks`: Product's share of total clicks for this keyword
- `keyword_clicks`: Total clicks across all products for this keyword
- `product_organic_clicks`: Organic clicks on this product for this keyword
- `product_paid_clicks`: Paid clicks on this product for this keyword
- `search_volume`: Total number of searches for this keyword
- `reach`: Estimated number of unique users reached by this keyword
- `product_clicks`: Total clicks on this product for this keyword

**Constraints:**

- `domain` and `asin` are required
- ASIN must be exactly 10 uppercase alphanumeric characters (e.g., `B0DLFVP6YM`)
- ASINs are domain-specific and cannot be used across different Amazon domains
- `granularity` supports `monthly` or `weekly`
- Supports pagination (`limit`, `offset`, `sort`, `asc`)

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Product Top Keywords

Sales Performance

Returns time-series sales performance data for a specific brand within a category on Amazon.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-sales/brands/sales-performance` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-sales/brands/sales-performance/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `total_views`: Total product page views for the brand in the category
- `units_sold_first_party`: Units sold directly by Amazon (1P)
- `units_sold_third_party`: Units sold by third-party sellers (3P)
- `units_sold`: Total units sold (1P \+ 3P)
- `revenue_first_party`: Revenue from 1P sales (local currency)
- `revenue_third_party`: Revenue from 3P sales (local currency)
- `revenue`: Total revenue (local currency)
- `num_asins`: Number of distinct ASINs for the brand in the category
- `category_total_views`: Total views across all brands in the category
- `category_units_sold`: Total units sold across all brands in the category
- `category_revenue`: Total revenue across all brands in the category (local currency)
- `conversion`: Conversion rate (units sold per view)
- `units_sold_share`: Brand's share of total units sold in the category
- `total_views_share`: Brand's share of total views in the category
- `revenue_share`: Brand's share of total revenue in the category
- `revenue_in_usd`: Total revenue (USD)
- `category_revenue_in_usd`: Total category revenue (USD)
- `revenue_first_party_in_usd`: Revenue from 1P sales (USD)
- `revenue_third_party_in_usd`: Revenue from 3P sales (USD)

**Constraints:**

- `domain`, `category`, and `brand` are required
- `granularity` supports `monthly` or `weekly`

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Brand Sales Performance

Returns list of top-performing products for a specific brand, ranked by selected metrics.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-sales/brands/top-products` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-sales/brands/top-products/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `asin`: Amazon Standard Identification Number of the product
- `name`: Product name
- `brand`: Brand name of the product
- `category_id`: Category ID the product belongs to
- `category_name`: Category name the product belongs to
- `views`: Number of product page views
- `units_sold`: Number of units sold
- `revenue`: Revenue generated (local currency)
- `revenue_in_usd`: Revenue generated (USD)
- `price`: Product price as a string
- `price_value`: Product price as a numeric value
- `price_last_scraped_date`: Date when the price was last recorded
- `average_unit_price`: Average selling price per unit
- `rating`: Product rating score
- `reviews`: Number of customer reviews
- `thumbnail`: URL of the product thumbnail image
- `best_seller_rank`: Product's best seller rank
- `best_seller_category_id`: Category ID in which the product is a best seller
- `best_seller_category_name`: Category name in which the product is a best seller
- `prime`: Whether the product is available with Amazon Prime
- `amazon_brand`: Whether the product is an Amazon private label brand
- `amazon_exclusive`: Whether the product is exclusive to Amazon
- `amazons_choice_keyword`: Keyword for which this product has the "Amazon's Choice" badge
- `small_business`: Whether the product is from a small business seller
- `climate_pledge_friendly`: Whether the product has the Climate Pledge Friendly badge

**Constraints:**

- `domain`, `category`, and `brand` are required
- `granularity` supports `monthly` or `weekly`
- Supports pagination (`limit`, `offset`, `sort`, `asc`)

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Brand Top Products

Returns time-series sales performance data for a specific category on Amazon.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-sales/categories/sales-performance` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-sales/categories/sales-performance/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `conversion`: Conversion rate (units sold per view) for the category
- `num_asins`: Number of distinct ASINs in the category
- `parent_category_id`: Unique identifier of the parent category
- `parent_category_name`: Display name of the parent category
- `parent_category_revenue`: Revenue of the parent category (local currency)
- `parent_category_revenue_in_usd`: Revenue of the parent category (USD)
- `parent_category_total_views`: Total views in the parent category
- `parent_category_units_sold`: Total units sold in the parent category
- `revenue`: Total revenue for the category (local currency)
- `total_views`: Total product page views in the category
- `units_sold`: Total units sold in the category
- `revenue_in_usd`: Total revenue for the category (USD)

**Constraints:**

- `domain` and `category` are required
- `granularity` supports `monthly` or `weekly`

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Category Sales Performance

Returns list of top-performing brands within a category, ranked by selected metrics.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-sales/categories/top-brands` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-sales/categories/top-brands/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `brand`: Name of the brand
- `total_views`: Total product page views for the brand in the category
- `total_views_share`: Brand's share of total views in the category
- `units_sold`: Total units sold by the brand in the category
- `units_sold_share`: Brand's share of total units sold in the category
- `revenue`: Total revenue generated by the brand (local currency)
- `revenue_in_usd`: Total revenue generated by the brand (USD)
- `revenue_share`: Brand's share of total revenue in the category
- `conversion`: Conversion rate for the brand (units sold per view)

**Constraints:**

- `domain` and `category` are required
- `granularity` supports `monthly` or `weekly`
- Supports pagination (`limit`, `offset`, `sort`, `asc`)

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Category Top Brands

Returns list of top products in a category, ranked by selected metrics.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-sales/categories/top-products` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-sales/categories/top-products/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `asin`: Amazon Standard Identification Number of the product
- `name`: Product name
- `brand`: Brand name of the product
- `category_id`: Category ID the product belongs to
- `category_name`: Category name the product belongs to
- `views`: Number of product page views
- `units_sold`: Number of units sold
- `revenue`: Revenue generated (local currency)
- `revenue_in_usd`: Revenue generated (USD)
- `price`: Product price as a string
- `price_value`: Product price as a numeric value
- `price_last_scraped_date`: Date when the price was last recorded
- `average_unit_price`: Average selling price per unit
- `rating`: Product rating score
- `reviews`: Number of customer reviews
- `thumbnail`: URL of the product thumbnail image
- `best_seller_rank`: Product's best seller rank
- `best_seller_category_id`: Category ID in which the product is a best seller
- `best_seller_category_name`: Category name in which the product is a best seller
- `prime`: Whether the product is available with Amazon Prime
- `amazon_brand`: Whether the product is an Amazon private label brand
- `amazon_exclusive`: Whether the product is exclusive to Amazon
- `amazons_choice_keyword`: Keyword for which this product has the "Amazon's Choice" badge
- `small_business`: Whether the product is from a small business seller
- `climate_pledge_friendly`: Whether the product has the Climate Pledge Friendly badge

**Constraints:**

- `domain` and `category` are required
- `granularity` supports `monthly` or `weekly`
- Supports pagination (`limit`, `offset`, `sort`, `asc`)

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Category Top Products

Returns time-series sales performance data for a specific product (ASIN) on Amazon.

**Variants:**

- **Time-series** (this endpoint): `GET /v5/shopper-sales/products/sales-performance` — data broken down by date for trend analysis.
- **Aggregated**: `GET /v5/shopper-sales/products/sales-performance/aggregated` — a single summary across the entire date range.

Both variants accept the same input parameters. The time-series response includes a `date` field per record; the aggregated response omits it and returns one consolidated row.

**Possible output fields:**

- `date`: Date of the data point *(time-series only)*
- `asin`: Amazon Standard Identification Number of the product
- `total_views`: Total product page views
- `units_sold`: Number of units sold
- `revenue`: Revenue generated (local currency)
- `price`: Product price
- `rating`: Product rating score
- `reviews`: Number of customer reviews
- `related_asins`: List of related ASINs (variants or complementary products)
- `brand`: Brand name of the product
- `category_name`: Category name the product belongs to
- `revenue_in_usd`: Revenue generated (USD)

**Constraints:**

- `domain` and `asin` are required
- ASIN must be exactly 10 uppercase alphanumeric characters (e.g., `B0DLFVP6YM`)
- ASINs are domain-specific and cannot be used across different Amazon domains
- `granularity` supports `monthly` or `weekly`

This endpoint uses data credits. See the [data credits guide](https://docs.similarweb.com/api-v5/guides/data-credits-calculations) to estimate costs.

Product Sales Performance

/v5/shopper-sales/sales-performance/describe

Default

API V5 latest

Similarweb API V5 Documentation

Production

Sandbox

AI Outreach

Amazon S3 Integration

Snowflake Integration

Hubspot

Salesforce

Google Data Studio

Power BI

Tableau

Google Sheets Integration

Microsoft Excel Integration

Available Data Tables

Marketing Channels

Popular Pages

Referrals

Top Geographies

Traffic & Engagement

Traffic Sources

Website Keywords

Reports

Contacts

Lead Enrichment

Website Audience

Website Content

Website Performance

Website Segments

ChatGPT Integration

Check Data Credits Balance

Claude Integration

Cursor Integration

Manus Integration

Microsoft Copilot Integration

#### The Similarweb Google Sheets Add-on (Updated July 2025) brings Similarweb’s digital intelligence directly into your spreadsheets. Use custom formulas to pull real-time web traffic, engagement, keyword, and geographic data—no code required.

Installation and Setup
----------------------

You can install the Add-on via the Google Workspace Marketplace.

**Option 1: From Google Workspace Marketplace** Search for **Similarweb**, click **Install**, and follow the prompts.

<Image url="https://files.readme.io/97e33de9d8836877dd4fe8a29351f0d14d7a94eb508b7fa5126ed147e268ff35-image.png" alt="Installing the Similarweb Google Sheets Integration" caption="" attributes='{"width":"625px","height":"286px"}'/>

**Option 2: Directly from Google Sheets**

1.  Open any sheet
    
2.  Go to Extensions > Add-ons > Get add-ons
    
3.  Search for **Similarweb** and install
    

### Authenticate with Your API Key

1.  Go to your Account Settings > **REST API**
    
2.  Copy your API key
    
3.  In the Similarweb add-on sidebar, paste your key
    
4.  Click **Save** to activate
    

<Image url="https://files.readme.io/cbfb7527a2c333633495a1e02e285e4c3588b58829ffcd57cf14d4d6914175a2-image.png" alt="Authenticate with Your API Key" caption="" attributes='{"width":"621px","height":"349px"}'/>

Discover Available Formulas
---------------------------

The first step we recommend you take is to explore all supported datasets and formulas, type this formula into any cell:

`=SIMILARWEB_GET_ALL_FUNCTIONS()`

This will return a full list of grouped formulas—covering traffic, geography, keywords, rankings, marketing channels, and more.

<Image url="https://files.readme.io/1231dc5d8ad0dc94442679222af21d86d1fe7efb142f20354b3224b584240a9d-Clipboard-20250716-175725-042.gif" alt="Discover Available Formulas" caption="" attributes='{"width":"544px","height":"233px"}'/>

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Click on any function in the output list to preview its parameters and rules, including accepted date formats, geo codes, metric options, and required fields.</p>
</Callout>

--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Image url="https://files.readme.io/21a926d3622bed3c70fff88cd395e3ba51b85818b30881006f9ee57916e2eb8f-image.png" alt="Parameters and Rules" caption="" attributes='{"width":"311px","height":"306px"}'/>

Retrieving Data in Google Sheets
--------------------------------

Instead of querying individual metrics, the new structure uses **10 grouped functions**—each one supporting multiple metrics via a single call.

### Example: Traffic & Engagement

`=SIMILARWEB_WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com","2025-01","2025-04","monthly","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit,unique_visitors")`

This retrieves traffic and engagement data for cnn.com in the US from January to April 2025.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>You can request one metric, several, or all available by editing the 'metrics' field.</p>
</Callout>

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Parameter Guide
---------------

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"6e3e1250-fd8c-49e7-a411-4667743cf77f","title":"Title"},{"id":"cfd4c34c-a0db-4b35-ba8b-ed5eb2f80bb5","title":"Description"}]'>
  <table-row>
    <table-cell>Parameter</table-cell>
    <table-cell>Description</table-cell>
  </table-row>
  <table-row>
    <table-cell>domain_name</table-cell>
    <table-cell>Website domain (e.g., "cnn.com")</table-cell>
  </table-row>
  <table-row>
    <table-cell>start_date / end_date</table-cell>
    <table-cell>Format: "YYYY-MM" or "YYYY-MM-DD"</table-cell>
  </table-row>
  <table-row>
    <table-cell>granularity</table-cell>
    <table-cell>"daily", "weekly", "monthly" (default: monthly)</table-cell>
  </table-row>
  <table-row>
    <table-cell>web_source</table-cell>
    <table-cell>"total", "desktop", "mobile_web"</table-cell>
  </table-row>
  <table-row>
    <table-cell>country</table-cell>
    <table-cell>ISO code (e.g., "us", "gb", "ww")</table-cell>
  </table-row>
  <table-row>
    <table-cell>metrics</table-cell>
    <table-cell>Comma-separated list: visits, bounce_rate, page_views, average_visit_duration, pages_per_visit, unique_visitors. Leave blank to pull all. (recommended: specify desired metrics to future-proof your reports)</table-cell>
  </table-row>
  <table-row>
    <table-cell>mtd</table-cell>
    <table-cell>TRUE/FALSE — include month-to-date values</table-cell>
  </table-row>
  <table-row>
    <table-cell>main_domain_only</table-cell>
    <table-cell>TRUE to exclude subdomains</table-cell>
  </table-row>
  <table-row>
    <table-cell>aggregation</table-cell>
    <table-cell>Aggregate over the date range: SUM, AVG, MIN, MAX, MEDIAN, FIRST</table-cell>
  </table-row>
  <table-row>
    <table-cell>return_values_only</table-cell>
    <table-cell>TRUE to return only the raw values (no headers or dates)</table-cell>
  </table-row>
</Table>

Default Behavior
----------------

*   **If no dates are provided** → latest available data will be used for **daily and monthly** granularity. **Weekly requires exact start and end dates**.
    
*   **If 'metrics' is not specified** → all available metrics will be returned.
    

<Callout attributes='{"isFitToPage":true,"dataType":"success","style":{"width":"100%","minWidth":"100%"}}'>
  <p>We highly recommend specifying only the metrics you need, as more will be added over time.</p>
</Callout>

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Advanced Examples
-----------------

These examples demonstrate how to use Similarweb formulas with specific parameters to pull the exact insights you need. In the examples below, the last field in the formula will be the relevant field.

### 1\. Choose Specific Metrics

**Use case:** Pull only the traffic and engagement metrics you need, rather than returning the full default set.

**Relevant field:** `metrics`

**Example:**

`=SIMILARWEB_WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com","2025-01","2025-04","monthly","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit,unique_visitors")`

### 2\. Aggregate Results Across Time Range

**Use case:** Summarize multiple months into a single value using median (or other aggregations like SUM, AVG).

**Relevant field:** `aggregation` - Use "MEDIAN", "SUM", etc., to condense the time period

**Example:**

`=SIMILARWEB_WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com","2025-01","2025-04","monthly","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit",,,,"MEDIAN")`

### 3\. Values Only (No Headers)

**Use case:** Output only the numeric results - no column labels or date headers. Ideal for embedding into existing reports.

**Relevant field:** `return_values_only` - Set to TRUE() to exclude labels and dates

**Example:**

`=SIMILARWEB_WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com","2025-01","2025-04","monthly","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit",,,,"SUM",TRUE())`

### 4\. Limit Results (Top Geography)

**Use case:** Pull the top countries driving traffic, limited to a specific number of rows.

**Formula used:** SIMILARWEB\_WEBSITES\_TOP\_GEOGRAPHY

**Relevant field:** limit - Caps the number of rows returned (e.g., 10)

**Example:**

<span style="color:rgb(51, 51, 51);background-color:inherit">`=SIMILARWEB_WEBSITES_TOP_GEOGRAPHY("cnn.com","2025-01","2025-04","monthly","total","share,visits,rank,average_visit_duration,pages_per_visit,bounce_rate",,"sum",,10)`</span>

### 5\. Rolling Dates for Freshest Data

**Use case:** Get the latest available **daily** or **monthly** data without manually setting dates. Leave start\_date and end\_date blank.

**Relevant field:** <span style="color:rgb(56, 66, 72);background-color:rgb(246, 248, 250)">`start_date`</span> and <span style="color:rgb(56, 66, 72);background-color:rgb(246, 248, 250)">`end_date`</span> - Date fields need to be left blank to get the latest available data. If you set granularity to 'monthly' you will get 3 months of data. If you set granularity to 'daily' you will get 28 days of data.

**Daily example:**

<span style="color:rgb(51, 51, 51);background-color:inherit">`=SIMILARWEB_WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com",,,,"daily","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit,unique_visitors")`</span>

**Monthly example:**

<span style="color:rgb(51, 51, 51);background-color:inherit">`=SIMILARWEB_WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com",,,,"monthly","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit,unique_visitors")`</span>

Sharing & Ownership
-------------------

<Callout attributes='{"isFitToPage":true,"dataType":"error","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Important</strong></p>
  <p>API keys are tied to the <strong class="slate-bold">owner of the Sheet</strong>. Anyone accessing the Sheet will use the owner's data credits.</p>
</Callout>

### ✅ Best Practice for Sharing:

*   Share as **"View Only"**
    
*   Recipients must **make a copy**, install the add-on, and enter their own API key
    

You can also:

*   Use **Freeze API Calls** to prevent accidental usage
    

Troubleshooting & Errors
------------------------

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"66a15b3a-6637-4d54-912b-f661017ebbbc","title":"Title"},{"id":"fbb7b1c5-e0d6-4239-9e5c-64095dd9795d","title":"Description"}]'>
  <table-row>
    <table-cell>Error</table-cell>
    <table-cell>Cause</table-cell>
  </table-row>
  <table-row>
    <table-cell># ERROR! (no response)</table-cell>
    <table-cell>Invalid API key or domain</table-cell>
  </table-row>
  <table-row>
    <table-cell>Data Not Found (404)</table-cell>
    <table-cell>Unsupported domain or country</table-cell>
  </table-row>
  <table-row>
    <table-cell>Invalid Country</table-cell>
    <table-cell>Wrong country code</table-cell>
  </table-row>
  <table-row>
    <table-cell>Blank Cell</table-cell>
    <table-cell>Possibly return_values_only = TRUE with no data returned</table-cell>
  </table-row>
</Table>

FAQ
---

**What's the best way to get started?** Run <span style="color:rgb(56, 66, 72);background-color:rgb(246, 248, 250)">`=SIMILARWEB_GET_ALL_FUNCTIONS()`</span> to explore all supported formulas. Click on any function name to preview its parameters.

**What metrics are available?** Metrics vary by formula group. For example, for traffic and engagement you can access: visits, bounce\_rate, page\_views, average\_visit\_duration, pages\_per\_visit, and unique\_visitors.

**Why should I specify metrics?** More metrics will be added over time. Specifying the ones you need ensures consistent output and helps future-proof your credit usage when new metrics are added.

**What happens if I don't input dates?** You'll receive the latest available **daily or monthly** data by default. Weekly granularity requires start and end dates.

**Can I limit the number of rows returned?** Yes, some functions like `SIMILARWEB_WEBSITES_TOP_GEOGRAPHY` support a limit parameter.

**Can I schedule data refreshes?** Yes! Use Google Sheets' Apps Script to schedule refreshes based on your reporting needs.

**Is the add-on free?** Yes, it's free for all Similarweb customers with API access.

**How is usage billed?** Each API call consumes credits according to your subscription plan.

#### The Similarweb Microsoft Excel Add-on (Updated June 2025) brings Similarweb’s digital intelligence directly into your spreadsheets. Use custom formulas to pull real-time web traffic, engagement, keyword, and geographic data—no code required.

### Installation and Setup

The Similarweb Excel Add-in enables customers with API access to seamlessly pull traffic and engagement data directly into Microsoft Excel. This eliminates the need for manual API calls or technical expertise, allowing users to:

*   Retrieve data directly within Excel using simple formulas.
    
*   Automate updates in reports without needing additional scripts.
    
*   Combine Similarweb data with internal datasets for deeper insights.
    
*   Create custom metrics and aggregations on demand.
    

This guide walks through installation, setup, usage, and advanced features, ensuring you get the most value from the add-in.

Installation & Setup
--------------------

### Installing the Add-in

You can install the Similarweb Excel Add-in via:

### Microsoft AppSource

1.  Open Excel, go to Insert > Get Add-ins. Or open Home > add-ins
    
2.  Search for Similarweb.
    
3.  Click Add, then confirm installation.
    
4.  Alternatively you can visit the [Microsoft Appsource product page](https://appsource.microsoft.com/en-us/product/Office365/WA200007983) and install the Add-in from there.
    

**Option 2: From the Sheets**

1.  Open any sheet
    
2.  Go to Extensions > Add-ons > Get add-ons
    
3.  Search for Similarweb and install
    

### Authenticate with Your API Key

1.  Go to your Account Settings > REST API
    
2.  Copy your API key
    
3.  In the Similarweb add-on sidebar, paste your key
    
4.  Click Save to activate
    

<Image url="https://files.readme.io/1a08f562d908aba774b1fe7a9659e8b6410c95743f117777c9671909a73b65f8-image.png" alt="Authenticate with Your API Key" caption="" attributes='{"width":"692px","height":"325px"}'/>

**Discover Available Functions**

To explore all supported datasets and functions, type this formula into any cell:

excel=SIMILARWEB\_GET\_ALL\_FUNCTIONS()

This will return a full list of grouped formulas—covering traffic, geography, keywords, rankings, marketing channels, and more.

<Image url="https://files.readme.io/8b853219166a3402d817004a247fbe2dda635e752f18e3b4cb07618b58c66073-image.png" alt="Discover Available Functions" caption="" attributes='{"width":"614px","height":"222px"}'/>

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Click on "fx" next to any function in the output list to open the Formula Builder and discover its parameters and rules, including accepted date formats, geo codes, metric options, and required fields.</p>
</Callout>

<Image url="https://files.readme.io/c39e8fdbbb39197508cb77658c3ba3a4dc5011deecedeaaef44de01585d95ed9-image.png" alt="Click on fx" caption="" attributes='{"width":"678px","height":"512px"}'/>

### Retrieving Data in to Excel

Instead of querying individual metrics, the new structure uses **10 grouped functions**—each one supporting multiple metrics via a single call.

#### Example: Traffic & Engagement

`=SIMILARWEB.WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com","2025-01","2025-04","monthly","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit,unique_visitors")`

This retrieves traffic and engagement data for CNN in the US from January to April 2025.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>You can request one metric, several, or all available by editing the metrics field.</p>
</Callout>

-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Parameter Guide

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"c55a0673-6d0d-4bbc-a1f1-fa080d04fdac","title":"Title"},{"id":"c4c16d01-8ada-4542-a325-a10dcb4a1c80","title":"Description"}]'>
  <table-row>
    <table-cell>Parameter</table-cell>
    <table-cell>Description</table-cell>
  </table-row>
  <table-row>
    <table-cell>domain_name</table-cell>
    <table-cell>Website domain (e.g., "cnn.com")</table-cell>
  </table-row>
  <table-row>
    <table-cell>start_date / end_date</table-cell>
    <table-cell>Format: "YYYY-MM" or "YYYY-MM-DD"</table-cell>
  </table-row>
  <table-row>
    <table-cell>granularity</table-cell>
    <table-cell>"daily", "weekly", "monthly" (default: monthly)</table-cell>
  </table-row>
  <table-row>
    <table-cell>web_source</table-cell>
    <table-cell>"total", "desktop", "mobile_web"</table-cell>
  </table-row>
  <table-row>
    <table-cell>country</table-cell>
    <table-cell>ISO code (e.g., "us", "gb", "ww")</table-cell>
  </table-row>
  <table-row>
    <table-cell>metrics</table-cell>
    <table-cell>Comma-separated list: visits, bouncerate, page_views, average_visit_duration, pages_per_visit, unique_visitors. Leave blank to pull all. (recommended: specify desired metrics to future-proof your reports)_</table-cell>
  </table-row>
  <table-row>
    <table-cell>mtd</table-cell>
    <table-cell>TRUE/FALSE — include month-to-date values</table-cell>
  </table-row>
  <table-row>
    <table-cell>main_domain_only</table-cell>
    <table-cell>TRUE to exclude subdomains</table-cell>
  </table-row>
  <table-row>
    <table-cell>aggregation</table-cell>
    <table-cell>Aggregate over the date range: SUM, AVG, MIN, MAX, MEDIAN, FIRST</table-cell>
  </table-row>
  <table-row>
    <table-cell>return_values_only</table-cell>
    <table-cell>TRUE to return only the raw values (no headers or dates)</table-cell>
  </table-row>
</Table>

### Default Behavior

*   If no dates are provided → latest available data will be used for daily and monthly granularity. Weekly requires exact start and end dates.
    
*   If metrics is not specified → all available metrics will be returned.
    

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>We highly recommend specifying only the metrics you need, as more will be added over time.</p>
</Callout>

------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Advanced Examples

These examples demonstrate how to use Similarweb formulas with specific parameters to pull the exact insights you need. In the examples below, the last field in the formula will be the relevant field.

#### 1\. Choose Specific Metrics

**Use case:** Pull only the traffic and engagement metrics you need, rather than returning the full default set.

**Relevant field:** `metrics`

**Example:**

`=SIMILARWEB.WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com","2025-01","2025-04","monthly","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit,unique_visitors")`

#### 2\. Aggregate Results Across Time Range

Use case: Summarize multiple months into a single value using median (or other aggregations like SUM, AVG).

**Relevant field:** `aggregation` - Use "MEDIAN", "SUM", etc., to condense the time period

**Example:**

`=SIMILARWEB.WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com","2025-01","2025-04","monthly","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit",,,,"MEDIAN")`

#### 3\. Values Only (No Headers)

**Use case:** Output only the numeric results - no column labels or date headers. Ideal for embedding into existing reports.

**Relevant field:** `return_values_only` \- Set to TRUE() to exclude labels and dates

**Example:**

`=SIMILARWEB.WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com","2025-01","2025-04","monthly","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit",,,,"SUM",TRUE())`

#### 4\. Limit Results (Top Geography)

**Use case:** Pull the top countries driving traffic, limited to a specific number of rows.

**Formula used:** `SIMILARWEB_WEBSITES_TOP_GEOGRAPHY`

**Relevant field:** `limit` - Caps the number of rows returned (e.g., 10)

**Example:**

`=SIMILARWEB.WEBSITES_TOP_GEOGRAPHY("cnn.com","2025-01","2025-04","monthly","total","share,visits,rank,average_visit_duration,pages_per_visit,bounce_rate",,"sum",,10)`

#### 5\. Rolling Dates for Freshest Data

Use case: Get the latest available daily or monthly data without manually setting dates. Leave start\_date and end\_date blank.

**Relevant field:** `start_date` and `end_date` - Date fields need to be left blank to get the latest available data. If you set granularity to 'monthly' you will get 3 months of data. If you set granularity to 'daily' you will get 28 days of data.

**Daily example:**

`=SIMILARWEB.WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com",,,,"daily","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit,unique_visitors")`

**Monthly example:**

`=SIMILARWEB.WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com",,,,"monthly","total","us","visits,bounce_rate,page_views,average_visit_duration,pages_per_visit,unique_visitors")`

#### You can also:

*   Use Freeze API Calls to prevent accidental usage
    
*   Or delete your key from the sidebar and click Save
    

### Troubleshooting & Errors

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"68750991-d6ca-499f-90d4-45793838fc5c","title":"Title"},{"id":"82361dc1-8bea-4c45-99ce-bdfc2112fb9a","title":"Description"}]'>
  <table-row>
    <table-cell>Error</table-cell>
    <table-cell>Cause</table-cell>
  </table-row>
  <table-row>
    <table-cell># ERROR! (no response)</table-cell>
    <table-cell>Invalid API key or domain</table-cell>
  </table-row>
  <table-row>
    <table-cell>Data Not Found (404)</table-cell>
    <table-cell>Unsupported domain or country</table-cell>
  </table-row>
  <table-row>
    <table-cell>Invalid Country</table-cell>
    <table-cell>Wrong country code</table-cell>
  </table-row>
  <table-row>
    <table-cell>Blank Cell</table-cell>
    <table-cell>Possibly return_values_only = TRUE with no data returned</table-cell>
  </table-row>
</Table>

### Advanced Features

#### Aggregation

Summarize your results with functions like:

`SUM, AVG, MIN, MAX, MEDIAN, FIRST`

**Example:**

**\=SIMILARWEB.WEBSITES\_TRAFFIC\_AND\_ENGAGEMENT("cnn.com","2025-01","2025-03","monthly","total","us","visits,page\_views",,,,"AVG")**

#### Return Values Only

**Omit headers and dates:**

`=SIMILARWEB.WEBSITES_TRAFFIC_AND_ENGAGEMENT("cnn.com","2025-01","2025-04","monthly","total","us","visits",,,,"SUM",TRUE())`

### FAQ

**What's the best way to get started?** Run `=SIMILARWEB.GET_ALL_FUNCTIONS()` to explore all supported formulas. Click on any function name to preview its parameters.

**What metrics are available?**

Metrics vary by formula group. For traffic and engagement, you can access: visits, bounce\_rate, page\_views, average\_visit\_duration, pages\_per\_visit, and unique\_visitors.

**Why should I specify metrics?**

More metrics will be added over time. Specifying the ones you need ensures consistent output and helps future-proof your Sheets.

**What happens if I don't input dates?**

You'll receive the latest available daily or monthly data by default. Weekly granularity requires start and end dates.

**Can I limit the number of rows returned?**

Yes—some functions like `SIMILARWEB_WEBSITES_TOP_GEOGRAPHY` support a limit parameter.

**Can I schedule data refreshes?**

Yes! Use Excel capabilities Script to schedule refreshes based on your reporting needs.

**Is the add-on free?**

Yes, it's free for all Similarweb customers with API access.

**How is usage billed?**

Each API call consumes credits according to your subscription plan.

<h4 class="slate-h4 " >The Similarweb Google Sheets Add-on (Updated July 2025) brings Similarweb’s digital intelligence directly into your spreadsheets. Use custom formulas to pull real-time web traffic, engagement, keyword, and geographic data—no code required.</h4><h2 class="slate-h2 " >Installation and Setup</h2><p class="slate-p " >You can install the Add-on via the Google Workspace Marketplace.</p><p class="slate-p " >Option 1: From Google Workspace Marketplace Search for Similarweb, click Install, and follow the prompts.</p><div style="text-align:left"><figure ><div style="display:inline-block"><img src="https://files.readme.io/97e33de9d8836877dd4fe8a29351f0d14d7a94eb508b7fa5126ed147e268ff35-image.png" alt="Installing the Similarweb Google Sheets Integration" style="
              width:625pxpx;
	            height:286pxpx;
	            aspect-ratio:625px / 286px"
         /></div></figure></div>

The Similarweb Google Sheets Add-on (Updated July 2025) brings Similarweb’s digital intelligence directly into your spreadsheets. Use custom formulas to pull real-time web traffic, engagement, keyword, and geographic data—no code required.

You can install the Add-on via the Google Workspace Marketplace.

Option 1: From Google Workspace Marketplace Search for Similarweb, click Install, and follow the prompts.

Sections

Google Sheets Integration

The Similarweb Google Sheets Add-on (Updated July 2025) brings Similarweb’s digital intelligence directly into your spreadsheets. Use custom formulas to pull real-time web traffic, engagement, keyword, and geographic data—no code required.

Installation and Setup

What made this section helpful for you?

What made this section unhelpful for you?

On this page

Sections

Google Sheets Integration

The Similarweb Google Sheets Add-on (Updated July 2025) brings Similarweb’s digital intelligence directly into your spreadsheets. Use custom formulas to pull real-time web traffic, engagement, keyword, and geographic data—no code required.

Installation and Setup

What made this section helpful for you?

What made this section unhelpful for you?

On this page

Ask an AI

Code with AI