# Google's Custom Search API shuts down Jan 1. Migrate by changing one URL. > Source: > Published: 2026-09-29 18:06:51+00:00 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. 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: So if you were using it for general web search, there's no official drop-in path. **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. 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.`if "items" in res`.` htmlSnippet` and `htmlTitle``` tags around matched words, and some UIs render them directly.`queries.nextPage`` start` + `num` can't go past 100, and `429` with `RESOURCE_EXHAUSTED`. A new provider returning `402 Payment Required` hits a code path your client has never seen.`totalResults` is a string Getting these right is most of the work. [cse-compat](https://github.com/csecompat/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.) ``` 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. 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 ``` The official client has Google's host built in, but it lets you override it: ``` python 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](https://csecompat.com/guides/google-api-python-client/). ``` js 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`. | | 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: 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. 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](https://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](https://csecompat.com) if that's you.