{"slug": "google-s-custom-search-api-shuts-down-jan-1-migrate-by-changing-one-url", "title": "Google's Custom Search API shuts down Jan 1. Migrate by changing one URL.", "summary": "A developer built cse-compat, an open-source Cloudflare Worker that preserves the Google Custom Search JSON API contract ahead of the API's January 1, 2027 shutdown. The tool serves the same /customsearch/v1 endpoint, parameters, response fields and error format while proxying queries to providers like Serper or Brave using the user's own API key, so existing clients only need to change the host and key. It is released under Apache-2.0 and runs on Cloudflare's free plan.", "body_md": "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.\n\nI 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.\n\nThe 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.\n\nGoogle's suggested replacements aren't the same product:\n\nSo if you were using it for general web search, there's no official drop-in path.\n\n**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.\n\n**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.\n\n**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.\n\nI went with option 3.\n\nIf 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:\n\n`items` is missing entirely when there are no results.`if \"items\" in res`.` htmlSnippet` and `htmlTitle``<b>` 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\nGetting these right is most of the work.\n\n[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.\n\nYou can try the public demo without signing up:\n\n```\ncurl \"https://csecompat.com/customsearch/v1?key=demo&cx=test&q=hello\"\n```\n\n(The demo has a daily cap, so for real use you deploy your own copy.)\n\n```\ngit clone https://github.com/csecompat/cse-compat.git && cd cse-compat\nnpm install\nnpx wrangler secret put SERPER_API_KEY\nnpx wrangler secret put PROXY_KEYS\nnpx wrangler deploy\n```\n\n`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.\n\nOnly the host and the key change:\n\n```\n- https://www.googleapis.com/customsearch/v1?key=GOOGLE_KEY&cx=YOUR_CX&q=best+pizza\n+ https://cse.yourdomain.workers.dev/customsearch/v1?key=YOUR_PROXY_KEY&cx=YOUR_CX&q=best+pizza\n```\n\nThe official client has Google's host built in, but it lets you override it:\n\n``` python\nfrom googleapiclient.discovery import build\n\nservice = build(\n    \"customsearch\", \"v1\",\n    developerKey=CSE_COMPAT_KEY,\n    client_options={\"api_endpoint\": \"https://cse.yourdomain.workers.dev\"},\n    static_discovery=True,\n)\n\n# Everything below is unchanged\nres = service.cse().list(q=\"lectures\", cx=CX, num=10).execute()\nfor item in res.get(\"items\", []):\n    print(item[\"title\"], item[\"link\"])\n```\n\n`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/).\n\n``` js\nconst { google } = require('googleapis');\n\nconst customsearch = google.customsearch({\n  version: 'v1',\n  rootUrl: 'https://cse.yourdomain.workers.dev',\n});\n\nconst res = await customsearch.cse.list({ auth: API_KEY, cx: CX, q: 'lectures' });\n// res.data.items works as before\n```\n\nGo's client has `option.WithEndpoint(...)` for the same thing, and Java has `setRootUrl`.\n\n|  | Google CSE | cse-compat | \n|---|---|---|\n| Request and response format | original | same | \n| Error format | original | same | \n| Ranking | Google's index | your provider's | \n| Image search ( `searchType=image` ) | yes | not yet (returns a clear error) | \n| `pagemap` data | yes | not yet | \n| CSE console features (promotions, refinements) | yes | no | \n\nA few more things worth knowing:\n\nIf 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.\n\nThe repo has a script that captures a set of real responses and removes your key from them:\n\n```\nGOOGLE_API_KEY=... GOOGLE_CX=... node scripts/capture-fixtures.mjs\n```\n\nA second script then compares any deployment against those captures, checking field by field that the shape matches:\n\n```\nnode scripts/diff-golden.mjs https://cse.yourdomain.workers.dev YOUR_PROXY_KEY\n```\n\nIf you'd like to contribute captured fixtures to the repo, I'd really appreciate it.\n\nIf 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.\n\nThe 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.", "url": "https://wpnews.pro/news/google-s-custom-search-api-shuts-down-jan-1-migrate-by-changing-one-url", "canonical_source": "https://dev.to/ege_ouz_7f1f546f0d73fc19/googles-custom-search-api-shuts-down-jan-1-migrate-by-changing-one-url-59c4", "published_at": "2026-09-29 18:06:51+00:00", "updated_at": "2026-09-29 18:16:49.962130+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Google", "cse-compat", "Cloudflare", "Serper", "Brave", "Vertex AI Search", "Exa", "Tavily"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/google-s-custom-search-api-shuts-down-jan-1-migrate-by-changing-one-url", "markdown": "https://wpnews.pro/news/google-s-custom-search-api-shuts-down-jan-1-migrate-by-changing-one-url.md", "text": "https://wpnews.pro/news/google-s-custom-search-api-shuts-down-jan-1-migrate-by-changing-one-url.txt", "jsonld": "https://wpnews.pro/news/google-s-custom-search-api-shuts-down-jan-1-migrate-by-changing-one-url.jsonld"}}