--- title: "Search the web" method: POST path: "/search" tags: ["Search"] --- # Search the web `POST /search` ## Request - Base URL: `https://request.usestring.ai/v1` - URL: `https://request.usestring.ai/v1/search` - Auth: HTTP bearer Run a web search on Google (default), DuckDuckGo, Brave or Mojeek and return the ranked organic results, plus Google page surfaces such as ads, local places, the knowledge panel and AI overviews. Set `engine: google_ai_mode` for Google AI Mode's answer instead. Use it when you have a query rather than a URL; fetch a result's `url` with fetchUrl to read the page. ## Request body - SearchRequest: Request body for POST /search. Any other field is rejected with a 400. - `query` string, required: The search query to run. - `engine` 'google' | 'duckduckgo' | 'brave' | 'mojeek' | 'google_ai_mode': Search engine. `google_ai_mode` returns Google's AI Mode answer in `aiMode` instead of ranked results. - `country` string: ISO 3166-1 alpha-2 country code used to localize results. Case-insensitive. Applies to every engine. - `language` string: Language tag for result language, such as `en` or `pt-br`. Applies to every engine. - `searchCount` integer: Number of organic results wanted. Google is paged until that many are collected (each page that answered bills as one search); the response then includes `paging`. With `page` N set, the maximum is 300 - (N-1)*10. Rejected with `format: raw` and with `google_ai_mode`. Without it, one results page is returned (about 8 to 10 Google results). - `location` string: Place name to search from, such as `London` or `Paris,Texas,United States`. `google` and `google_ai_mode` only. A name that cannot be placed is a 400; send `coordinates` instead. - `coordinates` SearchCoordinates: An exact point to search from. Takes precedence over `location`. - `latitude` number, required: Decimal degrees. - `longitude` number, required: Decimal degrees. - `radius` integer: How precise the point is, in meters. - `page` integer: Google results page to start from; page N is the page Google shows as N. On `images` the range is 1 to 3; on `shopping` it must be 1. A page past the last result returns empty `results` with `zeroResults: true`. `google` engine only; sending it with another engine (Google AI Mode included) is a 400. - `dateRange` union: Publication window. A preset (`hour`, `day`, `week`, `month`, `year` for the past hour through the past year), or a custom range of ISO calendar dates. `google` engine only; `web`, `videos` and `forums` search types only. - 'hour' | 'day' | 'week' | 'month' | 'year' - object: Custom range. Needs `from`, `to` or both, and `from` must not be after `to`. - `from` string, date: First day of the range, inclusive (YYYY-MM-DD). - `to` string, date: Last day of the range, inclusive (YYYY-MM-DD). - `sortBy` 'relevance' | 'date': Result order. `date` puts the newest first. `web`, `videos` and `forums` search types only. `google` engine only; sending it with another engine (Google AI Mode included) is a 400. - `format` 'structured' | 'raw': `structured` returns results as JSON (recommended). `raw` returns the Google results page as HTML (`text/html`), one page per request; choose the page with `page`. `raw` applies to the `web` search type only. `google` engine only; sending it with another engine (Google AI Mode included) is a 400. - `aiOverview` boolean: Make a second, sequential fetch to fill an AI Overview that Google streams in after the page loads. Adds latency and bills as two searches. Without it, a streamed overview comes back as `declined: true`. `web` search type only. `google` engine only; sending it with another engine (Google AI Mode included) is a 400. - `searchType` 'web' | 'images' | 'videos' | 'shopping' | 'books' | 'places' | 'forums': Google tab to search. `images` answers in `images`, `places` in `places`, `shopping` in `products` (with `results` empty); the other tabs answer in `results`. `google` engine only; sending it with another engine (Google AI Mode included) is a 400. - `safeSearch` boolean: `true` removes explicit results (Google SafeSearch). `google` engine only; sending it with another engine (Google AI Mode included) is a 400. - `includeOmittedResults` boolean: `true` includes results Google normally hides as very similar to ones already shown. `google` engine only; sending it with another engine (Google AI Mode included) is a 400. - `autocorrect` boolean: `false` searches the query exactly as sent instead of Google's corrected spelling. `google` engine only; sending it with another engine (Google AI Mode included) is a 400. - `restrictCountry` string: ISO 3166-1 alpha-2 code. Returns only pages from that country (unlike `country`, which sets where the search is made from). `google` engine only; sending it with another engine (Google AI Mode included) is a 400. - `verbatim` boolean: `true` matches the query's words exactly, without synonyms or variations. `web`, `videos` and `forums` search types only. `google` engine only; sending it with another engine (Google AI Mode included) is a 400. ## Response `200` Search completed. - SearchResponse: 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. - `results` SearchResult[], required: Ranked web results in engine order. Empty when the page carried no documents. - `position` integer: 1-based place in this response's `results`. Continues across pages on a `searchCount` request. - `rank` integer: Absolute Google rank (page offset plus place on that page); can skip numbers. Google only. - `title` string: Result title. - `url` string: 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` string: Google's displayed URL line. Cosmetic; empty when Google shows none. Not guaranteed to be fetchable. - `displayText` string: The source line Google shows under the title, verbatim. Display text, not a URL or number. Google only. - `source` string: Site name Google shows beside the result, such as `Reddit · r/buildapc`. Optional; Google only. - `snippet` string: Result description text. - `video` object: With `searchType: videos`. Each field optional. - `channel` string: The publisher. - `platform` string: Such as `YouTube`. - `duration` string: Such as `12:48`. - `book` object: With `searchType: books`. Each field optional. - `authors` string[]: Author names. - `published` unknown - `zeroResults` boolean, required: `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` SearchPaging: How a `searchCount` request was filled. Present only when `searchCount` was sent. - `pages` integer: Number of results pages that answered. - `complete` boolean: `false` when paging stopped early (`page_failed` or `deadline`); the response is still a 200 with the results collected so far. - `stoppedBy` 'search_count' | 'end_of_results' | 'page_cap' | 'page_failed' | 'deadline': 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). - `spelling` SearchSpelling: Google's correction or suggestion for the query. - `kind` 'substituted' | 'suggested': `substituted`: results are for the corrected query. `suggested`: Google only offered it; results are for the query as typed. - `query` string: The corrected text. - `asked` string: The original query. - `ads` SearchAd[] - `position` integer: 1-based order within the page's ad blocks. - `format` 'text' | 'shopping' - `block` string: Where the ad sat, such as `top` or `bottom`. - `title` string: Ad headline. Optional. - `url` string: The advertiser's destination. Absent when Google hid it. - `displayUrl` string: Address as shown. Optional. - `advertiser` string: Advertiser name as shown. Optional. - `places` SearchPlace[] - `position` integer: 1-based order of the listing. - `name` string: Business name. - `category` string: Business category as Google labels it. Optional. - `rating` number: Star rating out of 5. Optional. - `reviews` integer: Review count as Google displays it; rounded past a thousand. Optional. - `address` string: Street address line. Optional. - `phone` string: Phone number as shown. Optional. - `hours` string: Opening-hours line as shown. Optional. - `url` string: The business's own website. Optional. - `mapsUrl` string: Google Maps directions link; its path carries the full postal address. Optional. - `products` SearchProduct[]: Present only with `searchType: shopping`. - `position` integer: 1-based place in `products`. - `title` string: Product name. - `productId` string: Google's product ID. Optional. - `price` string: Price as displayed, currency symbol included. Optional. - `originalPrice` string: Price before a reduction. Present only when on sale. - `merchant` string: The seller the listing names. Optional. - `moreMerchants` boolean: `true` when other sellers offer the product too. Optional. - `delivery` string: Delivery terms as displayed. Optional. - `returns` string: Return terms as displayed. Optional. - `rating` number: Average rating out of 5. Optional. - `reviews` integer: Number of reviews, rounded past a thousand. Optional. - `entity` SearchEntity: The knowledge panel for the one business or person the query named. - `title` string: The entity's name. - `subtitle` string: The type line under the name. Optional. - `description` string: The panel's summary paragraph. Optional. - `descriptionSource` object: Where the description came from. - `name` string - `url` string: Resolved URL, when there is one. - `rating` number: Star rating out of 5. Optional. - `reviews` integer: Review count as displayed. Optional. - `website` object: The panel's Website button. - `url` string: Absent when the button led nowhere readable. - `attributes` object[]: Labelled facts in panel order. - `id` string: Google attribute id, when the row carried one. - `label` string - `value` string - `profiles` object[]: Social-media links from the panel. - `name` string - `url` string - `unread` string[]: Attribute ids of panel modules that were not read. Empty when the whole card was read. - `relatedSearches` string[]: Query strings from the Related searches block. - `peopleAlsoAsk` object[]: Questions from the People also ask block. No answer text is on the page. - `question` string - `answers` SearchAnswers: 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 - `localTime` object - `currency` object - `unitConversion` object: Carries `value`, `from`, `result` and `to`. - `weather` object: Current conditions and a `forecast` list. - `translation` object: Source and translated text and, when shown, a `dictionary`. - `sports` object: A `team` and its `games`. - `flights` object: The route and its `options`. - `videos` SearchVideo[] - `position` integer, required - `title` string, required - `url` string: When the destination is known. - `platform` string - `channel` string - `date` string - `duration` string - `shortVideos` SearchVideo[]: Entries of the Short videos block, same shape as `videos`. - `position` integer, required - `title` string, required - `url` string: When the destination is known. - `platform` string - `channel` string - `date` string - `duration` string - `discussions` SearchDiscussion[] - `position` integer, required - `title` string, required - `url` string: When the destination is known. - `site` string - `forum` string - `comments` string: As displayed, such as `140+ comments`. - `age` string - `excerpt` string - `images` SearchImage[] - `position` integer: 1-based place in `images`. - `title` string - `url` string: The page the image appears on. - `source` string: The site's name. Optional. - `imageUrl` string: The image file itself. Optional. - `imageWidth` integer: Width in pixels. Optional. - `imageHeight` integer: Height in pixels. Optional. - `thumbnail` string: Google's resized copy. Optional. - `sitelinks` SearchSitelink[] - `position` integer, required - `resultPosition` integer: The rank of the result the sub-page sits under. - `title` string, required - `url` string: When the destination is known. - `description` string - `overviews` SearchOverview[] - `topic` string: The tab's title. Absent on the query's own overview. - `question` string: The sub-question a tab answers. Absent on the query's own overview. - `declined` boolean: `true` when Google rendered the frame and did not answer (or the overview was streamed and `aiOverview` was not set). Absent otherwise. - `text` string: The summary as plain text; list items start with `- `. - `sources` object[]: Cited pages, in order. - `title` string - `url` string: Absent when the citation could not be resolved. - `aiMode` AiModeAnswer: Google AI Mode's answer (`engine: google_ai_mode`). Every field except `text` and `sources` is absent when the answer has none. - `text` string, required: The answer as plain text in reading order. - `markdown` string: The same answer as Markdown. - `blocks` AiModeBlock[]: The answer's structure in reading order. - `type` 'paragraph' | 'heading' | 'list' | 'table' | 'code', required - `text` string - `level` integer: Heading level. - `items` string[]: One string per list item. - `ordered` boolean: `true` for a numbered list. - `header` string[]: Column names. - `rows` array[]: One array per row, one cell per column. - string[] - `language` string: Code block language, when labelled. - `sources` object[], required: Pages the answer cites, in order. Empty when Google cited none. - `title` string: Optional. - `url` string: Absent when the citation could not be resolved. - `snippet` string: The quoted passage. Optional. - `source` string: The site's name. Optional. - `products` object[]: Products the answer recommends. - `title` string: Product name. - `price` string: As displayed. Optional. - `oldPrice` string: Price before a reduction. Present only on sale. - `merchant` string: Optional. - `moreSellers` boolean: Optional. - `rating` number: Optional. - `reviews` integer: Optional. - `thumbnail` string: Optional. - `productId` string: Google's product ID. Optional. - `url` string: Google's page for the product. Optional. - `places` object[]: Businesses and places the answer names. - `name` string - `category` string: Optional. - `rating` number: Optional. - `reviews` integer: English-language answers only. - `priceLevel` string: Such as `$$`. Optional. - `status` string: Opening status as displayed. Optional. - `address` string: Optional. - `description` string: Optional. - `url` string: Google's page for the place. Optional. - `videos` object[]: Videos the answer cites. - `title` string - `url` string: Optional. - `channel` string: Optional. - `duration` string: Optional. - `thumbnail` string: Optional. ## Other responses - `400`: Validation error: missing `query`, an invalid option, an unrecognized field, an option sent with an engine or search type that does not support it, or a `location` that cannot be placed. - `401`: Missing or invalid Authorization header. - `402`: The key is valid but the account balance can't cover the request. - `403`: Verification challenge that could not be cleared. - `429`: Rate limit exceeded. The default limit is 60 requests per second per organization, averaged over a rolling window. Back off and retry with exponential backoff and jitter. - `500`: Internal server error. - `502`: The search could not be completed, such as a Google AI Mode answer that could not be read. Retrying may succeed. --- [API](https://skmtc.dev/usestring/apis/string-web-access-api.md) · [All operations](https://skmtc.dev/usestring/apis/string-web-access-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usestring/apis/string-web-access-api/revisions/fd336960036e?raw)