crawlerdata-com Custom Search-compatible API

openapi: 3.2.0
info:
  title: CrawlerData Custom Search-compatible API
  version: 1.0.0
  description: Google Shopping (products, sellers, product details) and Google Search, Images, News, Local and Autocomplete results as JSON. Submit a job to POST /v1/jobs. The live queue returns the result in the same response; fast and regular are asynchronous (poll GET /v1/jobs/{jobId} or receive a webhook). Failed jobs cost 0 credits. Also available as an MCP server at POST /mcp.
  contact:
    name: CrawlerData
    email: contact@crawlerdata.com
    url: https://crawlerdata.com
  termsOfService: https://crawlerdata.com/legal/terms
  x-logo:
    url: https://crawlerdata.com/favicon.svg
servers:
- url: https://api.crawlerdata.com
security:
- bearerAuth: []
tags:
- name: Custom Search-compatible
  description: 'Google Custom Search JSON API parameters and response format: switch by changing the base URL and key'
paths:
  /customsearch/v1:
    get:
      tags:
      - Custom Search-compatible
      operationId: customSearch
      summary: Google Custom Search JSON API-compatible web search
      description: 'Takes Custom Search JSON API parameters and returns its JSON shape (kind, queries, searchInformation, items with title, htmlTitle, link, displayLink, snippet, htmlSnippet, formattedUrl), built from our Google web search organic results. Runs one live job, billed like POST /v1/jobs (1 credit; failed searches are free). cx is accepted and ignored (no search engine ID needed: results are from the whole web; use siteSearch to restrict). lr is used as the language when hl is not given, cr as the country when gl is not given. Other Custom Search parameters (safe, dateRestrict, exactTerms, fileType, sort, ...) are ignored; searchType=image is refused. totalResults is the estimate Google shows on the results page, omitted when there is none. htmlTitle and htmlSnippet are the HTML-escaped text (no highlighting). Errors use the Google API error format.'
      security:
      - cseKeyQuery: []
      - bearerAuth: []
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          maxLength: 500
      - name: num
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 10
        description: Number of results
      - name: start
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 1
        description: 1-based index of the first result (1, 11, 21, ...)
      - name: gl
        in: query
        schema:
          type: string
          enum:
          - us
          - gb
          - uk
          - ca
          - au
          - de
          - fr
          - nl
          - it
          - es
          - pt
          - be
          - at
          - ch
          - se
          - 'no'
          - dk
          - fi
          - ie
          - pl
          - cz
          - il
          - ae
          - in
          - jp
          - kr
          - sg
          - mx
          - br
          - nz
          - za
          - tr
          - ar
          - cl
          - co
          - pe
          - hk
          - tw
          - th
          - vn
          - id
          - my
          - ph
          - pk
          - bd
          - sa
          - eg
          - qa
          - kw
          - gr
          - hu
          - ro
          - bg
          - hr
          - sk
          - si
          - ua
          - rs
          - lt
          - lv
          - ee
          - lu
          - ng
          - ke
          - ma
          - is
          - cy
          - mt
          - ba
          - mk
          - me
          - md
          - ge
          - am
          - az
          - kz
          - uz
          - ec
          - uy
          - py
          - bo
          - cr
          - pa
          - do
          - gt
          - sv
          - pr
          - ve
          - lk
          - np
          - kh
          - jo
          - lb
          - om
          - bh
          - gh
          - tz
          - ug
          - dz
          - tn
          default: us
        description: Country
      - name: hl
        in: query
        schema:
          type: string
          default: en
        description: Language, e.g. en (a regional code such as zh-CN uses its language part)
      - name: lr
        in: query
        schema:
          type: string
        description: 'e.g. lang_fr: used as the language when hl is absent'
      - name: cr
        in: query
        schema:
          type: string
        description: 'e.g. countryDE: used as the country when gl is absent'
      - name: siteSearch
        in: query
        schema:
          type: string
        description: Restrict to (or with siteSearchFilter=e, exclude) a site
      - name: siteSearchFilter
        in: query
        schema:
          type: string
          enum:
          - i
          - e
          default: i
      - name: cx
        in: query
        schema:
          type: string
        description: Accepted and ignored
      responses:
        '200':
          description: Custom Search-shaped results
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/CseError'
        '401':
          $ref: '#/components/responses/CseError'
        '402':
          $ref: '#/components/responses/CseError'
        '429':
          $ref: '#/components/responses/CseError'
        '502':
          $ref: '#/components/responses/CseError'
components:
  responses:
    CseError:
      description: Error, Google API style
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        domain:
                          type: string
                        reason:
                          type: string
                  status:
                    type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from the dashboard (sk_...)
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: The same API key as a query parameter (SerpApi style, /search.json only)
    cseKeyQuery:
      type: apiKey
      in: query
      name: key
      description: The same API key as a query parameter (Custom Search style, /customsearch/v1 only)
externalDocs:
  description: Docs
  url: https://app.crawlerdata.com/docs