Skip to content
Blog

Google Custom Search API Alternative in Python (2026)

Carmine Cella8 min read
Google Custom Search API alternative (2026): migrate before January 1, 2027 with a Python adapter that maps q to query, start to page and organic results to CSE items

Google Custom Search API Alternative in Python (2026)

Short answer: Google's Custom Search JSON API is closed to new customers, and it shuts down in 2027. Google's own page says existing customers have until January 1, 2027 to transition to an alternative solution. If your code needs Google search results as JSON, a SERP API such as the Datafuel Search API can replace it with a thin adapter.

This 2026 guide gives you a parameter map, a tested Python adapter and the results of a live run on 20 search queries.

Site search boxes, SEO scripts and AI agents still call the Google Custom Search API. In 2026 those teams face a fixed date.

Google Custom Search API shutdown: the facts

Here's what Google's Custom Search JSON API overview says today:

  • "The Custom Search JSON API is closed to new customers." You can't start a new project on it.
  • Existing customers have until January 1, 2027 to move to another solution.
  • Pricing until then: 100 free search queries per day, then $5 per 1,000 queries, up to 10,000 a day.
  • Google's suggestions: Vertex AI Search for up to 50 domains. For full web search, Google asks you to contact its team.

Today each call goes to https://www.googleapis.com/customsearch/v1 with an API key and a custom search engine ID (cx) from the Programmable Search Engine control panel. A call returns at most 10 results, and never more than 100 per query.

Timeline of official search API shutdowns: Bing Search APIs retired on August 11, 2025, Custom Search JSON API closed to new customers today, migrate with an adapter before existing customers are cut off on January 1, 2027
Official search API shutdowns and the January 1, 2027 deadline

It isn't the first official search API to close. Microsoft retired the Bing Search APIs on August 11, 2025. Keep a small adapter between your code and any search engine APIs you use, so the next change is a one-file job.

Google search API alternative: two kinds of replacement

A Google search API alternative falls into one of two groups. Both are valid, but they answer different questions.

Google results as JSON (a SERP API).

  • Results and rankings match the google.com page for the country and language you set.
  • You also get People also ask, local results and related searches.
  • It's the best fit for SEO tracking and parity with your old output.

Search APIs with their own index.

  • Results come from the provider's own crawl, so rankings differ from Google.
  • They fit AI grounding, where Google parity doesn't matter.

Test your own queries on both. Vertex AI Search, Google's own route, fits a site search box over up to 50 domains. It isn't a drop-in replacement for web searching across the whole web.

Custom Search JSON API parameters mapped to Search API

The Datafuel Search API returns the Google results page as JSON, with organic results, People also ask and related searches in separate fields. Every name below comes from the Search API page and the developer guide.

  • q becomes query, with the same text.
  • num (1 to 10) has no field. One call returns one results page, so slice the list.
  • start (1, 11, 21) becomes page (1, 2, 3). The formula is (start - 1) // 10 + 1.
  • dateRestrict becomes tbs. For example, w1 turns into qdr:w1.
  • siteSearch and siteSearchFilter become operators in the query: site:example.com or -site:example.com.
  • exactTerms and excludeTerms become "exact phrase" and -word in the query.
  • gl becomes country, and hl becomes language.
  • lr, cr, safe and filter keep their names and go straight to Google.
  • cx has no field. Rebuild a site-restricted engine with site: operators.
  • searchType=image isn't covered. Search API returns web results.
Parameter map from the Custom Search JSON API to the Datafuel Search API: q to query, start to page, dateRestrict to tbs, siteSearch to site operators, gl to country, hl to language
Custom Search JSON API parameters mapped to Search API

The adapter fills title, link, displayLink and snippet for each item, plus totalResults. Fields such as htmlSnippet and pagemap have no direct match.

Custom Search JSON API Python adapter: a drop-in replacement

This adapter keeps the cse_list() arguments for web search. It returns a dictionary in the same shape as a search JSON API response from Google.

It reads the API key from an environment variable, sets timeouts and sends an Idempotency-Key, so a retry never charges twice.

import os
import time
import uuid
from urllib.parse import urlparse

import requests

# --- Settings -------------------------------------------------------------
API_URL = "https://scraping-api.datafuel.ai/api/v1/task"
API_KEY = os.environ["DATAFUEL_API_KEY"]   # never hard-code the key
TIMEOUT = (10, 60)                         # connect, read (seconds)
MAX_RETRIES = 3
DEFAULT_COUNTRY = "us"                     # Google gl
DEFAULT_LANGUAGE = "en"                    # Google hl
RESULTS_PER_PAGE = 10                      # CSE pages are 10 results wide


class SearchError(Exception):
    pass


def _date_restrict_to_tbs(value):
    """CSE dateRestrict d7 / w2 / m6 / y1 -> Google tbs qdr:d7 / qdr:w2 ..."""
    unit, number = value[0], value[1:]
    if unit not in "dwmy" or (number and not number.isdigit()):
        raise ValueError(f"Unsupported dateRestrict: {value}")
    return f"qdr:{unit}{number}"


def _build_query(q, siteSearch=None, siteSearchFilter="i",
                 exactTerms=None, excludeTerms=None):
    parts = [q]
    if exactTerms:
        parts.append(f'"{exactTerms}"')
    if excludeTerms:
        parts.append(f"-{excludeTerms}")
    if siteSearch:
        prefix = "-site:" if siteSearchFilter == "e" else "site:"
        parts.append(prefix + siteSearch)
    return " ".join(parts)


def _post(attributes):
    """One Search API call with retries. Blocked queries fail and cost 0 credits."""
    body = {"type": "serp", "attributes": attributes}
    headers = {"X-API-Key": API_KEY, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(MAX_RETRIES):
        try:
            resp = requests.post(API_URL, headers=headers, json=body, timeout=TIMEOUT)
        except requests.RequestException:
            time.sleep(2 ** attempt)
            continue
        if resp.status_code == 202:            # still processing: poll the task
            task_id = resp.json()["id"]
            for _ in range(30):
                time.sleep(2)
                task = requests.get(f"{API_URL}/{task_id}", headers=headers,
                                    timeout=TIMEOUT).json()
                if task.get("status") in ("completed", "failed"):
                    break
        elif resp.status_code in (429, 503):   # concurrency limit or backend down
            time.sleep(int(resp.headers.get("Retry-After", 1)) + attempt)
            continue
        elif resp.status_code >= 400:          # 400/401/402/403: fix the request
            raise SearchError(f"HTTP {resp.status_code}: {resp.text[:200]}")
        else:
            task = resp.json()
        if task.get("status") == "completed":
            return task
        # failed (blocked or timeout): new key, try again
        headers["Idempotency-Key"] = str(uuid.uuid4())
        time.sleep(2 ** attempt)
    raise SearchError("Search failed after retries")


def cse_list(q, num=10, start=1, dateRestrict=None, siteSearch=None,
             siteSearchFilter="i", gl=None, hl=None, lr=None, cr=None,
             safe=None, exactTerms=None, excludeTerms=None):
    """Same arguments and response shape as customsearch/v1 for web search."""
    page = (start - 1) // RESULTS_PER_PAGE + 1
    offset = (start - 1) % RESULTS_PER_PAGE
    attributes = {
        "query": _build_query(q, siteSearch, siteSearchFilter, exactTerms, excludeTerms),
        "country": gl or DEFAULT_COUNTRY,
        "language": hl or DEFAULT_LANGUAGE,
        "page": page,
        "result_format": "json",
    }
    if dateRestrict:
        attributes["tbs"] = _date_restrict_to_tbs(dateRestrict)
    for name, value in (("lr", lr), ("cr", cr), ("safe", safe)):
        if value:
            attributes[name] = value

    task = _post(attributes)
    data = task["result"]["data"]
    organic = data.get("organic", [])[offset:offset + num]
    items = [{
        "kind": "customsearch#result",
        "title": row.get("title"),
        "link": row.get("url"),
        "displayLink": urlparse(row.get("url", "")).netloc,
        "snippet": row.get("snippet") or "",   # a few results (often videos) have none
    } for row in organic]
    return {
        "kind": "customsearch#search",
        "searchInformation": {"totalResults": str(data.get("total_results", 0))},
        "items": items,
        "_credits_used": task.get("credits_used"),
    }

Your calling code barely changes:

res = cse_list("python requests timeout", num=5)
for item in res["items"]:
    print(item["title"], "|", item["link"])

Drop the Google API key and cx. If your engine covered a few sites, pass siteSearch, or put site:a.com OR site:b.com in the query.

How the adapter handles a call: build the Search API request, POST with an Idempotency-Key, poll on 202, back off on 429 or 503, stop on 4xx errors, retry failed tasks, then map organic results to CSE items
How the cse_list() adapter handles a call

Live test: 20 queries through the Google search JSON API replacement

Method. On 27 October 2026 at 08:54 UTC we sent 20 neutral queries, such as sql left join example, through the adapter. Each used country: us, language: en and page: 1. We also ran six parameter checks and measured latency from our test machine.

Results:

  • Queries completed: 20 of 20 (100%).
  • Organic items per call: 6 to 9, for 155 in total.
  • Items with title, link and snippet: 144 of 155 (93%).
  • Median latency: 2.5 s wall clock and 2.3 s server time.
  • Slowest call: 13.6 s.
  • Cost: 10 credits on every call.

Parameter checks. All six worked as expected:

  • start=11 reached Google as start=10 and returned 10 page-2 results.
  • dateRestrict="w1" became tbs=qdr:w1 and returned last week's Python releases.
  • siteSearch="docs.python.org" returned 10 of 10 links on that host. The exclude filter removed every stackoverflow.com link.
  • gl="it" and hl="it" returned Italian recipe sites.
  • lr="lang_de" with num=5 returned five German-language pages.

What we learned:

  1. Expect fewer than 10 items on page 1. People also ask and videos take space, so fix code that assumes 10.
  2. Allow for empty snippets. 11 items, mostly videos, had none. The adapter returns an empty string.
  3. Treat totalResults as an estimate. It varied widely.
  4. Set a generous read timeout. A few calls took 8 to 14 seconds.

The full test, including a probe and a final snippet run, used 280 credits.

Moving off the Custom Search JSON API at scale

For larger volumes, send a batch to POST /job with a queries array and multithreaded: true. Then poll the job and download the results. A blocked query returns blocked: true and credits_used: 0.

A safe migration plan:

  1. Wrap every Google APIs search call in one function.
  2. Point it at the adapter behind a feature flag.
  3. Run both for a week on real queries and compare the top links.
  4. Fix code that assumed 10 items, a snippet everywhere or pagemap.
  5. Switch well before January 1, 2027, and delete the old key.

For a broader tutorial, read our guide on how to scrape Google search results with Python.

Frequently asked questions

What does a Google Custom Search API alternative cost per 1,000 searches?

Google charges existing customers $5 per 1,000 queries after 100 free queries a day. Datafuel Search API charges 10 credits per successful search, so 1,000 searches use 10,000 credits. On the Starter plan ($29 a month for 300,000 credits), that's about $0.97 per 1,000 searches at list price. We refund blocked or failed queries. See pricing for every plan.

How many results does each call return?

The custom search API returns up to 10 results per call. Search API returns one Google results page per call. In our test that meant 6 to 9 organic results on page 1, plus People also ask and related searches. Use page to go deeper.

What are the limits?

The Free plan gives 1,000 one-time trial credits, valid for one year, with 2 concurrent threads and no card. Paid plans run 10 to 150 threads. There's no monthly minimum.

Is there a free Google search API?

Not for new projects from Google, since the Custom Search JSON API is closed to new customers. The 1,000 Datafuel trial credits cover 100 searches, enough to test your migration.

Results pages are public, but the rules depend on your country and use case. Store only what you need and avoid personal data. This guide isn't legal advice.

Start the migration this week

The deadline is fixed and the code change is small. Create a free account, set DATAFUEL_API_KEY and compare your top ten queries.

Search APITry it on your own targetsGoogle search results as structured JSON, Markdown or raw HTML, for the country, language and city you choose.
Start freeSee the Search API pagefrom $0.416 per 1k requests · failed requests free
Get started

Ready to build?

Start with the free tier and scale as your project grows. No credit card, no sales call.

Talk to an engineer, not a chatbot.