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

Drop-in for raw HTTP google-api-python-client googleapis (Node)

Works with your key from Brave Search serper.dev

Live demo

Run a real request. Right here.

A live query against this endpoint with the public demo key. Google's exact legacy schema comes back.

GET /customsearch/v1live endpoint

The public demo key allows 10 requests a minute per visitor. Testing something bigger? Self-host with your own free-tier key.

Compatibility

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" }], "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, just a translation layer.

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 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, which is the point of the whole project.

Self-host

Deployed in three steps.

Deploy the worker to your Cloudflare account.

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

Add your upstream key. One provider is enough.

npx wrangler secret put SERPER_API_KEY
# or BRAVE_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.