openapi: 3.0.3
info:
  title: SimilarWeb Batch Account Rankings API
  description: The SimilarWeb Batch API is optimized for large-scale bulk data extraction, supporting asynchronous jobs of up to one million domains per request. It delivers data to cloud storage destinations including Amazon S3, Google Cloud Storage, and Snowflake. The API covers website traffic, keywords, referrals, geography, segments, apps, companies, e-commerce, and technographics datasets.
  version: 4.0.0
  termsOfService: https://www.similarweb.com/corp/legal/terms-of-use/
  contact:
    name: SimilarWeb Support
    url: https://support.similarweb.com/hc/en-us/articles/22089555897373-REST-API
  license:
    name: Proprietary
    url: https://www.similarweb.com/corp/legal/terms-of-use/
servers:
- url: https://api.similarweb.com
  description: SimilarWeb API server
tags:
- name: Rankings
  description: Global, country, and industry rank data
paths:
  /v1/website/{domain_name}/global-rank/global-rank:
    get:
      operationId: getGlobalRank
      summary: Global Rank - Total (Desktop & Mobile)
      description: Retrieve the global rank for a domain calculated from a mix of unique visitor and pageview estimations across desktop and mobile.
      tags:
      - Rankings
      security:
      - apiKeyQuery: []
      parameters:
      - $ref: '#/components/parameters/domainName'
      - $ref: '#/components/parameters/apiKeyQuery'
      - $ref: '#/components/parameters/startDate'
      - $ref: '#/components/parameters/endDate'
      - $ref: '#/components/parameters/mainDomainOnly'
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Global rank time series
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalRankResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
  /v4/rank-tracker/{campaign_id}/reports/overview-report/performanceOverTime:
    get:
      operationId: getRankTrackingCampaignOverview
      summary: Rank Tracking Campaign Overview
      description: Retrieve aggregate performance metrics for a rank tracking campaign over time, including average position, visibility, and SERP feature coverage.
      tags:
      - Rankings
      security:
      - apiKeyQuery: []
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
        description: Rank tracking campaign identifier
      - $ref: '#/components/parameters/apiKeyQuery'
      - $ref: '#/components/parameters/startDate'
      - $ref: '#/components/parameters/endDate'
      - name: device
        in: query
        required: false
        schema:
          type: string
          enum:
          - Desktop
          - Mobile
        description: Device type filter
      - name: site
        in: query
        required: false
        schema:
          type: string
        description: Site to filter campaign results
      - name: scraping_configurations
        in: query
        required: false
        schema:
          type: string
        description: Scraping configuration ID
      responses:
        '200':
          description: Campaign performance overview
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/MetaObject'
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date
                        avg_position:
                          type: number
                        visibility:
                          type: number
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  parameters:
    startDate:
      name: start_date
      in: query
      required: false
      schema:
        type: string
        pattern: ^\d{4}-\d{2}$
        example: 2024-01
      description: Start month in YYYY-MM format
    mainDomainOnly:
      name: main_domain_only
      in: query
      required: false
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
        default: 'false'
      description: Return main domain only (true) or include subdomains (false)
    endDate:
      name: end_date
      in: query
      required: false
      schema:
        type: string
        pattern: ^\d{4}-\d{2}$
        example: 2024-06
      description: End month in YYYY-MM format
    domainName:
      name: domain_name
      in: path
      required: true
      schema:
        type: string
        example: example.com
      description: Website domain without 'www.' prefix
    format:
      name: format
      in: query
      required: false
      schema:
        type: string
        enum:
        - json
        - xml
        default: json
      description: Response format
    apiKeyQuery:
      name: api_key
      in: query
      required: true
      schema:
        type: string
      description: SimilarWeb API authentication key
  schemas:
    MetaObject:
      type: object
      description: Standard response metadata
      properties:
        request:
          type: object
          description: Echo of the original request parameters
        status:
          type: string
          description: Request status (Success or error)
        last_updated:
          type: string
          format: date
          description: Timestamp of the most recent data update
    GlobalRankResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/MetaObject'
        global_rank:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                pattern: ^\d{4}-\d{2}$
                description: Month in YYYY-MM format
              global_rank:
                type: integer
                description: Global rank position
  responses:
    BadRequest:
      description: Bad request - invalid parameters or missing required fields
      content:
        application/json:
          schema:
            type: object
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: api-key
      description: SimilarWeb API key passed as a request header
externalDocs:
  description: SimilarWeb Batch API Documentation
  url: https://developers.similarweb.com/docs/intro-to-the-batch-api-datasets.md