# Google Web Search API

> Search Google web results with q, language hl, country gl and a supported device. Result sections depend on the query and upstream response. `POST https://api.serpbase.dev/google/search`, 1 credit per request.

Source: https://serpbase.dev/docs/google_web_search · Index: https://serpbase.dev/llms.txt · OpenAPI: https://serpbase.dev/openapi.json

API reference · Search engines

Search Google web results with q, language hl, country gl and a supported device. Result sections depend on the query and upstream response.

POST `https://api.serpbase.dev/google/search`
1 credit [Open in Playground](https://serpbase.dev/playground?product=google_web_search)

## Example

```bash
curl -X POST 'https://api.serpbase.dev/google/search' \
  -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  --max-time 60 \
  -d '{"device":"mobile","gl":"us","hl":"en","q":"coffee shops"}'
```

Response · real, shortened

```
{
  "status": 0,
  "credits_charged": 1,
  "request_id": "r-4b27fe8a36d9ac303a5da7dd",
  "product_id": "google_web_search",
  "query": "coffee shops",
  "local_results": [
    {
      "address": "Denver, CO",
      "category": "Coffee shop",
      "hours": "Open",
      "position": 1,
      "rank": 1,
      "rating": "4.9",
      "reviews_count": "455",
      "title": "Coffeegraph"
    },
    {
      "address": "Sioux Falls, SD",
      "category": "Coffee shop",
      "hours": "Open",
      "position": 1,
      "rank": 2,
      "rating": "4.9",
      "reviews_count": "295",
      "title": "The Breaks Coffee Roasting Co."
    }
  ],
  "organic": [
    {
      "date": "Sep 17, 2026",
      "display_link": "www.discovertheburgh.com",
      "display_url": "www.discovertheburgh.com",
      "link": "https://www.discovertheburgh.com/pittsburgh-coffee-shops/",
      "position": 3,
      "published_at": "Sep 17, 2026",
      "rank": 1,
      "snippet": "🏨 Book Avenue in Garfield. Redhawk Coffee. Ghost Coffee Collab at Trace Brewing. Kaibur Coffee Kaibu…",
      "source_url": "https://www.google.com/goto?url=CAESdAHrOzAVQPT8-1-RxOq_G62WuAgUAmaFDk4SD6YsadPoLMH5lbvuR0WPu8BR2EKN…",
      "title": "48 Pittsburgh Coffee Shops to Grab a Delicious Brew",
      "url": "https://www.discovertheburgh.com/pittsburgh-coffee-shops/"
    }
  ],
  "page": 1,
  "people_also_ask": [
    {
      "position": 2,
      "question": "What are the top 10 coffee chains?"
    },
    {
      "position": 2,
      "question": "What are the main coffee shop chains?"
    }
  ],
  "people_also_search_for": [
    "Best coffee shops",
    "Coffee shops Orlando"
  ],
  "related_searches": [
    "Best coffee shops in Pittsburgh to study",
    "Coffee Shops near Monroeville PA"
  ],
  "search_type": "search"
}
```

## Parameters

| Name | What it does |
| --- | --- |
| `q` required string | Search query string. |
| `hl` string | Language code. Defaults to en. |
| `gl` string | Country code. Defaults to us. |
| `location` string | Where the search is made from, as a Google canonical location name: a country ("Germany"), a region ("Bavaria,Germany") or a city ("Munich,Bavaria,Germany"). Look names up with GET /google/locations. Case and spaces after commas are ignored. A name that is not in the list is not sent to Google and the search runs as if location were omitted. Use it together with gl and hl for the same market. It takes effect only with the mobile device (the default); with device pc Google places the search by the exit IP and ignores location. Optional; same credits. |
| `page` number | 1-based page number. Defaults to 1. |
| `device` "mobile" \| "pc" \| "default" | Google Search only. mobile returns the phone layout, pc (or desktop) the desktop layout; default and an omitted field mean mobile. The page is fetched from a real session of that device, so modules such as the knowledge panel differ between the two. |
| `format` "json" \| "raw" \| "markdown" | json (default) returns the parsed result. markdown returns the same result as Markdown text (text/markdown) for language models: no envelope, no duplicate alias fields, no inline images. raw returns the Google page itself as text/html, with the platform's session identifiers, Google's scripts and tracking beacons removed and result links already resolved; with raw, queries with search operators are also served by the signed lanes, so a raw page is always a real desktop or phone page. All formats cost the same credits; failures keep the JSON envelope. |
| `timeout` number | How many seconds you will wait, 1 to 30 (decimals allowed). Optional; without it the platform spends up to 30 seconds. With it, retries on other routes start earlier so an answer can still arrive inside your budget, and when the budget runs out the request ends with status 1504 and is not charged, instead of being cut off by your HTTP client. Keep your client's own timeout above this value. |

Search can also return ai_overview, weather, finance, flight, and result_stats when those modules appear in the SERP.

## What comes back

Fields that are not on the page for a given request are left out rather than sent empty.

| Field | Type | Availability | Description |
| --- | --- | --- | --- |
| `query` required | string | required | Normalized query from the request. |
| `page` required | number | required | Current 1-based page number. |
| `organic` optional | OrganicResult[] | When organic results are parsed. | Organic search results. |
| `featured_snippet` optional | FeaturedSnippet | When Google shows a featured snippet. | Featured snippet answer card, returned separately from organic results. |
| `top_stories` optional | TopStory[] | When the SERP contains top stories. | News cards from Top stories, News and Also in the news: title, link, source, time and thumbnail_url. |
| `people_also_ask` optional | PAA[] | When People Also Ask is present. | Question, answer, and source links. |
| `knowledge_graph` optional | KnowledgeGraph | When a knowledge panel is parsed. | Entity panel data. |
| `related_searches` optional | string[] | When related search suggestions are found. | Related search queries. |
| `ai_overview` optional | { summary, truncated?, sources[] } | When Google shows an AI Overview on the page. | The AI Overview text (sections and bullets kept as lines) and its cited sources: title (the site name), link, and page_title and snippet when the page shows the source card. truncated is true when Google put only the start of a long answer on the page. |
| `local_results` optional | LocalResult[] | When the page shows a Places pack. | Local places with title, rating, reviews_count, category, address and hours. |
| `inline_videos` optional | InlineVideo[] | When the page shows a Videos module. | Video cards with title, link, source (site), channel, duration, date and thumbnail_url. |
| `short_videos` optional | InlineVideo[] | When the page shows a Short videos carousel. | Short-form clips in the same shape as inline_videos. |
| `discussions` optional | Discussion[] | When the page shows Discussions and forums. | Forum threads with title, link, source (e.g. Reddit), forum, comments and date. |
| `recipes` optional | Recipe[] | When the page shows recipe cards. | Recipe cards with title, link, source, rating, reviews_count, total_time and ingredients. |
| `inline_images` optional | InlineImage[] | When the page shows an image strip (for example beside a knowledge panel). | Images with title, link to the hosting page, source credit and thumbnail_url: the full-size image on its site when the page names it, else Google's https thumbnail, else an inline data: image. |
| `weather` optional | { location, temperature, condition, precipitation, humidity, wind, source? } | When the page shows a weather card. | The current weather as displayed: location, temperature (with its unit on desktop), condition, precipitation, humidity and wind. |
| `finance` optional | { title, exchange, price, change, after_hours_price?, open?, day_range?, year_range?, market_cap?, pe_ratio?, previous_close?, as_of? } | When the page shows a stock card. | The stock quote as displayed, e.g. price "210.96 USD" and change "−1.25 (−0.59%)", with the after-hours line and the key facts table. |
| `social_posts` optional | SocialPost[] | When the page shows What people are saying. | Posts from social sites and forums (up to 10): title (the post text), link, source (e.g. X, Reddit), author, author_description, engagement (e.g. "370+ likes"), date, duration and thumbnail_url. |
| `latest_posts` optional | SocialPost[] | When the page shows Latest posts (brand or person queries). | The entity's own recent posts (up to 8), in the same shape as social_posts. |
| `social_profiles` optional | SocialProfile[] | When the page shows Profiles. | The entity's social accounts: title (the site), link and followers (e.g. "36M", desktop only). |
| `shopping_results` optional | Product[] | When the page shows product cards (Popular products, More products). | Products with title, product_id (Google's catalog id), price, original_price, merchant, delivery, rating, reviews_count, badge (e.g. "LOW PRICE") and thumbnail_url. Cards open Google's product viewer, so they have no link. |
| `sports_results` optional | { title, ranking, games[] } | When the page shows a sports team or league card. | The team or league and its standing, and games with status, date, start_time (RFC 3339), stage, teams (name and score) and the highlights link. |
| `flight_search` optional | { title, origin, destination, departure_date?, return_date?, options[] } | When the page shows a Search flights card (route queries). | The route and, on mobile, the dates, with the cheapest fare per airline: airline, duration, stops (desktop), price and a Google Flights link. |
| `people_also_search_for` optional | string[] | When the page shows People also search for. | Related entity queries, distinct from related_searches. |

### `OrganicResult` Result item schema

| Field | Type | Availability | Description |
| --- | --- | --- | --- |
| `rank` required | number | required | 1-based place of the item within its own module (the 3rd organic result has rank 3). |
| `position` optional | number (integer) | On every item and module of Google web search except the plain-text lists related_searches and people_also_search_for; elsewhere when available. | Where the item's module sits on the results page: its block number from the top (1 = first). Each organic result is one block and every other module one block, so all items of a module share its number. Use rank for the order within a module. On products that show a single list, position equals rank. |
| `title` required | string | required | Result title. |
| `link` required | string | required | Primary link returned by the parser. |
| `url` optional | string | Present for normalized result links. | Canonical target URL, usually the same value as link. |
| `source_url` optional | string | Only when Google redirect/source URL is observed. | Original Google URL kept for debugging and provenance. |
| `display_url` optional | string | When Google display text or a domain can be derived. | Display URL or source domain. |
| `display_link` optional | string | When Google display text is present. | Raw Google display link text. |
| `snippet` optional | string | When a snippet is parsed. | Organic result summary. |
| `date` optional | string | When Google includes a date in the snippet. | Raw date text extracted from snippet. |
| `published_at` optional | string | Alias for parsed date when available. | Normalized date alias. |
| `icon` optional | string | When a favicon/image is exposed. | Result icon URL. |
| `sitelinks` optional | { title, link, url, source_url?, display_url? }[] | When sitelinks are present. | Nested sitelinks for the organic result. |

## If it fails

A failed request has a non-zero status and an error, and is not charged. The ones you will see here:

`1000`A parameter is missing or wrongFix the request
`1020`No credits leftTop up
`1029`Over your requests per secondWait Retry-After seconds
`1502 · 1504`The source could not be read this timeRetry

[All status codes →](https://serpbase.dev/docs/responses-and-errors)

## Related

[Google Images Search1 credit](https://serpbase.dev/docs/google_images_search) [Google News Search1 credit](https://serpbase.dev/docs/google_news_search) [Google Videos Search1 credit](https://serpbase.dev/docs/google_videos_search) [Google Search Autocomplete1 credit](https://serpbase.dev/docs/google_autocomplete)