openapi: 3.0.0
info:
  title: Google Reverse Image API
  description: |
    Search Google with an image instead of a text query.

    Pass a publicly accessible image URL and the response carries the web results Google returns for that image, the visually similar images it finds, and the searches it relates to the image. Result links are returned as direct destination URLs. Some come back as google.com redirects that forward to the same destination.

    **Cross-linking**: to find exact copies of the image or product listings, or to add a text query alongside the image, use the Google Lens API.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Google Reverse Image Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `google_reverse_image`'
          schema:
            type: string
            enum: ["google_reverse_image"]
        - name: url
          in: query
          required: true
          description: URL of the image to search. Must be a publicly accessible image URL.
          schema:
            type: string
            maxLength: 6000
        - name: hl
          in: query
          required: false
          description: Language code for the search interface.
          schema:
            type: string
            default: "en"
            enum: ["af", "ak", "sq", "am", "ar", "hy", "az", "eu", "be", "bem", "bn", "bh", "xx-bork", "bs", "br", "bg", "km", "ca", "chr", "ny", "zh-cn", "zh-tw", "co", "hr", "cs", "da", "nl", "xx-elmer", "en", "eo", "et", "ee", "fo", "tl", "fi", "fr", "fy", "gaa", "gl", "ka", "de", "el", "kl", "gn", "gu", "xx-hacker", "ht", "ha", "haw", "iw", "hi", "hu", "is", "ig", "id", "ia", "ga", "it", "ja", "jw", "kn", "kk", "rw", "rn", "xx-klingon", "kg", "ko", "kri", "ku", "ckb", "ky", "lo", "la", "lv", "ln", "lt", "loz", "lg", "ach", "mk", "mg", "my", "ms", "ml", "mt", "mv", "mi", "mr", "mfe", "mo", "mn", "sr-me", "ne", "pcm", "nso", "no", "nn", "oc", "or", "om", "ps", "fa", "xx-pirate", "pl", "pt", "pt-br", "pt-pt", "pa", "qu", "ro", "rm", "nyn", "ru", "gd", "sr", "sh", "st", "tn", "crs", "sn", "sd", "si", "sk", "sl", "so", "es", "es-419", "su", "sw", "sv", "tg", "ta", "tt", "te", "th", "ti", "to", "lua", "tum", "tr", "tk", "tw", "ug", "uk", "ur", "uz", "vu", "vi", "cy", "wo", "xh", "yi", "yo", "zu"]
        - name: country
          in: query
          required: false
          description: Country code that defines the location the search is made from.
          schema:
            type: string
            default: "us"
            enum: ["ae", "af", "ag", "ai", "al", "am", "ao", "ar", "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bg", "bh", "bj", "bn", "bo", "br", "bs", "bw", "by", "bz", "ca", "cg", "ch", "ci", "cl", "cm", "cn", "co", "cr", "cv", "cy", "cz", "de", "dk", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fr", "gb", "ge", "gh", "gp", "gr", "gt", "gy", "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "in", "iq", "is", "it", "jm", "jo", "jp", "ke", "kg", "kh", "kr", "kw", "ky", "kz", "la", "lb", "lc", "lk", "lt", "lu", "lv", "ly", "ma", "md", "me", "mg", "mk", "ml", "mm", "mn", "mo", "mq", "mt", "mu", "mv", "mx", "my", "mz", "na", "nc", "ng", "ni", "nl", "no", "np", "nz", "om", "pa", "pe", "ph", "pk", "pl", "pr", "ps", "pt", "py", "qa", "re", "ro", "rs", "ru", "sa", "sc", "sd", "se", "sg", "si", "sk", "sn", "sr", "sv", "th", "tn", "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve", "vn", "xk", "ye", "za", "zm", "zw"]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          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: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          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 90 seconds.
          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:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        organic_results:
          type: array
          items:
            $ref: '#/components/schemas/OrganicResult'
          description: "Web results Google returns for the image"
        visual_matches:
          type: array
          items:
            $ref: '#/components/schemas/VisualMatch'
          description: "Images Google finds that look like the searched image"
        related_searches:
          type: array
          items:
            $ref: '#/components/schemas/RelatedSearch'
          description: "Searches Google relates to the image"
        error:
          type: string
          description: "Error message describing what went wrong"
    SearchMetadata:
      type: object
      required: [id, 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 make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "Google URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: "Search engine used"
        url:
          type: string
          description: "Image URL that was searched"
        hl:
          type: string
          description: "Language code used"
        country:
          type: string
          description: "Country code used"
    OrganicResult:
      type: object
      required: [position, title, link, source, domain, displayed_link, snippet]
      properties:
        position:
          type: integer
          description: "Position in the web results"
        title:
          type: string
          description: "Result title"
        link:
          type: string
          description: "Result URL"
        source:
          type: string
          description: "Source name shown with the result"
        domain:
          type: string
          description: "Domain of the result"
        displayed_link:
          type: string
          description: "Display URL or the metadata line Google shows in its place"
        snippet:
          type: string
          description: "Result snippet"
        snippet_highlighted_words:
          type: array
          items:
            type: string
          description: "Highlighted words in the snippet"
        favicon:
          type: string
          description: "Favicon of the result source"
        thumbnail:
          type: string
          description: "Thumbnail image URL"
        date:
          type: string
          description: "Date Google shows with the result"
        images:
          type: array
          items:
            type: string
          description: "Image URLs shown with the result"
        video:
          $ref: '#/components/schemas/VideoInfo'
        sitelinks:
          $ref: '#/components/schemas/Sitelinks'
        rich_snippet:
          $ref: '#/components/schemas/RichSnippet'
    VideoInfo:
      type: object
      properties:
        link:
          type: string
          description: "Video URL"
        source:
          type: string
          description: "Video source platform"
        channel:
          type: string
          description: "Channel name"
        date:
          type: string
          description: "Video upload or stream date"
        length:
          type: string
          description: "Video duration"
        key_moments:
          type: array
          items:
            $ref: '#/components/schemas/VideoKeyMoment'
          description: "Video key moments"
    VideoKeyMoment:
      type: object
      properties:
        time:
          type: string
          description: "Time display (e.g., '1:23')"
        seconds:
          type: integer
          description: "Time in seconds"
        title:
          type: string
          description: "Key moment title"
        link:
          type: string
          description: "Link to this moment in the video"
        thumbnail:
          type: string
          description: "Thumbnail image URL for this moment"
    Sitelinks:
      type: object
      properties:
        list:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
                description: "Sitelink title"
              link:
                type: string
                description: "Sitelink URL"
              answer_count:
                type: integer
                description: "Number of answers on the linked page"
              date:
                type: string
                description: "Date Google shows with the sitelink"
          description: "Sitelinks listed under the result"
    RichSnippet:
      type: object
      properties:
        extensions:
          type: array
          items:
            type: string
          description: "Extension strings shown with the result"
        detected_extensions:
          type: object
          properties:
            rating:
              type: number
              description: "Rating shown with the result"
            reviews:
              type: integer
              description: "Number of reviews shown with the result"
    VisualMatch:
      type: object
      required: [position, title, link, source, thumbnail]
      properties:
        position:
          type: integer
          description: "Position in the results"
        title:
          type: string
          description: "Title of the visual match"
        link:
          type: string
          description: "URL to the source of the visual match"
        image:
          type: object
          required: [link, height, width]
          properties:
            link:
              type: string
              description: "Full resolution image URL"
            height:
              type: integer
              description: "Image height in pixels"
            width:
              type: integer
              description: "Image width in pixels"
          description: "Original image of the visual match"
        source:
          type: string
          description: "Source website of the visual match"
        thumbnail:
          type: string
          description: "Thumbnail image URL"
        price:
          type: string
          description: "Price of the item if available"
        extracted_price:
          type: number
          description: "Numeric price value extracted from the price string"
        currency:
          type: string
          description: "ISO 4217 currency code when the displayed token identifies it unambiguously; omitted for shared symbols without seller context"
        rating:
          type: number
          description: "Rating of the item"
        reviews:
          type: integer
          description: "Number of reviews"
        stock_information:
          type: string
          description: "Stock availability information"
    RelatedSearch:
      type: object
      required: [title, link, thumbnail]
      properties:
        title:
          type: string
          description: "Title of the related search"
        link:
          type: string
          description: "URL to perform the related search"
        thumbnail:
          type: string
          description: "Base64 data URI of the related search thumbnail"
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong