POST /search

POST https://request.usestring.ai/v1/search

Request body

Any other field is rejected with a 400. So is a searchCount above 300 (the error names the maximum; the value is never silently clamped), and so is location or coordinates sent with any engine other than "google" or "google_ai_mode". page, dateRange, sortBy, aiOverview, searchType and the filters sent with any engine other than "google", Google AI Mode included, are rejected with a 400 that names the field, and so is "format": "raw". searchCount sent with "format": "raw" is rejected with a 400; use page instead.

Country codes are case-insensitive and normalized to uppercase, so "gb" and "GB" behave the same way. Country and language apply to every engine, Google AI Mode included.

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "construction consulting firms", "engine": "mojeek", "country": "GB", "language": "en" }'

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "construction consulting firms", "searchCount": 30 }'

Result count and paging

Without searchCount, a search returns one results page — about eight to ten organic results on Google. With it, a Google search keeps fetching further results pages until it has collected at least searchCount organic results or it is thirty-six pages deep, whichever comes first, and returns the first searchCount. To start from a later page, send page.

• Maximum 300. A larger value is rejected with a 400.

• Google often runs out first. Most queries have between about 100 and 200 Google results, so a large searchCount usually returns every result Google has, with stoppedBy: "end_of_results", rather than the full count.

• Positions continue across pages. results[].position runs 1, 2, 3 … through the whole list rather than restarting on each page, and a document Google repeats on a later page is kept once, at its first position. results[].rank is each result's own Google rank; see Results.

• Surfaces come from the first page only. places, entity, ads, overviews, relatedSearches, peopleAlsoAsk and the rest describe the first results page; later pages contribute organic results and nothing else.

• paging reports how the request was filled. It is present only when searchCount was sent: { "pages": 3, "complete": true, "stoppedBy": "search_count" }. pages is the number of results pages that answered. stoppedBy says why paging stopped:

  stoppedBy	Meaning	complete
  search_count	searchCount results were collected.	true
  end_of_results	Google had no more organic results, or the first page carried none (a query answered by a local pack or a knowledge panel alone is not paged).	true
  page_cap	The search reached its thirty-six-page limit. Google may have more results.	true
  page_failed	A later page could not be fetched.	false
  deadline	The search's 45-second time budget ran out before searchCount was reached.	false

  When complete is false the response is still a 200 carrying the results collected so far.

• Each page that answered is billed as one search. A request that collected results from three pages is billed as three searches at the rate on Pricing; a later page that failed or came back empty is not billed and is not counted in pages. Google carries about eight to ten organic results a page, so a searchCount of 100 is typically eleven to thirteen pages and is billed as that many searches. A search that pages to the end of Google's results is typically ten to twenty-five pages, and never more than thirty-six.

• Google AI Mode rejects searchCount with a 400: it answers with one generated answer, not ranked results.

• "format": "raw" rejects searchCount with a 400: raw returns one Google results page per request, so ask for each page with page.

Page

page picks the Google results page to start from, 1-based: page N is the page Google itself shows as N. It is an integer from 1 to 30 and defaults to 1.

• Without searchCount, the response is that one page. With "format": "raw" this is the only form: raw returns page N as HTML and rejects searchCount.
• With searchCount, searchCount results are collected starting from that page, paged as described in Result count and paging.
• page and searchCount together stay within the first 300 results. Page N starts at result (N-1)×10+1, so with page set, searchCount may be at most 300 - (N-1)×10; page 30 allows a searchCount of up to 10. A larger value is rejected with a 400 that states the maximum.
• position stays 1-based within the response, and rank is Google's. The first result of page 3 has position 1 and rank 21.
• A page past Google's last result is empty, not an error. It returns an empty results with zeroResults: true.
• Separate page requests can repeat or skip a result. Page N starts at Google's result (N-1)×10+1, but a Google page holds about eight to ten organic results, so a result can appear on two consecutive page requests or on neither. For one list without repeats, send a single request with searchCount instead.

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "construction consulting firms", "page": 3 }'

Date range and sort order

dateRange limits results to a publication window. Send one of "hour", "day", "week", "month" or "year" for the past hour through the past year, or an object with ISO calendar dates (YYYY-MM-DD) for a custom range:

A custom range needs from, to or both, and from must not be after to; either mistake, or a date that is not an ISO calendar date, is rejected with a 400.

sortBy orders the results: "relevance", the default, is Google's own ranking, and "date" puts the newest results first.

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "interest rate decision", "dateRange": "week", "sortBy": "date" }'

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "interest rate decision", "dateRange": { "from": "2024-01-01", "to": "2024-06-30" } }'

News articles are not a /search option: use the Google News site integration, POST /v1/integrations/googlenews/search.

Search type

searchType picks the Google tab to search. "web", the default, is the ordinary results page that the rest of this page describes. The other tabs answer in the shape of what they show:

With "images", "places" or "shopping", results is empty. Google News is not a searchType: use the Google News site integration.

• Each page is billed as one search, as on the web. One "images" search returns about 100 images and one "shopping" search about 55 products, for the price of one search.
• page and searchCount work on every tab except "shopping". On "images", page is 1 to 3 and a searchCount of up to 300 collects across the three pages, usually about 270 images, since a later page repeats some of the previous one's and each image is kept once. On "places", page N starts at business (N-1)×20+1. On "shopping", Google shows a single page: page must be 1, and searchCount returns at most the products that page holds.
• A page past the tab's last result is empty, not an error, and is billed as one search, as on the web.
• dateRange, sortBy and verbatim apply to "web", "videos" and "forums" only. "format": "raw" and aiOverview apply to "web" only. Any of them sent with another tab is rejected with a 400 that names the field.

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "eames lounge chair", "searchType": "images", "searchCount": 150 }'

Filters

These narrow a Google search on every tab, and each one applies to every page a searchCount search fetches.

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "climate policy", "restrictCountry": "FR", "safeSearch": true }'

Raw HTML

format is "structured" (the default), for results as JSON, or "raw", for HTML. We recommend "structured". With "raw" the response is the Google results page as HTML (Content-Type: text/html), one page per request. Choose the page with page; each raw request is billed as one search.

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "heat pump grants", "format": "raw", "page": 2 }'

<!doctype html><html lang="en">...</html>

Raw supports page only, not searchCount: a raw request with searchCount is rejected with a 400:

{
  "error": "Invalid request",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "searchCount": [
        "searchCount does not apply to format \"raw\"; raw answers one Google results page per request, so use page"
      ]
    }
  }
}

For more results as HTML, send one request per page. dateRange and sortBy work with "raw" exactly as they do with "structured". Sending "format": "raw" with any engine other than "google", Google AI Mode included, is rejected with a 400.

Location

Send location or coordinates with "engine": "google" to search from a place. The search is sent from that place's country, and results are biased toward the place. The fields take the same values as for AI Mode location: a name that cannot be placed is rejected with a 400, and if you send both, coordinates win.

Location biases results; it does not target a city exactly. The effect is strongest for queries that ask for something nearby, such as "plumbers near me". A bare query such as "coffee shops" may still return results from a wider area.

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "plumbers near me", "location": "Austin,Texas,United States" }'

Google AI Mode

"engine": "google_ai_mode" asks Google AI Mode the query and returns its answer in aiMode: the text, its structure, the pages it cites, and any products, places and videos the answer shows. results is always empty and zeroResults is false; no other surface is returned.

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "best trail running shoes and where to buy them in Portland", "engine": "google_ai_mode" }'

{
  "results": [],
  "zeroResults": false,
  "aiMode": {
    "text": "Top trail running shoes\nThe right shoe depends on terrain and how much cushioning you want.\nShoe | Best for | Drop\nHoka Speedgoat 6 | Long, technical trails | 5 mm\nSalomon Speedcross 6 | Mud and soft ground | 10 mm\nWhere to buy in Portland\n- Try them on at a specialty running store that offers gait analysis.",
    "markdown": "## Top trail running shoes\n\nThe right shoe depends on terrain and how much cushioning you want.\n\n| Shoe | Best for | Drop |\n| --- | --- | --- |\n| Hoka Speedgoat 6 | Long, technical trails | 5 mm |\n| Salomon Speedcross 6 | Mud and soft ground | 10 mm |\n\n## Where to buy in Portland\n\n- Try them on at a specialty running store that offers gait analysis.",
    "blocks": [
      { "type": "heading", "text": "Top trail running shoes", "level": 2 },
      { "type": "paragraph", "text": "The right shoe depends on terrain and how much cushioning you want." },
      {
        "type": "table",
        "header": ["Shoe", "Best for", "Drop"],
        "rows": [
          ["Hoka Speedgoat 6", "Long, technical trails", "5 mm"],
          ["Salomon Speedcross 6", "Mud and soft ground", "10 mm"]
        ]
      },
      { "type": "heading", "text": "Where to buy in Portland", "level": 2 },
      { "type": "list", "ordered": false, "items": ["Try them on at a specialty running store that offers gait analysis."] }
    ],
    "sources": [
      {
        "title": "The Best Trail Running Shoes of 2026",
        "url": "https://www.runnersworld.com/gear/best-trail-running-shoes",
        "snippet": "The Speedgoat remains our pick for long days on rocky, technical terrain.",
        "source": "Runner's World"
      },
      { "title": "Speedcross 6 review", "source": "Reddit" }
    ],
    "products": [
      {
        "title": "Hoka Speedgoat 6",
        "price": "$124.95",
        "oldPrice": "$155.00",
        "merchant": "REI",
        "moreSellers": true,
        "rating": 4.6,
        "reviews": 1840,
        "thumbnail": "https://encrypted-tbn0.gstatic.com/shopping?q=tbn:example",
        "productId": "4127739520180348614",
        "url": "https://www.google.com/search?ibp=oshop&prds=pid:4127739520180348614"
      }
    ],
    "places": [
      {
        "name": "Portland Running Company",
        "category": "Running store",
        "rating": 4.8,
        "reviews": 412,
        "priceLevel": "$$",
        "status": "Open · Closes 7 PM",
        "address": "3044 SE Division St, Portland, OR",
        "description": "Staff fit you after a gait analysis on the in-store treadmill.",
        "url": "https://www.google.com/search?q=Portland+Running+Company&ludocid=1234567890"
      }
    ]
  }
}

Every field except text and sources is absent when the answer has none.

Each entry in blocks has a type, which decides the other fields it carries:

• Country and language apply as for "google": they choose the Google domain and the answer's locale. With location or coordinates, the search is sent from that place's country instead, and the answer stays in language (or the default language for the country you sent).
• Billed as one search at the same rate as any other search. A request that fails is not billed.
• Unavailable answers fail. If an AI Mode answer isn't available for a query, the request returns a 502 rather than a results page. Retrying may succeed.
• The same answer is returned when you send a Google AI Mode URL (https://www.google.com/search?q=...&udm=50) to Fetch.

AI Mode location

AI Mode answers for a place when you send location or coordinates. The answer is given for that place, and the search is sent from the country the place is in. The same fields work with "engine": "google", where they bias results toward the place (see Location); sending either with any other engine is rejected with a 400.

• location is a place name, 1 to 200 characters: a city such as "London", or a fuller name such as "London,England,United Kingdom" or "Paris,Texas,United States" when the short name is ambiguous. A name that is only a country, such as "France", uses that country with no finer point. A name that cannot be placed is rejected with a 400; send coordinates instead.

• coordinates is the exact point:

  Field	Type	Description
  latitude	number	Required. Decimal degrees, -90 to 90.
  longitude	number	Required. Decimal degrees, -180 to 180.
  radius	integer	How precise the point is, in meters, 1 to 1,000,000. Default 5000.

• If you send both, coordinates win.

• Without either, a question that depends on where you are, such as today's weather or "near me", may be answered without a location.

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "what is the weather today", "engine": "google_ai_mode", "location": "London" }'

curl https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "best bakeries near me", "engine": "google_ai_mode", "coordinates": { "latitude": 48.8566, "longitude": 2.3522 } }'

Response

Every field beside results, zeroResults and paging is a surface Google rendered around the ranked documents. Each one is present only when the page carried it, so a typical response has results and zeroResults alone, and only Google returns any of them. Nothing in these fields is ever placed in results, and none of them makes a page with no documents a successful search.

{
  "results": [
    {
      "position": 1,
      "title": "How to Choose Running Shoes",
      "url": "https://www.rei.com/learn/expert-advice/running-shoes.html",
      "displayUrl": "https://www.rei.com › learn",
      "displayText": "https://www.rei.com › learn",
      "snippet": "A short description of the page as shown on the results page."
    },
    {
      "position": 2,
      "title": "Best running shoes for beginners?",
      "url": "https://www.reddit.com/r/running/comments/example/best_running_shoes_for_beginners/",
      "displayUrl": "",
      "displayText": "20+ comments · 3 months ago",
      "source": "Reddit · r/running",
      "snippet": "A short description of the page as shown on the results page."
    }
  ],
  "zeroResults": false,
  "spelling": { "kind": "suggested", "query": "running shoes", "asked": "runing shoes" },
  "ads": [
    { "position": 1, "format": "text", "block": "top", "title": "Running Shoes Sale", "url": "https://www.example-shop.com/running", "displayUrl": "www.example-shop.com", "advertiser": "Example Shop" }
  ],
  "places": [
    { "position": 1, "name": "Example Running Store", "category": "Shoe store", "rating": 4.8, "reviews": 312, "address": "10 High St", "phone": "(555) 010-2000", "hours": "Open ⋅ Closes 7 PM", "url": "https://www.example-running.com/" }
  ],
  "entity": {
    "title": "Example Running Store",
    "subtitle": "Shoe store in Springfield, Ohio",
    "descriptionSource": { "name": "Example Running Store", "url": "https://www.example-running.com/about" },
    "rating": 4.8,
    "reviews": 312,
    "website": { "url": "https://www.example-running.com/" },
    "attributes": [{ "label": "Address", "value": "10 High St, Springfield, OH 45501" }],
    "profiles": [],
    "unread": []
  },
  "relatedSearches": ["trail running shoes", "best running shoes 2026"],
  "peopleAlsoAsk": [{ "question": "How often should you replace running shoes?" }],
  "answers": {
    "unitConversion": { "category": "Length", "value": 5, "from": "mile", "result": 8.04672, "to": "kilometer" }
  },
  "videos": [
    { "position": 1, "title": "How to pick running shoes", "url": "https://www.youtube.com/watch?v=example", "platform": "YouTube", "channel": "Example Channel", "date": "Mar 2, 2026", "duration": "8:12" }
  ],
  "discussions": [
    { "position": 1, "title": "What running shoes do you actually wear?", "url": "https://www.reddit.com/r/running/comments/example", "site": "Reddit", "forum": "r/running", "comments": "140+ comments", "age": "2mo" }
  ],
  "sitelinks": [
    { "position": 1, "resultPosition": 1, "title": "Men's", "url": "https://www.rei.com/c/mens-running-shoes" }
  ],
  "overviews": [
    {
      "text": "Running shoes are primarily categorized by terrain and by the runner's gait.\n- Daily trainers: cushioned shoes for most weekly mileage.",
      "sources": [{ "title": "How to Choose Running Shoes", "url": "https://www.rei.com/learn/expert-advice/running-shoes.html" }]
    },
    { "topic": "Types", "question": "What are the different types of running shoes?", "text": "Road, trail, and track shoes differ in outsole and cushioning.", "sources": [] }
  ]
}

Results

Every entry in results is a web document. Nothing else is ever placed in this list, so its length is always the number of ranked pages the engine returned.

Use url to fetch a result. displayUrl is never built from url. Google shows no URL line for many social and forum results, including Reddit, YouTube, Instagram, Facebook, LinkedIn, Quora, Stack Overflow, X and Pinterest, and for those displayUrl is an empty string. displayText holds whatever Google shows in that line, in the results page's language, so a German search can return Ca. 50 Kommentare · vor 1 Jahr. Treat it as display text, not as a URL or a number.

Empty results

An empty results array has two different causes, and zeroResults tells them apart:

• zeroResults: true — the engine answered and reported that nothing matched. Retrying will not help; broaden the query instead.
• zeroResults: false — the page carried no ranked documents but was not a no-match page. On Google this is a query answered with a local pack (see places) or a knowledge panel (see entity); check those fields before treating the response as empty. No other surface can stand in for results: a page with only ads or only a generated summary is a failed search and is reported with a non-200 status.

A search that could not be completed at all is reported with a non-200 status code, never as an empty 200.

Spelling

When Google corrects the query, spelling says what it did. kind is "substituted" when Google searched the corrected query in place of the one asked and the results are for that query, or "suggested" when it only offered one and the results are for the query as typed. query is the corrected text and asked the original.

Ads

Sponsored results, in page order, kept out of results so a caller counting documents never counts an advertisement.

Places

Google answers some queries — typically one naming a business, a professional, or a service in a town — with a local pack of business listings and few or no web results. Those listings are returned in places, never in results, so a caller that counts or iterates results sees only documents. places is present only when the results page carried a local pack; when it is absent the page had none.

{
  "results": [],
  "zeroResults": false,
  "places": [
    {
      "position": 1,
      "name": "Example Dental",
      "category": "Dentist",
      "rating": 4.9,
      "reviews": 726,
      "address": "123 High St #200",
      "phone": "(555) 010-4040",
      "hours": "Open ⋅ Closes 5 PM",
      "url": "https://www.example-dental.com/",
      "mapsUrl": "https://www.google.com/maps/dir//Example+Dental,+123+High+St+%23200,+Springfield,+OH+45501"
    }
  ]
}

Images

With "searchType": "images", images is the answer: one entry per image, in Google's order.

On a "web" search, images is the page's "Images" block instead, and its entries carry position, title, url and source only.

Products

With "searchType": "shopping", products is the answer: one entry per product listing, in Google's order.

A product listing has no url: Google links it only to its own product page.

Entity panel

When a query names one business or person — a practice in a town, a public figure, a landmark — Google often answers with a knowledge panel and few or no web results. That card is returned in entity, never in results, so a caller that counts or iterates results still sees only documents. entity is present only when the results page carried a panel; when it is absent the page had none. A page can carry both a local pack and a panel, in which case both places and entity are returned.

{
  "results": [],
  "zeroResults": false,
  "entity": {
    "title": "Example Aesthetics and Wellness",
    "subtitle": "Medical spa in Springfield, Ohio",
    "description": "Example Aesthetics offers injectables, laser treatments and wellness services in a boutique setting.",
    "descriptionSource": {
      "name": "Example Aesthetics",
      "url": "https://www.example-aesthetics.com/about"
    },
    "rating": 5,
    "reviews": 12,
    "website": {
      "url": "https://www.example-aesthetics.com/"
    },
    "attributes": [
      { "id": "kc:/local:address", "label": "Address", "value": "26 E Main St B, Springfield, OH 45501" },
      { "label": "Phone", "value": "(555) 010-1056" },
      { "label": "Hours", "value": "Closed ⋅ Opens 8 AM Mon" }
    ],
    "profiles": [
      { "name": "Instagram", "url": "https://www.instagram.com/example-aesthetics/" }
    ],
    "unread": ["kc:/local:popular_times"]
  }
}

Related searches and People also ask

relatedSearches is the list of query strings Google suggests at the foot of the page. peopleAlsoAsk is the list of collapsed questions, each as { "question": "…" }; Google fetches an answer only when a reader expands one, so no answer text is on the page.

Answer widgets

For a query whose shape triggers one, Google renders a single-purpose widget above the results, and answers carries it under one of localTime, currency, unitConversion, weather, translation, sports, or flights. Each is present only when the page carried that widget. A conversion carries value, from, result and to; weather carries current conditions and a forecast list; a translation carries the source and translated text and, when shown, a dictionary; sports carries a team and its games; flights carries the route and its options.

Ranked blocks

Google shows several ranked lists apart from the documents, and each stays apart here. Every entry carries a position and a title, and a url when its destination is known.

• videos and shortVideos add platform, channel, date and duration where shown.
• discussions adds site, forum, comments, age and excerpt where shown.
• images adds source, the site the image came from.
• sitelinks adds resultPosition, the rank of the result the sub-page sits under, and description where shown.

AI overviews

overviews is every generated summary the page carried. The query's own overview, when Google composed one, comes first with no topic; entries with a topic and a question are the "Things to know" tabs beneath it, one per sub-question Google chose. When Google rendered the frame and declined to answer, the list holds one entry with declined: true and no text; that is a third state, and retrying will not produce an answer. A streamed overview also comes back as declined: true unless the request set aiOverview; see Streamed AI Overviews. Google omits the summary on many queries, so absence means nothing about the query.

A summary is never a result. A page with an overview and no documents is still a failed search.

Streamed AI Overviews

Google renders many AI Overviews as a placeholder and streams the summary in after the page has loaded. Reading that stream takes a second request, made after the results page, so it is off by default:

• Off by default. Without aiOverview, an AI Overview already present in the page is returned as usual. A streamed one is returned as an entry with declined: true and no text.
• "aiOverview": true fills it. The request makes a second, sequential fetch to read the stream, and the overview arrives with its text and sources.
• It adds latency. Measured on production traffic from 2026-09-30 to 2026-10-01, about 64% of results pages carried a streamed overview, and filling it added about 2.8 s at p50 and 5.6 s at p90 to those requests.
• It costs 2x a normal search. A request with "aiOverview": true is billed as two searches. With searchCount, only the first page carries the overview and the extra charge; later pages bill as one search each. A request that fails is not billed.

curl -X POST https://request.usestring.ai/v1/search \
  -H "Authorization: Bearer $STRING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "best cushioned marathon shoes", "aiOverview": true }'

Only Google returns these surfaces. Other engines return results and zeroResults only.

Status codes

See Search overview for billing.