Custom Search (CSE-compatible)
For apps moving off the Google Custom Search JSON API: same query params (key, cx, q, start, num…), same items[] and searchInformation shape.
For apps moving off the Google Custom Search JSON API, which Google shuts down on January 1, 2027. Every CSE query parameter, the same items[] and searchInformation shape and Google's error body. Change the host and the key, keep your parser.
cx is accepted and ignored: results come from the whole web, not a programmable search engine. Use siteSearch or a site: operator to restrict to a domain. This endpoint keeps Google's own parameter names (gl, hl, lr…) and is not under /v1. /customsearch/v1/siterestrict is the same endpoint.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
q required | string | The search query. Required. | |
key | string | Your SerpKite API key (or send Authorization: Bearer). |
|
cx | string | Accepted and ignored. | |
start | integer | 1 | Index of the first result, from 1; start + num - 1 is at most 100. A window that spans two Google pages reads both (2 credits). |
num | integer | 10 | Results per call, 1–10. |
gl | string | Country the search is made from. | |
hl | string | Interface language. | |
lr | string | Only documents in that language, e.g. lang_de. |
|
cr | string | Only documents from that country, e.g. countryDE. |
|
safe | string | SafeSearch. The retired high and medium mean active. One of: active, off. |
|
dateRestrict | string | Recency, e.g. d3, w2, m6, y1. |
|
sort | string | date (newest first) or date:r:YYYYMMDD:YYYYMMDD (a date range). |
|
exactTerms | string | A phrase every result contains (added to q in quotes). |
|
excludeTerms | string | A word or phrase no result contains. | |
orTerms | string | Space-separated terms; each result contains at least one. | |
hq | string | Terms added to q. |
|
fileType | string | A file extension, e.g. pdf. |
|
lowRange | string | With highRange, a number range added to q as low..high. |
|
highRange | string | See lowRange. |
|
siteSearch | string | Restrict to a site. | |
siteSearchFilter | string | e excludes siteSearch instead. One of: i, e. |
|
searchType | string | image for image results. One of: image. |
|
imgSize | string | Images: icon, small, medium, large, xlarge, xxlarge, huge. |
|
imgType | string | Images: clipart, face, lineart, stock, photo, animated. |
|
imgColorType | string | Images: color, gray, mono, trans. |
|
imgDominantColor | string | Images: a color such as red. |
|
rights | string | Images: any cc_* value asks for Creative Commons licences. |
Example request
Pass your key as ?key= like Google's API, or send Authorization: Bearer $SERPKITE_API_KEY.
curl "https://api.serpkite.com/customsearch/v1?q=site%3Adocs.python.org+asyncio&cx=any" \
-H "Authorization: Bearer $SERPKITE_API_KEY"Response fields
| Field | Type | Description |
|---|---|---|
kind | string | customsearch#search. |
searchInformation | object | searchTime, formattedSearchTime, totalResults, formattedTotalResults. totalResults is Google's estimate when shown, otherwise 100 while more results follow and the exact count at the end. |
items[] | array | kind, title, htmlTitle, link, displayLink, snippet, htmlSnippet, formattedUrl, htmlFormattedUrl, pagemap, image. Absent when there are no results. An item whose destination Google held back has link_resolved: false and Google's redirect as link. |
queries | object | request[], nextPage[] and previousPage[] as in the CSE API. |
Example response
{
"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
}
]
}
}Errors
Errors use one shape: {"error":{"code","message","request_id"}}. Errors are never billed.
Full list in Errors.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A parameter is missing or invalid. |
| 401 | unauthorized | The API key is missing, invalid or revoked. |
| 402 | insufficient_credits | Your balance is too low. Buy a pack or wait for the monthly free grant. |
| 429 | rate_limited | Too many requests per second for your plan. Retry after the Retry-After header. |
| 503 | upstream_error | Google could not be fetched or parsed. Not billed; retry after Retry-After. |
Notes
- Errors use Google's error body:
{"error":{"code":400,"message","errors":[{"reason":"badRequest"}],"status":"INVALID_ARGUMENT"}}, with SerpKite's own code inerror.details[0].reasonanderror.request_id.