Client API migration

Migrate basic Google CSE searches before 2027

Keep supported cse().list() calls and items parsing. Change the endpoint and key for first-page web search, with explicit limits on cx, pagination and image search.

google-api-python-client — python diff
 from googleapiclient.discovery import build
 
 service = build('customsearch', 'v1',
-    developerKey='YOUR_GOOGLE_KEY',
+    developerKey='YOUR_SEARCH1API_KEY',
+    client_options={'api_endpoint': 'https://api.search1api.com/compat/google/'},
 )
 response = service.cse().list(q='hono workers', cx='YOUR_OLD_CX', num=5).execute()

When to make the switch

Google has closed the Custom Search JSON API to new customers and requires existing customers to transition by January 1, 2027. Search1API provides a first-page web-search compatibility endpoint backed by its Google engine, without calling the retiring CSE API.

Original service reference: Google Custom Search JSON API notice

What you keep

The supported Google Python client cse().list() call.
items[].title, link and snippet result parsing.
Query-string key authentication with a Search1API key, or a Bearer header.

What to review before switching

Only first-page web search is supported: num is 1–10 and start must be 1. Image search and SafeSearch requests return an error.
cx is an opaque compatibility value. It does not load Google’s saved sites or ranking rules; recreate site restrictions explicitly.
Results can differ. Total-result estimates, pagemap and nextPage are omitted. Review X-Search1API-Ignored for options that were not applied.

Move your existing client

Check whether your application needs pagination, image search or configuration saved behind cx.
Create a Search1API key and change the endpoint. The Python SDK base ends with /compat/google/ including the trailing slash.
Test your queries, explicit site restrictions and error handling before switching traffic.

HTTP · first-page web search — bash
curl --get 'https://api.search1api.com/compat/google/customsearch/v1' \
  --data-urlencode 'q=hono workers' \
  --data-urlencode 'num=5' \
  -H "Authorization: Bearer $SEARCH1API_API_KEY"

Examples match the compatibility reference. Validate your own filters and result handling before switching production traffic.

Client examples:google-api-python-client / HTTP clientsRead the compatibility reference

Search uses your Search1API credits and account rate limit. Reading page content and selecting several engines can add charges; see the protocol reference for details.

View pricing

Migration questions

Does changing cx import my search engine?

No. cx is accepted for supported client calls, but Google’s saved settings are not imported. Use siteSearch for one site, or the native Search API for multiple include_sites and exclude_sites.

Can I keep using the Google Python SDK?

Yes for the documented basic calls. google-api-python-client 2.201.0 was tested locally with an api_endpoint override, result parsing and HttpError handling. Other wrappers may need their own endpoint configuration.

Is the embedded Google Search Element covered?

No. This migration is for the Custom Search JSON API. It does not replace Google’s embedded JavaScript Search Element or its site-search UI.

More migration guides

Search API migrations SearXNG Bing Web Search v7