Google is retiring Custom Search.
Your code doesn't have to know.

cse-compat is an open-source Cloudflare Worker serving the same endpoint, parameters, response schema, and error envelope as the retiring Custom Search JSON API — backed by your own key from a modern search provider.

Run it live ↓ View source

config/search.envthe entire migration

  SEARCH_CX=017576662512468239146:omuauf_lfve- SEARCH_BASE=https://www.googleapis.com/customsearch/v1+ SEARCH_BASE=https://csecompat.com/customsearch/v1  # items[].link, items[].snippet, queries.nextPage — unchanged

2 lines changed · 0 parsers rewritten · an afternoon, not a sprint

Show, don't tell

Run a real request right now

A live query against this very endpoint with the public demo key — watch Google's exact legacy schema come back.

GET /customsearch/v1live endpoint

What drop-in means here

The legacy contract, kept honest

Not "similar JSON" — the same envelope your parser was written against, pinned by a public conformance suite.

Byte-exact response schema

items[], htmlSnippet highlighting, queries.nextPage pagination, honest totalResults — the fields your code already reads, where it already reads them.

{ "kind": "customsearch#search", "items": [{ "title", "link", "snippet", "htmlSnippet", "displayLink" }], "queries": { "request", "nextPage", "previousPage" } }

Failover built in

Per-provider circuit breaker with timeout budgets. Pagination stays on one index, so page 2 never skips or repeats.

request─▶ provider A ✕─▶ provider B ✓─▶ 200 OK

Bring your own key

Your Brave or serper.dev key; you stay their direct customer. No resale, no markup — a translation layer, nothing more.

Google-exact errors

Quota answers the way your client library expects.

429 RESOURCE_EXHAUSTED 400 INVALID_ARGUMENT 402

Stateless by design

Queries are never logged or stored. The worker is a pure pipe.

0 bytes of query data retained

Proven, not promised

A public conformance suite pins the contract — pagination windows, error envelopes, zero-result behavior, the 100-result cap.

37/37 conformance tests passing · read them

Apache-2.0, self-hostable forever

The core is open source. Run it on Cloudflare's free tier and it costs you nothing but your own search-API usage. No lock-in — that's the point of the whole project.

Self-host

Deployed in three steps

Deploy the worker to your Cloudflare account.

git clone github.com/egeoguz04/cse-compat
cd cse-compat
npm i && npx wrangler deploy

Add your upstream key — one provider is enough.

npx wrangler secret put \
  BRAVE_API_KEY
# or SERPER_API_KEY

Change the base URL. That's the migration.

SEARCH_BASE=
https://cse.you.workers.dev
  /customsearch/v1

Managed version

Zero infrastructure on your side

The hosted version adds multi-provider fallback, cx site-restriction profiles, usage analytics, and an SLA — same endpoint, no worker to run. Launching before the shutdown.

Google is retiring Custom Search.Your code doesn't have to know.