Irmu Google API

openapi: 3.2.0
info:
  title: Irmu Com Google API
  version: 1.0.0
  description: 'Operations tagged Google across 2 of this provider''s published API definitions: app.irmu.com.yaml, irmu-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.irmu.com/api
  description: Production
tags:
- name: Google
  description: Reading the AI Overview Google shows for a query, through the same crawler.
paths:
  /google-ai-overview:
    get:
      tags:
      - Google
      summary: Read Google's AI Overview
      operationId: googleAiOverview
      description: 'Searches Google for a query and returns the AI Overview shown above the

        results: the answer as text, and the pages it cites.


        You name the query and which Google to ask -- `de` for google.de,

        `co.uk` for google.co.uk; the search url is built from them. The

        consent dialog a first visit is greeted with is pressed past, and the

        answer is expanded before it is read.


        **30 credits, flat.** `premium`, `country` and `city` choose where the

        crawl exits, not what it costs. A query Google shows no overview for is

        still charged for: it is Google''s answer, and a null `ai_overview` with

        `status` `done` is how it reads. A crawl that fails is not charged for.


        The key goes in the `Authorization` header, or in `?key=`.'
      security:
      - apiKeyHeader: []
      - apiKeyQuery: []
      parameters:
      - name: query
        in: query
        required: true
        description: The search, as you would type it into Google. Up to 500 characters.
        schema:
          type: string
          maxLength: 500
        example: cómo se monta en tren
      - name: domain
        in: query
        required: false
        description: 'The extension of the Google to ask: `com`, `de`, `es`, `co.uk`,

          `com.br` and so on. The overview is written in that Google''s

          language, so this is usually what decides it.


          Pair it with `country` to search from inside that market too.

          '
        schema:
          type: string
          default: com
          pattern: ^(?:com|cat|(?:com?\.)?[A-Za-z]{2})$
        example: es
      - name: premium
        in: query
        required: false
        description: 'Search through the premium proxy pool rather than the standard one.

          **On by default**, because the standard pool is the one Google turns

          away; send `false` to use the standard pool. Free either way, unlike

          on `/crawl` -- the price is flat.


          Accepts `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off`, in any

          case. Anything else is refused.

          '
        schema:
          type: string
          default: 'true'
        example: 'true'
      - name: country
        in: query
        required: false
        description: 'The country to appear to be searching from, as a two-letter ISO

          3166-1 alpha-2 code. Free. Required to use `city`.

          '
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
        example: es
      - name: city
        in: query
        required: false
        description: 'The city inside that country, as the pool spells it. **Requires

          `country`.** Free here.


          Letters, digits, hyphens and underscores only; a multi-word city is

          written `new_york`.

          '
        schema:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$
        example: madrid
      - name: key
        in: query
        required: false
        description: 'The API key, as an alternative to the `Authorization` header. Ignored

          when a header is present.

          '
        schema:
          type: string
      responses:
        '200':
          description: 'Google''s results page was read. `ai_overview` is null when it showed

            no overview for the query.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAiOverviewResult'
              example:
                query: cómo se monta en tren
                domain: es
                url: https://www.google.es/search?q=c%C3%B3mo+se+monta+en+tren
                ai_overview: Montar en tren como pasajero es un proceso sencillo que se divide en varios pasos…
                sources:
                - title: Remitly
                  url: https://www.remitly.com/blog/es/viajar/viajar-en-tren/
                credits_charged: 30
                credits_remaining: 970
                job_id: 0198a9b6-1f4c-7c3e-9a2b-5d8e6f0a1b23_0198a9b6-2a71-7f0d-8c44-9e1b3c5d7f02
                status: done
                position: null
                debug: null
                error: null
        '202':
          description: 'Paid for and still going. Collect it from `/crawl/{job}`, where the

            answer arrives under `data.ai_overview` and `data.ai_overview_sources`

            rather than lifted out the way it is here.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAiOverviewResult'
        '401':
          description: No key, an unknown key, or a caller that is not an organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: 'Not enough credits, or the daily limit is reached. Nothing is charged

            and no attempt is recorded.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'A malformed request -- no query, a query over the limit, a domain that

            is not a Google domain''s extension, a city with no country, or a flag

            that is not a yes or a no.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '500':
          description: 'The crawl failed. **The credits are refunded**, so `credits_charged`

            is `0`.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAiOverviewResult'
        '503':
          description: 'The crawl could not be routed through a proxy pool. Nothing is

            charged.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://app.irmu.com/api
      description: Production
components:
  schemas:
    CrawlSnapshot:
      type: object
      description: 'Where a crawl had got to, for one that is still running or failed. Only

        sent when the request carries `debuga=1`.


        The crawler stops waiting long before it stops working, and when it stops

        waiting it looks at the tab: the url the browser is on, a picture of what

        is on screen, and the page source as it stands. That is what this is --

        a diagnosis for a request that timed out, not a result. Nothing is

        charged for it.


        Null on anything that is not still running. A finished or failed crawl has

        no tab left to look at, and a crawl still in the queue has not opened one

        yet.


        Two things to know when reading one. The image is the **viewport**, not

        the whole page, so it is not the picture `/screenshot` sells -- it is a

        thumbnail at quality 60, meant to be looked at rather than kept. And

        either artefact may be missing: they are captured independently, because a

        navigation can destroy one without touching the other, so half a snapshot

        is ordinary. The missing half reads as null rather than going absent.


        A blank image beside a near-empty `html` is not a broken capture -- it

        means the crawl stalled *inside* a navigation, with the old document

        already replaced. That is itself the answer.

        '
      required:
      - url
      - screenshot
      - html
      properties:
        url:
          type:
          - string
          - 'null'
          format: uri
          description: 'The url the tab was on, which a redirect may have moved away from the

            one you asked for.

            '
          example: https://shop.example/p/1
        screenshot:
          type:
          - string
          - 'null'
          format: byte
          description: 'A base64 JPEG of the viewport, with no `data:` prefix -- decode it as

            it stands. Null when the capture raced a navigation and lost.

            '
          example: /9j/4AAQSkZJRgABAQ...
        html:
          type:
          - string
          - 'null'
          description: 'The page source at that moment, half-loaded and all. Null when the

            capture raced a navigation and lost.

            '
          example: <!doctype html>...
    GoogleAiOverviewResult:
      type: object
      description: 'What `/google-ai-overview` answers. `ai_overview` is null while it is

        still running and when Google showed none; `status` tells those apart.

        '
      required:
      - query
      - domain
      - url
      - ai_overview
      - sources
      - credits_charged
      - credits_remaining
      - job_id
      - status
      - debug
      properties:
        query:
          type: string
          description: The search, as it was asked.
        domain:
          type: string
          description: The extension of the Google that was asked, lowercased.
        url:
          type: string
          description: The results page the crawl was run against.
        ai_overview:
          type:
          - string
          - 'null'
          description: The overview's answer as text, without its heading or Google's standing notice.
        sources:
          type: array
          description: The pages the overview cites. Empty when it cites none.
          items:
            type: object
            properties:
              title:
                type:
                - string
                - 'null'
              url:
                type: string
        credits_charged:
          type: integer
          example: 30
        credits_remaining:
          type: integer
        job_id:
          type: string
          description: What this ran under. Collect a `202` from `/crawl/{job}` with it.
        status:
          type: string
          enum:
          - done
          - queued
          - running
          - failed
        position:
          type:
          - integer
          - 'null'
        error:
          type:
          - string
          - 'null'
        debug:
          oneOf:
          - $ref: '#/components/schemas/CrawlSnapshot'
          - type: 'null'
    ValidationError:
      type: object
      required:
      - message
      - errors
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
  securitySchemes:
    apiKeyHeader:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <key>`. The usual way in.

        '
    apiKeyQuery:
      type: apiKey
      in: query
      name: key
      description: '`?key=<key>`. Accepted on the crawl route only, and only when no

        `Authorization` header was sent.

        '
x-refined-from:
- app.irmu.com.yaml
- irmu-com-openapi.yaml