Google search results

google_serp runs a batch of Google searches and returns the organic results of the first page for each one. One result is one query.

Run it

import os

from gofetch import GoFetchClient

client = GoFetchClient(api_key=os.environ["GOFETCH_API_KEY"])

run = client.actor("google_serp").call(run_input={
    "queries": ["nasa artemis mission", "nobel prize physics"],
    "limit": 10,
})

for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["search_term"], [result["url"] for result in row["results"]])

curl https://go-fetch.io/api/v1/jobs/create/ \
  -H "X-API-Key: $GOFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scraper_type": "google_serp", "config": {"queries": ["nasa artemis mission", "nobel prize physics"]}}'

Inputs

Field	Type	Default	What it does
`queries`	list of text		Search queries, sent as you type them, operators included. `keyword` or `keywords` (a list, or one query per line) are accepted as other names.
`limit`	integer	`10`	Results per query, from 1 to 10. Larger values are lowered to 10: only the first page is read.
`hl`	text	`en`	Language code: `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `ru` or `ja`. Any other value is read as `en`.
`country`	text	`US`	The country to search from, as a two-letter code; `gl` is accepted as another name. The organic results are localised to that country. See the supported codes below.
`maxTotalChargeUsd`	number		A spending cap: the whole job, one result per query, must fit it. See Billing.

hl sets the search language for the 10 codes in the table; any other value searches in English. country takes one of these 51 codes: AR AT AU BE BG BR BY CA CH CL CN CO CZ DE DK EE EG ES FI FR GB GR HK HU ID IE IN IT JP KR MX MY NL NO NZ PE PH PL PT RO RU SE SG TR TW UA US UY VE VN ZA. The United Kingdom is GB, not UK. Any other value is searched as US, reported as US in completeness.country, and named in a warning in the job’s log: “country XX is not supported yet; results are for the US.” Where a country is searched in more than one language, such as CH or BE, the language of hl picks it: country: "CH" with hl: "fr" gets the French-language Swiss results. A query repeated in one job runs, and is billed, each time. A query made only of quoted terms joined by OR (such as "@nasa" OR "nasa") is sent without its quotes, because the quoted form returns nothing; search_term still shows what you sent.

Output

One row per query that got an answer. Rows come back in the order queries finish: match them on search_term. A real row from a test job, shortened here to its first 3 of 10 results:

[
  {
    "search_term": "nasa artemis mission",
    "results": [
      {
        "position": 1,
        "title": "Moon to Mars | NASA's Artemis Program",
        "url": "https://www.nasa.gov/humans-in-space/artemis/",
        "description": "Under Artemis, NASA will send astronauts on increasingly difficult missions to explore more of the Moon for scientific discovery, economic benefits, and to ..."
      },
      {
        "position": 2,
        "title": "Artemis program - Wikipedia",
        "url": "https://en.wikipedia.org/wiki/Artemis_program",
        "description": "The Artemis program is a Moon exploration program led by the United States' National Aeronautics and Space Administration (NASA), aimed at returning humans ..."
      },
      {
        "position": 3,
        "title": "Artemis II Multimedia: Crew Photos, Videos and Mission Highlights",
        "url": "https://www.nasa.gov/artemis-ii-multimedia/",
        "description": "Here, you can view and download mission photographs, behind‑the‑scenes videos, podcasts, and more. The Artemis II mission—NASA's first crewed lunar flyby in ..."
      }
    ]
  }
]

Field	Type	What it holds
`search_term`	text	The query as you sent it.
`results`	list	The organic results, in page order. `[]` means Google said there were no results; that row is still billed.
`results[].position`	integer	Rank, from 1.
`results[].title`	text	The result’s title.
`results[].url`	URL	Where it links, without Google’s tracking parameters.
`results[].description`	text	The snippet; can be `""`.
`results[].date`	text	The date the snippet shows, as display text (`Jan 2, 2021`, `21 hours ago`). Left out when there is none.

A query that failed, or whose page could not be read, returns no row and is not billed.

What logged-out means here

You get: the organic results of page 1 for each query, as a signed-out searcher sees them. Not available: ads, knowledge panels, People Also Ask, related searches, AI overviews, image, news and video results, local results, result counts, later pages and date-range filters.

Completeness

scraper_metadata.completeness:

Key	What it says
`queries_submitted`, `queries_executed`	Queries sent, and rows returned (the billed count).
`queries_empty`	Billed rows with `results: []`.
`queries_empty_unbilled`	Pages that could not be read: no row, not billed.
`queries_failed`	Queries that failed, or that the job ran out of time for: no row, not billed.
`all_queries_failed`	Every query failed; the job then fails.
`degraded`	More than 20% of the pages reached could not be read.
`results_total`, `results_mean`	Organic results returned, in total and per row.
`country`, `hl`, `limit`	The settings the job ran with. `country` is the country searched: `US` when the one you sent isn’t supported.
`queries`	Per query, for the first 250: `search_term`, `status` (`ok`, `empty` or `failed`), `results_count`, `query_rewritten` when it applies, and `reason` on a query that returned no row: `job-time-budget` when the job ran out of time for it, otherwise `failed`. A page that could not be read is `empty` with reason `failed`.

Get started

Concepts

Scrapers

Python SDK

Google search results

Run it

Inputs

Output

What logged-out means here

Completeness

​Run it

​Inputs

​Output

​What logged-out means here

​Completeness

Run it

Inputs

Output

What logged-out means here

Completeness