openapi: 3.0.0
info:
  title: Google Resolve API
  description: Turn the Google redirect links in your SearchApi responses into destination URLs. Requests use no credits.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    post:
      summary: Google Resolve
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - engine
                - results
              properties:
                engine:
                  type: string
                  enum: ["google_resolve"]
                  description: Must be set to google_resolve.
                results:
                  type: array
                  minItems: 1
                  maxItems: 100
                  description: The links to resolve. An item can carry fields of your own, such as an id for your records, and they come back on its row, except `error`. The whole array can be at most 1 MB as JSON. Results come back in the order they were sent, and a request attempts up to 25 distinct links that still need resolving.
                  items:
                    type: object
                    required:
                      - link_token
                    additionalProperties: true
                    properties:
                      link_token:
                        type: string
                        description: The token returned beside a Google redirect link in a SearchApi response. Send a token named after another field, such as `website_token`, here too.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleResolveResponse'
        '400':
          description: A results item is not an object with a link_token, a link_token did not come from a SearchApi response, results is over its limits, or an item contains a null character.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests. The limit is 120 per minute and 5 at a time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    GoogleResolveResponse:
      type: object
      required:
        - search_metadata
        - search_parameters
        - results
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        results:
          type: array
          items:
            $ref: '#/components/schemas/GoogleResolveResult'
        retry_after:
          type: integer
          description: The seconds to wait before sending again the rows that have a link_token and no error, where 0 means right away.
    GoogleResolveResult:
      type: object
      description: One row per item sent, in the same order, with the fields sent on that item.
      additionalProperties: true
      properties:
        link:
          description: The destination URL on a resolved row, or the link you sent, unchanged, on any other row.
        link_token:
          type: string
          description: The token of a link that did not resolve, absent from a resolved row.
        error:
          type: string
          description: Why this link will not resolve. Do not send a row with an error again.
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to resolve the links in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the response in seconds
        total_time_taken:
          type: number
          description: Total request and parsing time in seconds
        request_url:
          type: string
          format: uri
          description: Google URL used for this search
        json_url:
          type: string
          format: uri
          description: URL to retrieve the cached JSON response
    SearchParameters:
      type: object
      required: [engine]
      properties:
        engine:
          type: string
          enum: ["google_resolve"]
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong