Google's Custom Search API shuts down Jan 1. Migrate by changing one URL.

Ege — Tue, 29 Sep 2026 18:06:51 +0000

If you have code that calls https://www.googleapis.com/customsearch/v1, it stops working on January 1, 2027. Google has already closed the API to new customers, and existing ones are being moved off it.

I went through this myself and ended up building a small open-source tool for it. This post covers what's changing, what your options are, and the approach I went with, including where it falls short.

What's actually shutting down

The Custom Search JSON API is the one where you send key, cx and q, and get back JSON with an items array. For years it was the easy way to put web search into a script, an internal tool, or more recently an AI agent: 100 free queries a day, then $5 per 1,000.

Google's suggested replacements aren't the same product:

Vertex AI Search is built for searching your own content, or a limited set of sites (up to 50 domains). It isn't a general web search API.
For full web search, Google points you to a partner-only offering with no public pricing, where you have to contact them.

So if you were using it for general web search, there's no official drop-in path.

Your three options

1. Rewrite for a new search API. Brave, Serper, Exa, Tavily and others all have good APIs. But each one returns a different JSON shape, so you rewrite your parsing, pagination and error handling. That's fine for one small script, and painful if the call is spread across several services or buried inside a library you don't own.

2. Switch to Vertex AI Search. Makes sense if you were only ever searching your own sites. It's a different API, though, so it's still a rewrite.

3. Keep the old API shape and swap what's behind it. Put a thin layer in front of a new provider that speaks the old format exactly. Your code keeps calling the same endpoint shape, you change the base URL, and that's it.

I went with option 3.

The parts of the old API people underestimate

If you try to build a compatibility layer yourself, "return some JSON with items" isn't enough. Code that has run against this API for years quietly depends on details like:

items is missing entirely when there are no results. It isn't an empty list. Plenty of code does if "items" in res.
htmlSnippet and htmlTitle carry <b> tags around matched words, and some UIs render them directly.
queries.nextPage is how most pagination loops know when to stop.
The 100-result window. start + num can't go past 100, and num is 1 to 10. Google returns a specific 400 error if you exceed these.
The error format. Retry logic often checks for 429 with RESOURCE_EXHAUSTED. A new provider returning 402 Payment Required hits a code path your client has never seen.
totalResults is a string, not a number.

Getting these right is most of the work.

What I built: cse-compat

cse-compat is a small Cloudflare Worker that serves /customsearch/v1 with the old contract: same parameters, same response fields, same error format. Behind it, it calls a search provider using your own API key (Serper today, with a Brave adapter included). It's open source under Apache-2.0 and runs fine on Cloudflare's free plan.

You can try the public demo without signing up:

curl "https://csecompat.com/customsearch/v1?key=demo&cx=test&q=hello"

(The demo has a daily cap, so for real use you deploy your own copy.)

Deploying your own

git clone https://github.com/csecompat/cse-compat.git && cd cse-compat
npm install
npx wrangler secret put SERPER_API_KEY
npx wrangler secret put PROXY_KEYS
npx wrangler deploy

SERPER_API_KEY is your key from serper.dev. PROXY_KEYS is a key you make up, which your apps send as ?key= instead of the old Google key.

Changing your code

Plain HTTP

Only the host and the key change:

- https://www.googleapis.com/customsearch/v1?key=GOOGLE_KEY&cx=YOUR_CX&q=best+pizza
+ https://cse.yourdomain.workers.dev/customsearch/v1?key=YOUR_PROXY_KEY&cx=YOUR_CX&q=best+pizza

Python (google-api-python-client)

The official client has Google's host built in, but it lets you override it:

from googleapiclient.discovery import build

service = build(
    "customsearch", "v1",
    developerKey=CSE_COMPAT_KEY,
    client_options={"api_endpoint": "https://cse.yourdomain.workers.dev"},
    static_discovery=True,
)

# Everything below is unchanged
res = service.cse().list(q="lectures", cx=CX, num=10).execute()
for item in res.get("items", []):
    print(item["title"], item["link"])

static_discovery=True makes the client use its built-in API description instead of fetching it from Google, so nothing depends on Google's servers after the shutdown. There's a longer guide here.

Node (googleapis)

const { google } = require('googleapis');

const customsearch = google.customsearch({
  version: 'v1',
  rootUrl: 'https://cse.yourdomain.workers.dev',
});

const res = await customsearch.cse.list({ auth: API_KEY, cx: CX, q: 'lectures' });
// res.data.items works as before

Go's client has option.WithEndpoint(...) for the same thing, and Java has setRootUrl.

What's different (being honest)

	Google CSE	cse-compat
Request and response format	original	same
Error format	original	same
Ranking	Google's index	your provider's
Image search (`searchType=image`)	yes	not yet (returns a clear error)
`pagemap` data	yes	not yet
CSE console features (promotions, refinements)	yes	no

A few more things worth knowing:

Results come from your provider. Serper is a SERP API, so its results are Google-derived. Brave has its own independent index. Same shape either way, but the results won't match Google exactly.
Serper's free plan rejects some exact-match queries that include a quoted domain. cse-compat returns those as a normal 400 error instead of crashing.
totalResults is a lower bound, not a made-up big number, so pagination loops don't run forever.

One thing to do before January 1, whatever you choose

If you still have a working CSE key, save some real responses now. After January 1 nobody can generate new ones, and they're the best way to check that any replacement, mine or not, behaves like the original.

The repo has a script that captures a set of real responses and removes your key from them:

GOOGLE_API_KEY=... GOOGLE_CX=... node scripts/capture-fixtures.mjs

A second script then compares any deployment against those captures, checking field by field that the shape matches:

node scripts/diff-golden.mjs https://cse.yourdomain.workers.dev YOUR_PROXY_KEY

If you'd like to contribute captured fixtures to the repo, I'd really appreciate it.

Wrapping up

If your code is one small script, rewriting it for a new provider is probably simplest. If the Custom Search call is spread across services, or inside libraries you don't control, keeping the API shape and swapping what's behind it can save a lot of work.

The repo is github.com/csecompat/cse-compat. Issues and PRs are welcome, and I'd love to hear what you use the Custom Search API for. I'm also considering a hosted version for teams that don't want to run their own worker. There's a waitlist on csecompat.com if that's you.

DEV Community: Ege