Google Search API

When you need Google's results for a search term as data, the useful format is the ranked list itself: each result's position, title, address and snippet, ready for code, a spreadsheet or an AI agent. The Google Search API returns exactly that from one request, up to 100 results at a time, together with the answer box, knowledge graph, 'People also ask' questions and related searches whenever Google shows them.

Use cases for the Google Search API:

• Rank tracking: see where your pages and your competitors' pages appear for the terms you care about
• Lead and source lists: collect the sites Google returns for a niche, then scrape each one
• Research and monitoring: follow what Google shows for a topic in a given country or over the past day, week or month
• AI agents and RAG pipelines: give a model fresh, ranked sources before it reads them

Prefer no code?

The same search is available in the dashboard as the 'Google search results' ready-made recipe, which saves the results as rows you can schedule and export. See Ready-made recipes.

How it works

You send a search term, and Simplescraper asks Google for as many pages of results as your limit needs, ten results per page. The results come back in one response, numbered 1, 2, 3 in the order Google ranked them, with a result that Google repeats on a later page kept only once.

Each page of ten results costs 2 credits, and a page that fails is not charged.

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer your_api_key

Your API key is available on your Account Page and on the API tab of each recipe. See the main API authentication docs for details.

Endpoints

Full endpoint

https://api.simplescraper.io/v1/search

Method	Usage
POST /v1/search	JSON body. Recommended, because it needs no URL encoding
GET /v1/search	Query string parameters. Useful for quick tests in a browser or a simple integration

Both methods accept the same parameters and return the same response.

Request parameters

Parameter	Required	Type	Default	Description
query	Yes	String	-	The search term, 1 to 400 characters. On GET you can also send it as q
country	No	String	us	The two-letter country code Google searches from, such as us, gb or de
language	No	String	Google's choice for the country	The two-letter language code of Google's interface, optionally with a region: en, fr, pt-br
limit	No	Number	10	How many results to return, a whole number from 1 to 100
date_range	No	String	any	Only results from this period: any, past_hour, past_day, past_week, past_month or past_year
include	No	Array of strings	All four	Which extras to return beside the results: answer_box, knowledge_graph, people_also_ask, related_searches. On GET, a comma-separated list. Send an empty array, or an empty string on GET, for results only

A parameter the API does not recognize is refused with a 400 error that names it, so a typo such as limt never goes unnoticed.

POST /v1/search

async function searchGoogle(apikey, query) {

  const url = 'https://api.simplescraper.io/v1/search';

  const requestBody = {
    query: query,
    country: 'us',
    limit: 20,
    date_range: 'past_month'
  };

  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apikey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(requestBody)
    });
    const result = await response.json();
    console.log(result.data); // the organic results, ranked
  } catch (error) {
    console.error('error:', error);
  }
}

searchGoogle('YOUR_API_KEY', 'web monitoring');

GET /v1/search

curl "https://api.simplescraper.io/v1/search?q=web%20monitoring&country=gb&limit=10&include=answer_box,related_searches" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "Xk2pQ0aLmN8rT4vW1yZb",
  "query": "web monitoring",
  "status": "completed",
  "date_searched": "2026-10-14T12:00:00.000Z",
  "metadata": {
    "engine": "google",
    "country": "us",
    "language": null,
    "date_range": "past_month",
    "result_count": 20,
    "pages_requested": 2,
    "pages_fetched": 2
  },
  "data": [
    {
      "position": 1,
      "page": 1,
      "title": "What is Web Monitoring?",
      "url": "https://example.com/web-monitoring",
      "snippet": "Web monitoring is the process of checking websites for availability, performance and changes...",
      "date": "3 days ago",
      "sitelinks": [{ "title": "Pricing", "url": "https://example.com/pricing" }]
    }
  ],
  "answer_box": { "title": "...", "answer": "...", "snippet": "...", "url": "https://..." },
  "knowledge_graph": { "title": "...", "type": "...", "description": "...", "website": "https://...", "attributes": {} },
  "people_also_ask": [{ "question": "What is a web monitor?", "snippet": "...", "title": "...", "url": "https://..." }],
  "related_searches": [{ "query": "web monitoring tools" }],
  "errors": []
}

Field	Description
id	A unique id for this search
query	The search term, as searched
status	completed when every page Google was asked for answered, partial when some pages failed (see Partial results)
date_searched	When the search ran, as an ISO 8601 date
metadata	The country, language and date range used, result_count (results in data), pages_requested and pages_fetched
data	The organic results, in Google's order
answer_box, knowledge_graph, people_also_ask, related_searches	Each appears only when you asked for it in include and Google showed one. They come from the first page of results
errors	One entry per page of results that failed; empty when every page answered

Each result in data has these fields:

Field	Description
position	Rank in the returned list, counted from 1 without gaps
page	The Google page the result came from, 1 to 10
title	The result's title
url	The result's address
snippet	The text Google shows under the title, or null when it shows none
date	The date Google shows beside the result. Present only when Google shows one
sitelinks	The sub-links Google shows under the result, each with title and url. Present only when Google shows them

A search Google has no results for is a success: status is completed and data is an empty array.

Partial results

A search over several pages can lose a page to a temporary failure on Google's side. When at least one page answered, you still get the results that arrived, with status: "partial" and one entry in errors for each page that failed:

{
  "status": "partial",
  "metadata": { "result_count": 10, "pages_requested": 2, "pages_fetched": 1 },
  "errors": [
    { "page": 2, "page_message": "search-page-failed", "response_code": 500 }
  ]
}

Only the pages that answered are charged. To fill the gap, send the same search again.

Credits

Each page of up to ten results costs 2 credits, taken from your account's credits:

• limit 10 or less is one page and costs 2 credits.
• limit 20 is two pages and costs 4 credits; limit 15 also needs two pages and costs 4.
• limit 100 is ten pages and costs 20 credits.

Before Google is asked, the API checks that your credits cover every page the search needs. If they do not, the search is refused with a 402 error and nothing is charged. After the search, you are charged only for the pages that returned results: a page that failed costs nothing, and when the first page has no results, no further page is fetched or charged.

Error responses

Errors return a JSON body with a type and a message, for example:

{ "error": { "type": "invalid-value", "message": "Invalid value provided.", "field": "limit" } }

Status code	Error	When it happens
400	invalid-value	A parameter is missing, out of range or not recognized. field names the parameter
402	out-of-credits	Your credits cannot cover the pages the search needs
403	api-key-not-included	The request carries no API key
404	user-not-found	The API key does not belong to an account
408	search-timeout	Google did not answer in time. Try again
500	search-failed	Google could not be searched. When the search service answered with an error, response_code carries its status. Try again
500	search-not-configured	Search is temporarily unavailable on our side. Try again later or reach out via chat

A search that fails with any of these errors is not charged.

Use it from an AI assistant

The Simplescraper MCP server offers the same search as the google_search tool, with query, country, language, date_range and a limit from 1 to 20. Ask your assistant something like "Search Google for the top project management tools and summarize the first ten results", and it can then read any result page with the extract_markdown tool.

FAQ

How fast is a search?

A search for 10 results typically answers in about two seconds, and 20 results in about two and a half. Larger searches fetch their later pages in parallel, so they take only a little longer.

Can I get more than 100 results?

One request returns up to 100 results, which is Google's first ten pages. There is no paging beyond that.

Can I choose the country and language?

Yes. country sets the Google market the search runs in, and language sets the interface language. Without language, Google uses its default for the country.

Does a search show up in my usage?

Yes. Each API search appears on the usage page under 'API', with the credits it cost.

Related

• Ready-made recipes - the 'Google search results' recipe runs the same search from the dashboard, on a schedule if you like
• Extracting websites to Markdown - read the pages a search returns
• MCP server - search Google from Claude, ChatGPT or Cursor

For questions or help, reach out via chat.