Blog / API guides

Google Search API: Get Search Results as JSON

10 Aug 2026Perceptlayer7 min read

One GET request to /v1/google-search/search with a query returns Google search results as JSON: organic results with position, title, link and snippet, plus related searches. It costs 1 credit per successful call, and failed calls cost nothing. This matters now because Google's own Custom Search JSON API is closed to new customers.

Why does the Custom Search JSON API no longer work for new projects?

Google's documentation states that "the Custom Search JSON API is closed to new customers" and that existing customers have until January 1, 2027 to transition to an alternative. The page points to Vertex AI Search for searching up to 50 domains. If you need results from the open web as JSON, you need a different source.

That is a real constraint if you were planning to start on it today. A new project can't get a key, and an old one has a deadline. Google's page also lists the pricing that still applies to current users: 100 queries a day free, then $5 per 1,000 queries, up to 10,000 queries a day.

Vertex AI Search is the better fit if your goal is search over a fixed set of your own sites. It is a different product from "give me the results page for this query as JSON". For that job, the rest of this article shows the replacement request.

How do you get Google search results as JSON?

Send a GET request to https://api.perceptlayer.com/v1/google-search/search with your query and your key in the X-API-Key header. The response is JSON with named fields, not a page of HTML. If you don't have a key yet, get a free API key; the authentication docs cover the header and the api_key query parameter alternative.

curl "https://api.perceptlayer.com/v1/google-search/search?query=best+restaurants+in+Berlin&hl=en&safe=off" \
  -H "X-API-Key: $API_KEY"

hl sets the interface language and safe=off turns off safe search. Both are optional. Only query is required.

You can also run the same call from the playground on the Google Search API page: pick the endpoint, fill in the parameters and run it with your key.

What does the response look like?

The recorded response for the request above starts with search_information, followed by an organic_results array. Each entry carries the fields below, taken from the recorded output. The excerpt is trimmed with ….

{
  "search_information": {
    "query_displayed": "best restaurants in Berlin",
    "organic_results_count": 6
  },
  "organic_results": [
    {
      "position": 1,
      "title": "The Best Restaurants in Berlin - Food Guide & Map",
      "link": "https://andershusa.com/best-restaurants-berlin-germany-guide/",
      "displayed_link": "https://andershusa.com › best-restaurants-berlin-german...",
      "snippet": "Dec 3, 2025 — Tim Raue is the most internationally renowned restaurant in Berlin. It holds two Michelin stars, has been frequently ranked on The World's 50 ...",
      "snippet_highlighted_words": [
        "Tim Raue is the most internationally renowned restaurant in Berlin"
      ],
      "source": "Anders & Kaitlin",
      "rank_group": 1,
      "rank_absolute": 4
    },
    …
  ],
  "related_searches": [
    {
      "query": "Best restaurants in Berlin for tourists",
      "link": "https://www.google.com/search?safe=off&gl=us&hl=en&complete=0&pws=0&nfpr=1&q=Best+restaurants+in+Berlin+for+tourists"
    },
    …
  ],
  "people_also_search_for": [
    {
      "name": "Best restaurants in Berlin for tourists",
      "query": "Best restaurants in Berlin for tourists",
      "link": "https://www.google.com/search?safe=off&gl=us&hl=en&complete=0&pws=0&nfpr=1&q=Best+restaurants+in+Berlin+for+tourists"
    },
    …
  ],
  …
}

The recorded response also includes a redirect_link on each organic result, which we cut from the excerpt for length.

Note the difference between position and rank_absolute. In the recording, the first organic result has position 1 and rank_absolute 4, so the two fields measure different things. If you track rankings, store both.

Which parameters does the search endpoint take?

GET /v1/google-search/search takes one required parameter, query, and a long list of optional ones for location, language, filters and paging. The ones most readers need are in the table below. Allowed values come from the endpoint's parameter list; no defaults or page sizes are documented, so don't assume any.

The full list also has uule, cr, lr, tbs, as_qdr, kgmid, filter, nfpr, udm and several other Google-specific parameters. The Search endpoint page lists every one with its limits. If you're paging through results, the pagination guide shows a safe loop pattern.

What are the other six Google Search endpoints for?

The Google Search API has 7 endpoints, and each costs 1 credit per call. Pick by the job: the standard and advanced search endpoints return the results page, one endpoint returns the AI Overview, another returns AI Mode answers, one returns place details, and two lighter endpoints cover search and autocomplete.

Two details trip people up. AI Mode uses q, not query. And search-advanced-place has no required parameter; you pass a detail_url or svid instead.

If you're migrating from Custom Search, look at search-light first. Its parameters (num, start, dateRestrict, sort, rights, cr, lr, safe, filter) use names that will look familiar. We haven't recorded a response for it, so check the output in the playground before you map fields. Treat it as a candidate, not a drop-in swap.

How much does a call cost compared with Custom Search?

A successful call costs 1 credit, so 1,000 calls cost 1,000 credits. Credits come in prepaid packs from 10,000 credits (Starter) up to 5,000,000 (Volume), and the pricing page shows what each pack costs. Google's Custom Search charges $5 per 1,000 queries after 100 free queries a day, capped at 10,000 queries a day.

The arithmetic for 10,000 queries: 10,000 calls × 1 credit = 10,000 credits, which equals the Starter pack's 10,000. The free tier's 1,000 credits a month cover 1,000 of those calls. Custom Search at $5 per 1,000 would be $50 for the same volume, ignoring its free daily queries.

Failed calls cost nothing and return X-Credits-Used: 0. Successful responses carry X-Credits-Used and X-Credits-Remaining, so you can track the balance in code. Purchased credits last 12 months, and there's no subscription. The credits docs explain how calls are counted.

One trade-off to be plain about: Custom Search is Google's own service. If you already have access and it fits, staying until the January 1, 2027 deadline is reasonable. For anything new, it's no longer an option.

What happens when a call fails?

Errors return an HTTP status and a JSON body shaped like {"error": {"code", "message", "request_id"}}. Common codes are invalid_api_key (401), insufficient_credits (402), invalid_parameters (422), rate_limited (429) and temporarily_unavailable (503). The errors docs list them all.

Rate-limited and temporarily unavailable responses include a Retry-After header with the seconds to wait. There's no idempotency key, so a request that timed out on your side may have succeeded and been billed. The guide to retrying without paying twice covers how to handle that, and the rate limit docs have the rest.

If you're feeding results to an agent, the same key works over MCP. See Claude MCP web search and the MCP docs.

Next step: get a free API key, then run the Berlin request above and compare organic_results with what you get today.

google searchserpsearch apijsoncustom search