apidirect-io Google Search API

openapi: 3.2.0
info:
  title: Apidirect Io Google Search API
  version: 1.9.1
  contact:
    name: API Direct support
    url: https://apidirect.io
    email: support@apidirect.io
  termsOfService: https://apidirect.io/terms
  x-refined-note:
  - x-guidance differs across the merged source definitions and was not carried
  x-logo:
    url: https://apidirect.io/static/A.png
    altText: API Direct
  description: 'Operations tagged Google Search across 2 of this provider''s published API definitions: apidirect-io-openapi.json, apidirect-io-x402-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://apidirect.io
  description: Production
- description: x402 (pay per request in USDC, no API key)
  url: https://x402.apidirect.io
tags:
- name: Google Search
  description: Search Google web results in real time and prompt Google AI Mode for conversational answers with citations.
paths:
  /v1/web/search:
    get:
      tags:
      - Google Search
      operationId: searchWeb
      summary: Google Web Search
      description: 'Run a real-time Google search and return organic results with position, rank, title, URL, snippet, source, domain, and displayed link. Supports Google advanced operators (site:, inurl:, intitle:). Fetch 1-10 pages of results in a single call: each page is 10 results and every page is merged into one results array. Supports country, language, time window, city-level location, and device targeting. Set include_ai_overview=true to include Google''s AI Overview when one is available for the query.


        **Price:** $0.004 per page (+$0.002 flat per request when `include_ai_overview=true`). **Free tier:** 50 requests/month.'
      externalDocs:
        url: https://apidirect.io/docs/web-search
      parameters:
      - name: query
        in: query
        required: true
        description: Search keyword (max 500 characters, measured after leading and trailing whitespace is trimmed). Supports Google advanced operators (site:, inurl:, intitle:, etc.)
        schema:
          type: string
          maxLength: 500
        example: how to build a website
      - name: pages
        in: query
        required: false
        description: 'Number of result pages to fetch and merge (10 results per page). This is a count, not a page number: pages=3 returns the first 30 results in a single results array. Values above 10 are rejected with 400; values below 1 are treated as 1. Each page is billed as one request.'
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 1
        example: 2
      - name: country
        in: query
        required: false
        description: 2-letter ISO 3166-1 alpha-2 country code. A value that is not exactly 2 letters is rejected with 400.
        schema:
          type: string
          default: us
          minLength: 2
          maxLength: 2
        example: us
      - name: language
        in: query
        required: false
        description: 2-letter ISO 639-1 language code. A value that is not exactly 2 letters is rejected with 400.
        schema:
          type: string
          default: en
          minLength: 2
          maxLength: 2
        example: en
      - name: time
        in: query
        required: false
        description: Time filter for results
        schema:
          type: string
          enum:
          - any
          - hour
          - day
          - week
          - month
          - year
          default: any
      - name: location
        in: query
        required: false
        description: City-level geo location (e.g. London,England,United Kingdom)
        schema:
          type: string
      - name: device
        in: query
        required: false
        description: Device type to simulate
        schema:
          type: string
          enum:
          - desktop
          - mobile
          default: desktop
      - name: include_ai_overview
        in: query
        required: false
        description: When true, include Google's AI Overview for the query. Only the exact value true (case-insensitive) enables it. When enabled, the response always contains an ai_overview field, which is null if Google generated no overview for the query.
        schema:
          type: boolean
          default: false
      x-example-query:
        query: how to build a website
        pages: 2
        country: us
        language: en
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchWebResponse'
              example:
                results:
                - position: 1
                  rank: 1
                  title: Website Builder - Create a Free Website
                  url: https://www.canva.com/website-builder/
                  snippet: Design and launch a professional, one-of-a-kind website in minutes...
                  source: Canva
                  domain: canva.com
                  displayed_link: https://www.canva.com › website-builder
                - position: 2
                  rank: 2
                  title: 'Wix.com: Website Builder - Create a Free Website In Minutes'
                  url: https://www.wix.com/
                  snippet: Get everything you need to create your website, your way...
                  source: Wix
                  domain: wix.com
                  displayed_link: https://www.wix.com
                pages: 2
                count: 20
                ai_overview:
                  text_parts:
                  - type: paragraph
                    text: Building a website involves choosing a platform, designing pages, and publishing. Most modern builders offer drag-and-drop interfaces...
                  reference_links:
                  - title: How to Create a Website From Scratch
                    link: https://www.wix.com/blog/how-to-build-website-from-scratch-guide
                    source: Wix
        '400':
          description: 'Bad request: missing or invalid parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'Unauthorized: invalid or missing API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Free tier used up for this endpoint and no payment method on file (`payment_required`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Account blocked after a failed payment (`account_blocked`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded or too many concurrent requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Temporary failure retrieving search data. Please retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable. Please retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://apidirect.io
      description: Production
  /v1/web/ai-mode:
    get:
      tags:
      - Google Search
      operationId: googleAiMode
      summary: Google AI Mode
      description: 'Send a prompt to Google''s AI Mode and receive a structured conversational reply broken into ordered parts (paragraph, heading, list, images) with cited reference links. Each response includes a session_token: pass it on the next call to continue the conversation in context. Each call, including a follow-up, is billed as one request. The same endpoint also accepts POST with a JSON body for prompts that do not fit comfortably in a URL. In the rare case where Google returns no answer, the response is still 200 with an empty reply_parts array.


        **Price:** $0.005 per request. **Free tier:** 50 requests/month.'
      externalDocs:
        url: https://apidirect.io/docs/google-ai-mode
      parameters:
      - name: prompt
        in: query
        required: true
        description: The AI Mode prompt (max 12000 characters)
        schema:
          type: string
          maxLength: 12000
        example: How do I make pizza?
      - name: country
        in: query
        required: false
        description: 2-letter ISO 3166-1 alpha-2 country code. A value that is not exactly 2 letters is rejected with 400.
        schema:
          type: string
          default: us
          minLength: 2
          maxLength: 2
      - name: language
        in: query
        required: false
        description: 2-letter ISO 639-1 language code. A value that is not exactly 2 letters is rejected with 400.
        schema:
          type: string
          default: en
          minLength: 2
          maxLength: 2
      - name: session_token
        in: query
        required: false
        description: Token from a previous AI Mode response. Pass it to continue the conversation with prior context. Treat as an opaque string.
        schema:
          type: string
      x-example-query:
        prompt: How do I make pizza?
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAiModeResponse'
              example:
                reply_parts:
                - type: paragraph
                  text: Making pizza at home involves preparing the dough, sauce, and toppings, then baking at high heat.
                - type: heading
                  text: 1. Prepare the Dough
                - type: list
                  ordered: false
                  list:
                  - title: 'Activate Yeast:'
                    text: Mix warm water with yeast and a pinch of sugar. Let it sit for about 5-10 minutes until foamy.
                  - title: 'Mix and Knead:'
                    text: Combine the yeast mixture with flour and salt. Knead for 5-10 minutes until smooth and elastic.
                reference_links:
                - title: Best Homemade Pizza Dough (photo tutorial)
                  link: https://www.crunchycreamysweet.com/the-best-homemade-pizza-dough-photo-tutorial/
                  snippet: Instructions. Place water and sugar in a large mixing bowl...
                  source: Crunchy Creamy Sweet
                  favicon: https://encrypted-tbn1.gstatic.com/faviconV2?url=https://www.crunchycreamysweet.com&size=128
                  date: Jul 6, 2012
                session_token: Q21vd1lUZHFaMjlNYWtOTWREQndWRmRyV1RNemFqRnViak01Ym1FeE1tdFZVemhFVGxCeFQxZE9RV1o0...
        '400':
          description: 'Bad request: missing or invalid parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'Unauthorized: invalid or missing API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Free tier used up for this endpoint and no payment method on file (`payment_required`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Account blocked after a failed payment (`account_blocked`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded or too many concurrent requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Temporary failure retrieving search data. Please retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable. Please retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
    post:
      tags:
      - Google Search
      operationId: googleAiModePost
      summary: Google AI Mode (JSON Body)
      description: 'Same behaviour as GET /v1/web/ai-mode, with the parameters sent as a JSON body instead of query string parameters. Use POST for long prompts that do not fit comfortably in a URL. If a parameter is sent in both places, a non-empty query string value takes precedence over the body. In the rare case where Google returns no answer, the response is still 200 with an empty reply_parts array. Every field may be sent either in the JSON body or as a query parameter; when both are present the query parameter wins. A request that supplies `prompt` as a query parameter therefore needs no body at all.


        **Price:** $0.005 per request. **Free tier:** 50 requests/month.'
      externalDocs:
        url: https://apidirect.io/docs/google-ai-mode
      parameters:
      - name: prompt
        in: query
        required: false
        description: 'The AI Mode prompt (max 12000 characters). Optional on POST: overrides the same field in the JSON body when both are sent'
        schema:
          type: string
          maxLength: 12000
        example: How do I make pizza?
      - name: country
        in: query
        required: false
        description: '2-letter ISO 3166-1 alpha-2 country code. A value that is not exactly 2 letters is rejected with 400. Optional on POST: overrides the same field in the JSON body when both are sent'
        schema:
          type: string
          default: us
          minLength: 2
          maxLength: 2
      - name: language
        in: query
        required: false
        description: '2-letter ISO 639-1 language code. A value that is not exactly 2 letters is rejected with 400. Optional on POST: overrides the same field in the JSON body when both are sent'
        schema:
          type: string
          default: en
          minLength: 2
          maxLength: 2
      - name: session_token
        in: query
        required: false
        description: 'Token from a previous AI Mode response. Pass it to continue the conversation with prior context. Treat as an opaque string. Optional on POST: overrides the same field in the JSON body when both are sent'
        schema:
          type: string
      x-example-query:
        prompt: How do I make pizza?
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  maxLength: 12000
                  description: The AI Mode prompt (max 12000 characters)
                country:
                  type: string
                  default: us
                  description: 2-letter ISO 3166-1 alpha-2 country code. A value that is not exactly 2 letters is rejected with 400.
                language:
                  type: string
                  default: en
                  description: 2-letter ISO 639-1 language code. A value that is not exactly 2 letters is rejected with 400.
                session_token:
                  type: string
                  description: Token from a previous AI Mode response. Pass it to continue the conversation with prior context. Treat as an opaque string.
            example:
              prompt: How do I make pizza?
              country: us
              language: en
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAiModePostResponse'
              example:
                reply_parts:
                - type: paragraph
                  text: Making pizza at home involves preparing the dough, sauce, and toppings, then baking at high heat.
                - type: heading
                  text: 1. Prepare the Dough
                - type: list
                  ordered: false
                  list:
                  - title: 'Activate Yeast:'
                    text: Mix warm water with yeast and a pinch of sugar. Let it sit for about 5-10 minutes until foamy.
                  - title: 'Mix and Knead:'
                    text: Combine the yeast mixture with flour and salt. Knead for 5-10 minutes until smooth and elastic.
                reference_links:
                - title: Best Homemade Pizza Dough (photo tutorial)
                  link: https://www.crunchycreamysweet.com/the-best-homemade-pizza-dough-photo-tutorial/
                  snippet: Instructions. Place water and sugar in a large mixing bowl...
                  source: Crunchy Creamy Sweet
                  favicon: https://encrypted-tbn1.gstatic.com/faviconV2?url=https://www.crunchycreamysweet.com&size=128
                  date: Jul 6, 2012
                session_token: Q21vd1lUZHFaMjlNYWtOTWREQndWRmRyV1RNemFqRnViak01Ym1FeE1tdFZVemhFVGxCeFQxZE9RV1o0...
        '400':
          description: 'Bad request: missing or invalid parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'Unauthorized: invalid or missing API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Free tier used up for this endpoint and no payment method on file (`payment_required`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Account blocked after a failed payment (`account_blocked`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request body larger than 1 MB (`payload_too_large`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded or too many concurrent requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Temporary failure retrieving search data. Please retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable. Please retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://apidirect.io
      description: Production
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - code
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Machine-readable error code, such as `missing_parameter`, `invalid_parameter`, `missing_api_key`, `invalid_api_key`, `payment_required`, `account_blocked`, `not_found`, `concurrency_limit_exceeded`, `daily_limit_exceeded`, `monthly_limit_exceeded`, `upstream_rate_limit`, `upstream_error`, `upstream_timeout`, `service_unavailable`, `endpoint_suspended`, `payload_too_large` or `rate_limited`. New codes may be added.
      example:
        error: 'Missing required parameter: query'
        code: missing_parameter
    SearchWebResponse:
      type: object
      properties:
        results:
          type:
          - array
          - 'null'
          items:
            type:
            - object
            - 'null'
            properties:
              position:
                type:
                - number
                - 'null'
              rank:
                type:
                - number
                - 'null'
              title:
                type:
                - string
                - 'null'
              url:
                type:
                - string
                - 'null'
              snippet:
                type:
                - string
                - 'null'
              source:
                type:
                - string
                - 'null'
              domain:
                type:
                - string
                - 'null'
              displayed_link:
                type:
                - string
                - 'null'
        pages:
          type:
          - number
          - 'null'
        count:
          type:
          - number
          - 'null'
        ai_overview:
          type:
          - object
          - 'null'
          properties:
            text_parts:
              type:
              - array
              - 'null'
              items:
                type:
                - object
                - 'null'
                properties:
                  type:
                    type:
                    - string
                    - 'null'
                  text:
                    type:
                    - string
                    - 'null'
            reference_links:
              type:
              - array
              - 'null'
              items:
                type:
                - object
                - 'null'
                properties:
                  title:
                    type:
                    - string
                    - 'null'
                  link:
                    type:
                    - string
                    - 'null'
                  source:
                    type:
                    - string
                    - 'null'
      description: Inferred from a live response. Any field can be null or absent, and new fields may be added at any time.
    GoogleAiModeResponse:
      type: object
      properties:
        reply_parts:
          type:
          - array
          - 'null'
          items:
            type:
            - object
            - 'null'
            properties:
              type:
                type:
                - string
                - 'null'
              text:
                type:
                - string
                - 'null'
              ordered:
                type:
                - boolean
                - 'null'
              list:
                type:
                - array
                - 'null'
                items:
                  type:
                  - object
                  - 'null'
                  properties:
                    title:
                      type:
                      - string
                      - 'null'
                    text:
                      type:
                      - string
                      - 'null'
        reference_links:
          type:
          - array
          - 'null'
          items:
            type:
            - object
            - 'null'
            properties:
              title:
                type:
                - string
                - 'null'
              link:
                type:
                - string
                - 'null'
              snippet:
                type:
                - string
                - 'null'
              source:
                type:
                - string
                - 'null'
              favicon:
                type:
                - string
                - 'null'
              date:
                type:
                - string
                - 'null'
        session_token:
          type:
          - string
          - 'null'
      description: Inferred from a live response. Any field can be null or absent, and new fields may be added at any time.
    GoogleAiModePostResponse:
      type: object
      properties:
        reply_parts:
          type:
          - array
          - 'null'
          items:
            type:
            - object
            - 'null'
            properties:
              type:
                type:
                - string
                - 'null'
              text:
                type:
                - string
                - 'null'
              ordered:
                type:
                - boolean
                - 'null'
              list:
                type:
                - array
                - 'null'
                items:
                  type:
                  - object
                  - 'null'
                  properties:
                    title:
                      type:
                      - string
                      - 'null'
                    text:
                      type:
                      - string
                      - 'null'
        reference_links:
          type:
          - array
          - 'null'
          items:
            type:
            - object
            - 'null'
            properties:
              title:
                type:
                - string
                - 'null'
              link:
                type:
                - string
                - 'null'
              snippet:
                type:
                - string
                - 'null'
              source:
                type:
                - string
                - 'null'
              favicon:
                type:
                - string
                - 'null'
              date:
                type:
                - string
                - 'null'
        session_token:
          type:
          - string
          - 'null'
      description: Inferred from a live response. Any field can be null or absent, and new fields may be added at any time.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your API key (starts with `ak_live_`), from https://apidirect.io/dashboard/keys.
externalDocs:
  description: API Direct documentation
  url: https://apidirect.io/docs
x-refined-from:
- apidirect-io-openapi.json
- apidirect-io-x402-openapi.json