> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go-fetch.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Google search results

> First-page organic Google results for each query. scraper_type google_serp.

`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

```python Python theme={null}
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"]])
```

```bash cURL theme={null}
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](https://docs.go-fetch.io/billing.md#cap-a-job-with-maxtotalchargeusd). |

> [!NOTE]
>
> `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:

```json theme={null}
[
  {
    "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`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.