Migrate from Google Custom Search
Google shuts down the Custom Search JSON API on January 1, 2027. SerpKite's GET /customsearch/v1 takes the same parameters and returns the same response shape.
Google is retiring the Custom Search JSON API (https://www.googleapis.com/customsearch/v1) on January 1, 2027. SerpKite ships a compatible endpoint, GET /customsearch/v1, that accepts the same query parameters and returns the same customsearch#search document. Code that reads items[].title, items[].link, searchInformation.totalResults or queries.nextPage keeps working.
The change
- https://www.googleapis.com/customsearch/v1?key=GOOGLE_KEY&cx=ENGINE_ID&q=asyncio
+ https://api.serpkite.com/customsearch/v1?key=skt_live_...&cx=ENGINE_ID&q=asyncio
- Replace the host
www.googleapis.com(orcustomsearch.googleapis.com) withapi.serpkite.com. The path stays/customsearch/v1. - Replace the Google API key with a SerpKite key. You can keep passing it as
key=, or move it to anAuthorization: Bearerheader so it stays out of URLs and logs. - Leave
cxas it is. It is accepted and ignored.
Paste an existing request URL into the CSE migration helper to get the rewritten URL and code.
Parameters
Every parameter of the Custom Search JSON API is accepted. Parameters that shape the query become search operators in Google’s query, as Google’s documentation describes them.
| Parameter | Supported | Notes |
|---|---|---|
q |
Yes | Required. |
key |
Yes | Your SerpKite key. Authorization: Bearer also works. |
cx |
Accepted, ignored | Results come from the whole web, not a Programmable Search Engine. |
start |
Yes | Index of the first result, from 1. start + num - 1 can be at most 100, as in CSE. Any value works, not only 1, 11, 21… |
num |
Yes | 1–10. |
gl |
Yes | Country the search is made from. |
hl |
Yes | Interface language. |
lr |
Yes | Only documents in that language, e.g. lang_de or lang_de|lang_fr. |
cr |
Yes | Only documents from that country, e.g. countryDE. |
safe |
Yes | active or off. The retired high and medium mean active. |
dateRestrict |
Yes | d7, w2, m6, y1…, applied as written. |
sort |
Yes | date (newest first) or date:r:YYYYMMDD:YYYYMMDD (a date range). Other values return 400: Google’s results page has no other order. |
exactTerms, excludeTerms, orTerms, hq |
Yes | Added to q as "phrase", -word, (a OR b) and plain terms. |
fileType |
Yes | Added to q as filetype:. |
lowRange, highRange |
Yes | Added to q as low..high. |
siteSearch, siteSearchFilter |
Yes | site: or, with siteSearchFilter=e, -site:. |
searchType |
Yes | image for image results. |
imgSize, imgType, imgColorType, imgDominantColor, rights |
Yes | Image filters. Google has three sizes (icon, medium, large), so small means medium and xlarge and up mean large. Any cc_* right asks for Creative Commons licences. |
filter, linkSite, c2coff, googlehost |
Accepted, ignored | Google retired the link: operator; its duplicate filter stays on. |
alt, fields, prettyPrint, quotaUser, callback |
Accepted, ignored | The full JSON response is returned. |
/customsearch/v1/siterestrict (the Site Restricted variant) works too, and behaves the same.
If your engine was restricted to certain sites
A Programmable Search Engine could be limited to a list of sites. SerpKite ignores cx, so add the restriction to the request: siteSearch=docs.example.com, or a site: operator in q (site:docs.example.com OR site:blog.example.com asyncio).
Response
The response keeps the CSE shape: kind, searchInformation, items[] (with title, htmlTitle, link, displayLink, snippet, htmlSnippet, formattedUrl, pagemap, image for image search) and queries with request and nextPage.
{
"kind": "customsearch#search",
"searchInformation": {
"searchTime": 0.94,
"formattedSearchTime": "0.94",
"totalResults": "1240000",
"formattedTotalResults": "1,240,000"
},
"items": [
{
"kind": "customsearch#result",
"title": "asyncio — Asynchronous I/O",
"htmlTitle": "<b>asyncio</b> — Asynchronous I/O",
"link": "https://docs.python.org/3/library/asyncio.html",
"displayLink": "docs.python.org",
"snippet": "asyncio is a library to write concurrent code using the async/await syntax."
}
],
"queries": {
"request": [
{
"searchTerms": "site:docs.python.org asyncio",
"count": 10,
"startIndex": 1
}
]
}
}Things to know:
- Errors use Google’s error body, so code that reads Google’s errors keeps working:
error.codeis the HTTP status,error.errors[0].reasonis Google’s reason (badRequest,keyInvalid,quotaExceeded,rateLimitExceeded,backendError) anderror.statusis the canonical status (INVALID_ARGUMENT…). SerpKite’s own code, such asinsufficient_credits, is inerror.details[0].reason, anderror.request_ididentifies the call for support. Running out of credits is a402. See Errors. - No results means no
itemskey, as in CSE, andsearchInformation.totalResultsis"0". - totalResults is Google’s estimate when its page shows one. Google mostly no longer does; then it is
"100"while more results follow (the most the API pages through) and the exact count once they end. - Delayed links. Google sometimes holds back where a result leads. Such an item keeps its place with
"link_resolved": false, itslinkis Google’sgoogle.com/gotoredirect anddisplayLinkis the domain Google showed. Repeating the request may return its destination. - Quota. There is no 100-queries-per-day free cap and no 10,000-per-day ceiling. You pay 1 credit per Google page read from a prepaid balance, and your plan sets a requests-per-second rate limit.
Code
Python with requests
import os
import requests
res = requests.get(
"https://api.serpkite.com/customsearch/v1",
params={"q": "site:docs.python.org asyncio", "cx": "any", "num": 10, "start": 1},
headers={"Authorization": f"Bearer {os.environ['SERPKITE_API_KEY']}"},
timeout=30,
)
res.raise_for_status()
data = res.json()
print(data["searchInformation"]["totalResults"])
for item in data.get("items", []):
print(item["title"], item["link"])
Python with google-api-python-client
If you use Google’s client library, point it at SerpKite with client_options. The library builds URLs from the discovery document’s root, so overriding the endpoint sends requests to https://api.serpkite.com/customsearch/v1:
import os
from googleapiclient.discovery import build
service = build(
"customsearch",
"v1",
developerKey=os.environ["SERPKITE_API_KEY"],
client_options={"api_endpoint": "https://api.serpkite.com/"},
)
data = service.cse().list(q="site:docs.python.org asyncio", cx="any").execute()
for item in data.get("items", []):
print(item["title"], item["link"])
The discovery document itself is still fetched from Google, so this path depends on Google’s discovery service staying up after the shutdown. For a long-lived migration, prefer the plain requests version above.
Node.js
const url = new URL("https://api.serpkite.com/customsearch/v1");
url.search = new URLSearchParams({ q: "site:docs.python.org asyncio", cx: "any", num: "10" });
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.SERPKITE_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const { items = [], searchInformation } = await res.json();
console.log(searchInformation.totalResults, items.map((i) => i.link));
Go
q := url.Values{}
q.Set("q", "site:docs.python.org asyncio")
q.Set("cx", "any")
q.Set("num", "10")
req, _ := http.NewRequest("GET", "https://api.serpkite.com/customsearch/v1?"+q.Encode(), nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SERPKITE_API_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var out struct {
Items []struct {
Title string `json:"title"`
Link string `json:"link"`
} `json:"items"`
}
if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
log.Fatal(err)
}
for _, it := range out.Items {
fmt.Println(it.Title, it.Link)
}
Pagination
As with CSE, page with start and follow queries.nextPage[0].startIndex until it is absent: start=1 is results 1–10, start=11 is 11–20, up to result 100. Result indexes follow Google’s pages of 10, so a call whose start and num stay on one page costs 1 credit, and one that spans two pages (start=5, or num=3 at start=10) reads both and costs 2. A Google page sometimes holds fewer than 10 results; its last indexes are then empty, and nothing is skipped or repeated. If you need the top 100 in one go, the native /v1/search endpoint with num: 100 returns them in one call for 7 credits instead of 10 (see Pagination and depth).
Going further than CSE
Once you’re on SerpKite, the native endpoints give you more than CSE ever returned: People Also Ask, the knowledge graph, the answer box, news, maps and more, plus Markdown output for LLMs. The mapping from CSE is straightforward: items[].link is results[].link, items[].title is results[].title, items[].snippet is results[].snippet, start becomes page, and the CSE gl and hl parameters become country and language. With the official SDKs:
curl https://api.serpkite.com/v1/search \
-H "Authorization: Bearer $SERPKITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"site:docs.python.org asyncio","country":"us","language":"en"}'Related
Last updated: 2026-11-06