Google CSE compatibility reference

Google's Custom Search JSON API is closed to new customers, and existing customers must transition by January 1, 2027. See Google's official API notice and Programmable Search Engine announcement.

Search1API provides a compatible endpoint for first-page web search. It uses Search1API's Google engine and returns the items[].title, link and snippet fields that existing CSE clients read. It does not call the retiring Custom Search JSON API.

Replace https://www.googleapis.com/customsearch/v1 with:

https://api.search1api.com/compat/google/customsearch/v1

Send a Search1API key in the key query parameter, replacing the Google API key. Authorization: Bearer YOUR_API_KEY also works. Conflicting credentials return 400. Responses use Cache-Control: no-store, and Search1API masks query-string keys in its application logs.

For the migration overview and configuration changes, see Migrate from Google CSE.

Configure your client

import os
from googleapiclient.discovery import build

with build(
    "customsearch",
    "v1",
    developerKey=os.environ["SEARCH1API_API_KEY"],
    client_options={
        "api_endpoint": "https://api.search1api.com/compat/google/",
    },
) as service:
    response = service.cse().list(
        q="hono cloudflare workers",
        cx="YOUR_OLD_ENGINE_ID",
        num=5,
    ).execute()

    for item in response.get("items", []):
        print(item["title"], item["link"], item["snippet"])

curl --get 'https://api.search1api.com/compat/google/customsearch/v1' \
  --data-urlencode 'q=hono cloudflare workers' \
  --data-urlencode 'num=5' \
  -H "Authorization: Bearer $SEARCH1API_API_KEY"

Clients with a hardcoded Google URL need an endpoint override or a code change. A setting named base_url is not enough if the client discards its path. Framework wrappers that construct their own Google client may need that client configured explicitly; they have not been tested here. Google's embedded Search Element JavaScript and the old /siterestrict endpoint are not covered.

Supported parameters

Other parameters, including hl, gl, cr, sort, exactTerms, excludeTerms, fileType, rights, filter, fields and image filters, are ignored. hl is a UI language and is not treated as a result-language restriction. If your application depends on one of these options, review the difference before migrating.

X-Search1API-Ignored lists ignored option names, never values, as a bounded comma-separated list of percent-encoded names. It reports at most 50 names; a name longer than 120 encoded characters becomes option_name_truncated. Check it when evaluating requests; it includes cx whenever supplied. This header does not mean the old engine configuration was applied.

Response and pagination

Successful responses contain kind: "customsearch#search", queries.request, searchInformation.searchTime in seconds and an items array. Each item contains kind: "customsearch#result", title, link, displayLink (the host name) and snippet.

An empty successful search returns items: []. Search results and rankings can differ from CSE. HTML highlighting, pagemap, promotions, refinements, spelling corrections and search-total estimates are omitted rather than fabricated.

Only the first page is available. queries.nextPage and queries.previousPage are not returned. Pagination loops and applications using searchInformation.totalResults need adjustment; do not assume full CSE compatibility from the basic result format.

Credits and errors

A completed search costs 1 credit, including a confirmed empty search, and shares the native account rate limit. Technical search failures are not charged. No page-content crawling is performed. See Credits and limits.

Errors use Google's envelope: { "error": { "code": 400, "message": "…", "errors": [{ "domain": "global", "reason": "invalid", "message": "…" }] } }. HTTP status codes remain those of Search1API: 400 for invalid or unavailable behavior, 401 for an invalid key, 402 for insufficient credits, 403 for forbidden access and 429 for rate limiting. A 429 preserves the native Retry-After header. Error reasons follow the Google format; 402 is still Search1API's credit-balance status, not a daily Google quota.

Migration checklist

1. Confirm that you use the Custom Search JSON API rather than the embedded Search Element.
2. Recreate any site restrictions previously stored behind cx.
3. Replace the endpoint and key; keep your supported cse().list() calls and items parsing.
4. Remove pagination and image-search calls from this endpoint, and review ignored filters and unavailable metadata.
5. Run representative queries and verify error handling before switching production traffic.