{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usestring-ai/json-schema/usestring-ai-search-response-schema.json",
  "title": "SearchResponse",
  "description": "Structured search response. Every field besides `results`, `zeroResults` and `paging` is a Google page surface, present only when the page carried it; other engines return `results` and `zeroResults` only. A search that could not be completed is a non-200 status, never an empty 200.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usestring-ai-openapi.json#/components/schemas/SearchResponse",
  "type": "object",
  "required": [
    "results",
    "zeroResults"
  ],
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchResult"
      },
      "description": "Ranked web results in engine order. Empty when the page carried no documents."
    },
    "zeroResults": {
      "type": "boolean",
      "description": "`true` when the engine reported that nothing matched (broaden the query; retrying will not help). `false` with empty `results` means a local pack (`places`) or knowledge panel (`entity`) answered instead."
    },
    "paging": {
      "$ref": "#/$defs/SearchPaging"
    },
    "spelling": {
      "$ref": "#/$defs/SearchSpelling"
    },
    "ads": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchAd"
      }
    },
    "places": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchPlace"
      }
    },
    "products": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchProduct"
      },
      "description": "Present only with `searchType: shopping`."
    },
    "entity": {
      "$ref": "#/$defs/SearchEntity"
    },
    "relatedSearches": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Query strings from the Related searches block."
    },
    "peopleAlsoAsk": {
      "type": "array",
      "description": "Questions from the People also ask block. No answer text is on the page.",
      "items": {
        "type": "object",
        "properties": {
          "question": {
            "type": "string"
          }
        }
      }
    },
    "answers": {
      "$ref": "#/$defs/SearchAnswers"
    },
    "videos": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchVideo"
      }
    },
    "shortVideos": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchVideo"
      },
      "description": "Entries of the Short videos block, same shape as `videos`."
    },
    "discussions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchDiscussion"
      }
    },
    "images": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchImage"
      }
    },
    "sitelinks": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchSitelink"
      }
    },
    "overviews": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchOverview"
      }
    },
    "aiMode": {
      "$ref": "#/$defs/AiModeAnswer"
    }
  },
  "$defs": {
    "AiModeAnswer": {
      "type": "object",
      "description": "Google AI Mode's answer (`engine: google_ai_mode`). Every field except `text` and `sources` is absent when the answer has none.",
      "required": [
        "text",
        "sources"
      ],
      "properties": {
        "text": {
          "type": "string",
          "description": "The answer as plain text in reading order."
        },
        "markdown": {
          "type": "string",
          "description": "The same answer as Markdown."
        },
        "blocks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AiModeBlock"
          },
          "description": "The answer's structure in reading order."
        },
        "sources": {
          "type": "array",
          "description": "Pages the answer cites, in order. Empty when Google cited none.",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "description": "Optional."
              },
              "url": {
                "type": "string",
                "description": "Absent when the citation could not be resolved."
              },
              "snippet": {
                "type": "string",
                "description": "The quoted passage. Optional."
              },
              "source": {
                "type": "string",
                "description": "The site's name. Optional."
              }
            }
          }
        },
        "products": {
          "type": "array",
          "description": "Products the answer recommends.",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "description": "Product name."
              },
              "price": {
                "type": "string",
                "description": "As displayed. Optional."
              },
              "oldPrice": {
                "type": "string",
                "description": "Price before a reduction. Present only on sale."
              },
              "merchant": {
                "type": "string",
                "description": "Optional."
              },
              "moreSellers": {
                "type": "boolean",
                "description": "Optional."
              },
              "rating": {
                "type": "number",
                "description": "Optional."
              },
              "reviews": {
                "type": "integer",
                "description": "Optional."
              },
              "thumbnail": {
                "type": "string",
                "description": "Optional."
              },
              "productId": {
                "type": "string",
                "description": "Google's product ID. Optional."
              },
              "url": {
                "type": "string",
                "description": "Google's page for the product. Optional."
              }
            }
          }
        },
        "places": {
          "type": "array",
          "description": "Businesses and places the answer names.",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "category": {
                "type": "string",
                "description": "Optional."
              },
              "rating": {
                "type": "number",
                "description": "Optional."
              },
              "reviews": {
                "type": "integer",
                "description": "English-language answers only."
              },
              "priceLevel": {
                "type": "string",
                "description": "Such as `$$`. Optional."
              },
              "status": {
                "type": "string",
                "description": "Opening status as displayed. Optional."
              },
              "address": {
                "type": "string",
                "description": "Optional."
              },
              "description": {
                "type": "string",
                "description": "Optional."
              },
              "url": {
                "type": "string",
                "description": "Google's page for the place. Optional."
              }
            }
          }
        },
        "videos": {
          "type": "array",
          "description": "Videos the answer cites.",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "description": "Optional."
              },
              "channel": {
                "type": "string",
                "description": "Optional."
              },
              "duration": {
                "type": "string",
                "description": "Optional."
              },
              "thumbnail": {
                "type": "string",
                "description": "Optional."
              }
            }
          }
        }
      }
    },
    "AiModeBlock": {
      "type": "object",
      "description": "One block of the AI Mode answer. `type` decides the other fields: `paragraph`: `text`; `heading`: `text`, `level`; `list`: `items`, `ordered`; `table`: `header`, `rows`; `code`: `text`, optional `language`.",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "paragraph",
            "heading",
            "list",
            "table",
            "code"
          ]
        },
        "text": {
          "type": "string"
        },
        "level": {
          "type": "integer",
          "description": "Heading level."
        },
        "items": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "One string per list item."
        },
        "ordered": {
          "type": "boolean",
          "description": "`true` for a numbered list."
        },
        "header": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Column names."
        },
        "rows": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "description": "One array per row, one cell per column."
        },
        "language": {
          "type": "string",
          "description": "Code block language, when labelled."
        }
      }
    },
    "SearchAd": {
      "type": "object",
      "description": "A sponsored result, kept apart from `results`.",
      "properties": {
        "position": {
          "type": "integer",
          "description": "1-based order within the page's ad blocks."
        },
        "format": {
          "type": "string",
          "enum": [
            "text",
            "shopping"
          ]
        },
        "block": {
          "type": "string",
          "description": "Where the ad sat, such as `top` or `bottom`."
        },
        "title": {
          "type": "string",
          "description": "Ad headline. Optional."
        },
        "url": {
          "type": "string",
          "description": "The advertiser's destination. Absent when Google hid it."
        },
        "displayUrl": {
          "type": "string",
          "description": "Address as shown. Optional."
        },
        "advertiser": {
          "type": "string",
          "description": "Advertiser name as shown. Optional."
        }
      }
    },
    "SearchAnswers": {
      "type": "object",
      "description": "Single-purpose Google widgets. Each key is present only when the page carried that widget. See https://portal.usestring.ai/docs/api-reference/search#answer-widgets",
      "properties": {
        "localTime": {
          "type": "object"
        },
        "currency": {
          "type": "object"
        },
        "unitConversion": {
          "type": "object",
          "description": "Carries `value`, `from`, `result` and `to`."
        },
        "weather": {
          "type": "object",
          "description": "Current conditions and a `forecast` list."
        },
        "translation": {
          "type": "object",
          "description": "Source and translated text and, when shown, a `dictionary`."
        },
        "sports": {
          "type": "object",
          "description": "A `team` and its `games`."
        },
        "flights": {
          "type": "object",
          "description": "The route and its `options`."
        }
      }
    },
    "SearchDiscussion": {
      "type": "object",
      "description": "A thread from the Discussions and forums block.",
      "required": [
        "position",
        "title"
      ],
      "properties": {
        "position": {
          "type": "integer"
        },
        "title": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "description": "When the destination is known."
        },
        "site": {
          "type": "string"
        },
        "forum": {
          "type": "string"
        },
        "comments": {
          "type": "string",
          "description": "As displayed, such as `140+ comments`."
        },
        "age": {
          "type": "string"
        },
        "excerpt": {
          "type": "string"
        }
      }
    },
    "SearchEntity": {
      "type": "object",
      "description": "The knowledge panel for the one business or person the query named.",
      "properties": {
        "title": {
          "type": "string",
          "description": "The entity's name."
        },
        "subtitle": {
          "type": "string",
          "description": "The type line under the name. Optional."
        },
        "description": {
          "type": "string",
          "description": "The panel's summary paragraph. Optional."
        },
        "descriptionSource": {
          "type": "object",
          "description": "Where the description came from.",
          "properties": {
            "name": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "description": "Resolved URL, when there is one."
            }
          }
        },
        "rating": {
          "type": "number",
          "description": "Star rating out of 5. Optional."
        },
        "reviews": {
          "type": "integer",
          "description": "Review count as displayed. Optional."
        },
        "website": {
          "type": "object",
          "description": "The panel's Website button.",
          "properties": {
            "url": {
              "type": "string",
              "description": "Absent when the button led nowhere readable."
            }
          }
        },
        "attributes": {
          "type": "array",
          "description": "Labelled facts in panel order.",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Google attribute id, when the row carried one."
              },
              "label": {
                "type": "string"
              },
              "value": {
                "type": "string"
              }
            }
          }
        },
        "profiles": {
          "type": "array",
          "description": "Social-media links from the panel.",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          }
        },
        "unread": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Attribute ids of panel modules that were not read. Empty when the whole card was read."
        }
      }
    },
    "SearchImage": {
      "type": "object",
      "description": "An image. With `searchType: images` all fields can appear; on a `web` search (the Images block) only `position`, `title`, `url` and `source`.",
      "properties": {
        "position": {
          "type": "integer",
          "description": "1-based place in `images`."
        },
        "title": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "description": "The page the image appears on."
        },
        "source": {
          "type": "string",
          "description": "The site's name. Optional."
        },
        "imageUrl": {
          "type": "string",
          "description": "The image file itself. Optional."
        },
        "imageWidth": {
          "type": "integer",
          "description": "Width in pixels. Optional."
        },
        "imageHeight": {
          "type": "integer",
          "description": "Height in pixels. Optional."
        },
        "thumbnail": {
          "type": "string",
          "description": "Google's resized copy. Optional."
        }
      }
    },
    "SearchOverview": {
      "type": "object",
      "description": "A Google-generated summary. The query's own overview comes first with no `topic`; entries with `topic` and `question` are Things to know tabs. A summary is never a result.",
      "properties": {
        "topic": {
          "type": "string",
          "description": "The tab's title. Absent on the query's own overview."
        },
        "question": {
          "type": "string",
          "description": "The sub-question a tab answers. Absent on the query's own overview."
        },
        "declined": {
          "type": "boolean",
          "description": "`true` when Google rendered the frame and did not answer (or the overview was streamed and `aiOverview` was not set). Absent otherwise."
        },
        "text": {
          "type": "string",
          "description": "The summary as plain text; list items start with `- `."
        },
        "sources": {
          "type": "array",
          "description": "Cited pages, in order.",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "description": "Absent when the citation could not be resolved."
              }
            }
          }
        }
      }
    },
    "SearchPaging": {
      "type": "object",
      "description": "How a `searchCount` request was filled. Present only when `searchCount` was sent.",
      "properties": {
        "pages": {
          "type": "integer",
          "description": "Number of results pages that answered."
        },
        "complete": {
          "type": "boolean",
          "description": "`false` when paging stopped early (`page_failed` or `deadline`); the response is still a 200 with the results collected so far."
        },
        "stoppedBy": {
          "type": "string",
          "enum": [
            "search_count",
            "end_of_results",
            "page_cap",
            "page_failed",
            "deadline"
          ],
          "description": "Why paging stopped: `search_count` (count reached), `end_of_results` (no more results), `page_cap` (36-page limit), `page_failed` (a later page failed), `deadline` (45-second budget ran out)."
        }
      }
    },
    "SearchPlace": {
      "type": "object",
      "description": "A business listing from a local pack, or with `searchType: places` the whole answer.",
      "properties": {
        "position": {
          "type": "integer",
          "description": "1-based order of the listing."
        },
        "name": {
          "type": "string",
          "description": "Business name."
        },
        "category": {
          "type": "string",
          "description": "Business category as Google labels it. Optional."
        },
        "rating": {
          "type": "number",
          "description": "Star rating out of 5. Optional."
        },
        "reviews": {
          "type": "integer",
          "description": "Review count as Google displays it; rounded past a thousand. Optional."
        },
        "address": {
          "type": "string",
          "description": "Street address line. Optional."
        },
        "phone": {
          "type": "string",
          "description": "Phone number as shown. Optional."
        },
        "hours": {
          "type": "string",
          "description": "Opening-hours line as shown. Optional."
        },
        "url": {
          "type": "string",
          "description": "The business's own website. Optional."
        },
        "mapsUrl": {
          "type": "string",
          "description": "Google Maps directions link; its path carries the full postal address. Optional."
        }
      }
    },
    "SearchProduct": {
      "type": "object",
      "description": "A product listing (`searchType: shopping`). Has no `url`.",
      "properties": {
        "position": {
          "type": "integer",
          "description": "1-based place in `products`."
        },
        "title": {
          "type": "string",
          "description": "Product name."
        },
        "productId": {
          "type": "string",
          "description": "Google's product ID. Optional."
        },
        "price": {
          "type": "string",
          "description": "Price as displayed, currency symbol included. Optional."
        },
        "originalPrice": {
          "type": "string",
          "description": "Price before a reduction. Present only when on sale."
        },
        "merchant": {
          "type": "string",
          "description": "The seller the listing names. Optional."
        },
        "moreMerchants": {
          "type": "boolean",
          "description": "`true` when other sellers offer the product too. Optional."
        },
        "delivery": {
          "type": "string",
          "description": "Delivery terms as displayed. Optional."
        },
        "returns": {
          "type": "string",
          "description": "Return terms as displayed. Optional."
        },
        "rating": {
          "type": "number",
          "description": "Average rating out of 5. Optional."
        },
        "reviews": {
          "type": "integer",
          "description": "Number of reviews, rounded past a thousand. Optional."
        }
      }
    },
    "SearchResult": {
      "type": "object",
      "description": "One ranked web document. Nothing else is ever placed in `results`.",
      "properties": {
        "position": {
          "type": "integer",
          "description": "1-based place in this response's `results`. Continues across pages on a `searchCount` request."
        },
        "rank": {
          "type": "integer",
          "description": "Absolute Google rank (page offset plus place on that page); can skip numbers. Google only."
        },
        "title": {
          "type": "string",
          "description": "Result title."
        },
        "url": {
          "type": "string",
          "description": "The page the result links to, without redirect or tracking parameters. Safe to fetch. Absent when Google linked the result only through an unknown redirect."
        },
        "displayUrl": {
          "type": "string",
          "description": "Google's displayed URL line. Cosmetic; empty when Google shows none. Not guaranteed to be fetchable."
        },
        "displayText": {
          "type": "string",
          "description": "The source line Google shows under the title, verbatim. Display text, not a URL or number. Google only."
        },
        "source": {
          "type": "string",
          "description": "Site name Google shows beside the result, such as `Reddit · r/buildapc`. Optional; Google only."
        },
        "snippet": {
          "type": "string",
          "description": "Result description text."
        },
        "video": {
          "type": "object",
          "description": "With `searchType: videos`. Each field optional.",
          "properties": {
            "channel": {
              "type": "string",
              "description": "The publisher."
            },
            "platform": {
              "type": "string",
              "description": "Such as `YouTube`."
            },
            "duration": {
              "type": "string",
              "description": "Such as `12:48`."
            }
          }
        },
        "book": {
          "type": "object",
          "description": "With `searchType: books`. Each field optional.",
          "properties": {
            "authors": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Author names."
            },
            "published": {
              "description": "The year or date of publication."
            }
          }
        }
      }
    },
    "SearchSitelink": {
      "type": "object",
      "description": "A sub-page listed under a navigational result.",
      "required": [
        "position",
        "title"
      ],
      "properties": {
        "position": {
          "type": "integer"
        },
        "resultPosition": {
          "type": "integer",
          "description": "The rank of the result the sub-page sits under."
        },
        "title": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "description": "When the destination is known."
        },
        "description": {
          "type": "string"
        }
      }
    },
    "SearchSpelling": {
      "type": "object",
      "description": "Google's correction or suggestion for the query.",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "substituted",
            "suggested"
          ],
          "description": "`substituted`: results are for the corrected query. `suggested`: Google only offered it; results are for the query as typed."
        },
        "query": {
          "type": "string",
          "description": "The corrected text."
        },
        "asked": {
          "type": "string",
          "description": "The original query."
        }
      }
    },
    "SearchVideo": {
      "type": "object",
      "description": "An entry of the Videos or Short videos block.",
      "required": [
        "position",
        "title"
      ],
      "properties": {
        "position": {
          "type": "integer"
        },
        "title": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "description": "When the destination is known."
        },
        "platform": {
          "type": "string"
        },
        "channel": {
          "type": "string"
        },
        "date": {
          "type": "string"
        },
        "duration": {
          "type": "string"
        }
      }
    }
  }
}