# Google Search Advanced

Fetch a modern Google SERP and return richer structured modules including organic results, ads, People Also Ask, knowledge panels, local packs, news, videos, images, shopping blocks, answer boxes, related searches, spelling corrections, filters, and pagination when present. gl=us and hl=en are used when omitted. page is 0-based: page=0 is the first page and page=1 is the second; start is the preferred explicit result offset. total_results is Google's estimate when exposed and may be null; organic_results_count is the number of returned organic rows. Scrappa does not impose fixed per-key concurrency or requests-per-minute limits. Transient capacity responses include Retry-After, and failed responses including 503 are never charged. External text is returned as valid UTF-8; malformed byte sequences are replaced with the Unicode replacement character (�), while valid Unicode is preserved. Account balance and recent usage are available from GET /api/account/usage and in the dashboard. Explicit empty SERPs return immediately without provider retries, and tbs and as_qdr date filters use bounded retries. Source links are resolved when Google exposes their destinations; unavailable question source links are omitted. Video cards are returned in inline_videos; YouTube cards include channel, raw views and date text, normalized view_count, and publication_age when Google provides the metadata. AI Overview extraction is best effort: ai_overview is populated only when the module is present in the captured HTML. The endpoint does not wait for asynchronously inserted AI Overviews, make a secondary Google AI Overview request, or expand the module, and no request parameter enables those behaviors. When captured, cited sources are returned in ai_overview.references; null means the module was absent from the captured response, not that Google never displays one for the query. Local-pack-only responses are returned with empty organic_results and remain unbilled; they do not substitute for missing site-filtered results. Responses for a different query and non-definitive responses without usable result modules after retries return an unbilled 503. Local places include an optional website field only for safe external business URLs. When no business website is available, detail_url may contain a sanitized Google /searchviewer link to that place; it is not a business-owned website. search_url contains the sanitized Google SERP URL that produced the response. The serp_results collection preserves the DOM order of supported paid cards, local modules, and organic cards. rank_group is the 1-based position within one type; rank_absolute is the 1-based position across those supported types. A multi-place local module occupies one rank_absolute slot, and every nested local_results.places item inherits that rank so clients can merge local and organic results and sort by rank_absolute.

- **Documentation:** [https://staging.scrappa.co/docs/google-search-api/google_search_advanced](https://staging.scrappa.co/docs/google-search-api/google_search_advanced)
- **API group:** Google Search API
- **Endpoint:** `GET https://scrappa.co/api/search-advanced`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Search query |
| `location` | string | No | Location for results (currently ignored by backend) |
| `uule` | string | No | Encoded location (deprecated; supported) |
| `google_domain` | string | No | Google domain (e.g., google.de) |
| `gl` | string | No | Country code (e.g., us, de, fr; default: us) |
| `cr` | string | No | Restrict results to countries (e.g., countryUS\|countryDE) |
| `hl` | string | No | Interface language code (default: en) |
| `lr` | string | No | Restrict results to language (e.g., lang_en) |
| `device` | string | No | Device used to fetch Google results: desktop (default), tablet, or mobile. |
| `tbs` | string | No | Advanced search filters (dates, patents, etc.) |
| `as_qdr` | string | No | Simple time range filter (e.g., d, w, m, y) |
| `safe` | string | No | Safe search mode (active, off) |
| `nfpr` | integer | No | Exclude auto-corrected results (default: 1). Set 0 to allow auto-correction; results for a different query are rejected. |
| `filter` | integer | No | Enable/disable similar/omitted filters (0 or 1) |
| `tbm` | string | No | Search type (isch, vid, nws, lcl, shop, pts) |
| `start` | integer | No | Result offset for pagination (0-indexed) |
| `page` | integer | No | 0-based page number: 0 is the first page and 1 is the second. Prefer start for new integrations. |
| `amount` | integer | No | Results per page (1-10, may return fewer) |
| `lsig` | string | No | Google local listing signature, used with ludocid to target one listing. |
| `kgmid` | string | No | Google Knowledge Graph machine ID of the entity to target (e.g. /m/0dr90d). |
| `si` | string | No | Opaque Google search context token, passed through unchanged. |
| `ibp` | string | No | Opaque Google interface parameter, passed through unchanged. |
| `uds` | string | No | Opaque Google filter token from a previous result page, passed through unchanged. |
| `oq` | string | No | Original Google query value, passed through and encoded once in the upstream URL. |
| `sclient` | string | No | Google search client identifier, passed through and encoded once in the upstream URL. |
| `gs_lp` | string | No | Opaque Google SERP context value, passed through and encoded once in the upstream URL. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/search-advanced?query=best+restaurants+in+Berlin&hl=en&gl=de&device=mobile"
```

## Example response

```json
{
    "search_information": {
        "query_displayed": "best restaurants in Berlin",
        "total_results": 428000000
    },
    "search_url": "https://www.google.de/search?q=best+restaurants+in+Berlin&hl=en&gl=de&complete=0&pws=0&nfpr=1",
    "organic_results": [
        {
            "position": 1,
            "rank_group": 1,
            "rank_absolute": 3,
            "title": "The 38 Best Restaurants in Berlin",
            "link": "https://www.example.com/berlin/best-restaurants",
            "displayed_link": "www.example.com > berlin > best-restaurants",
            "snippet": "A curated guide to Berlin restaurants, from modern German dining rooms to casual neighborhood favorites.",
            "source": "example.com"
        }
    ],
    "related_questions": [
        {
            "question": "What food is Berlin best known for?",
            "snippet": "Berlin is known for currywurst, doner kebab, and a large international restaurant scene.",
            "link": "https://www.example.com/berlin-food-guide"
        }
    ],
    "people_also_search_for": [],
    "things_to_know": [],
    "knowledge_graph": null,
    "see_results_about": null,
    "twitter_card": null,
    "local_results": {
        "places": [
            {
                "position": 1,
                "rank_absolute": 2,
                "title": "Example Berlin Bistro",
                "rating": 4.7,
                "reviews": 1842,
                "type": "Restaurant",
                "address": "Mitte, Berlin",
                "website": "https://www.example-bistro.de/"
            }
        ],
        "modules": [
            {
                "title": "Places",
                "place_indexes": [
                    0
                ],
                "rank_group": 1,
                "rank_absolute": 2
            }
        ]
    },
    "local_map": null,
    "answer_box": null,
    "ai_overview": null,
    "ads": [
        {
            "position": 1,
            "rank_group": 1,
            "rank_absolute": 1,
            "title": "Reserve a Berlin restaurant",
            "link": "https://ads.example.com/berlin-restaurants",
            "displayed_link": "ads.example.com",
            "snippet": "Find and reserve a table in Berlin."
        }
    ],
    "top_stories": [],
    "videos": [],
    "inline_videos": [
        {
            "position": 1,
            "title": "Adobe Express Brand Kit Tutorial 2026",
            "link": "https://www.youtube.com/watch?v=example123",
            "platform": "YouTube",
            "channel": "XayLi Barclay",
            "views": "720+ views",
            "view_count": 720,
            "date": "4 months ago",
            "publication_age": "4 months ago"
        }
    ],
    "inline_images": [],
    "shopping_results": [],
    "popular_products": [],
    "perspectives": [],
    "events_results": [],
    "recipes_results": [],
    "immersive_products": [],
    "filters": [],
    "related_searches": [],
    "refine_this_search": [],
    "nutrition_information": null,
    "pagination": [],
    "serp_results": [
        {
            "type": "paid",
            "result_index": 0,
            "rank_group": 1,
            "rank_absolute": 1
        },
        {
            "type": "local_results",
            "module_index": 0,
            "rank_group": 1,
            "rank_absolute": 2
        },
        {
            "type": "organic",
            "result_index": 0,
            "rank_group": 1,
            "rank_absolute": 3
        }
    ],
    "organic_results_count": 1,
    "total_results": 428000000,
    "engine_used": "google",
    "service_used": "google"
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | One or more query parameters failed validation. |
| 503 | The upstream service is temporarily unavailable. Please retry shortly. | The upstream service is temporarily unavailable. Please retry shortly. |

## More Scrappa resources

- [API documentation](https://staging.scrappa.co/docs)
- [Full LLM-readable API reference](https://staging.scrappa.co/llms-full.txt)
- [OpenAPI specification](https://staging.scrappa.co/docs/api.json)
- [Pricing](https://staging.scrappa.co/pricing)