Skip to content

New AI assistant answers: ChatGPT, Gemini, Copilot and AI Mode by API

SerpKite
Get API key
Docs menu / Custom Search (CSE-compatible)

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.

GET https://api.serpkite.com/customsearch/v1 Credits: 1 per page Try in playground
View as Markdown

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

ParameterTypeDefaultDescription
q requiredstringThe search query. Required.
keystringYour SerpKite API key (or send Authorization: Bearer).
cxstringAccepted and ignored.
startinteger1Index of the first result, from 1; start + num - 1 is at most 100. A window that spans two Google pages reads both (2 credits).
numinteger10Results per call, 1–10.
glstringCountry the search is made from.
hlstringInterface language.
lrstringOnly documents in that language, e.g. lang_de.
crstringOnly documents from that country, e.g. countryDE.
safestringSafeSearch. The retired high and medium mean active. One of: active, off.
dateRestrictstringRecency, e.g. d3, w2, m6, y1.
sortstringdate (newest first) or date:r:YYYYMMDD:YYYYMMDD (a date range).
exactTermsstringA phrase every result contains (added to q in quotes).
excludeTermsstringA word or phrase no result contains.
orTermsstringSpace-separated terms; each result contains at least one.
hqstringTerms added to q.
fileTypestringA file extension, e.g. pdf.
lowRangestringWith highRange, a number range added to q as low..high.
highRangestringSee lowRange.
siteSearchstringRestrict to a site.
siteSearchFilterstringe excludes siteSearch instead. One of: i, e.
searchTypestringimage for image results. One of: image.
imgSizestringImages: icon, small, medium, large, xlarge, xxlarge, huge.
imgTypestringImages: clipart, face, lineart, stock, photo, animated.
imgColorTypestringImages: color, gray, mono, trans.
imgDominantColorstringImages: a color such as red.
rightsstringImages: 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

FieldTypeDescription
kindstringcustomsearch#search.
searchInformationobjectsearchTime, formattedSearchTime, totalResults, formattedTotalResults. totalResults is Google's estimate when shown, otherwise 100 while more results follow and the exact count at the end.
items[]arraykind, 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.
queriesobjectrequest[], nextPage[] and previousPage[] as in the CSE API.

Example response

200 OK · illustrative
{
  "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.

StatusCodeMeaning
400invalid_requestA parameter is missing or invalid.
401unauthorizedThe API key is missing, invalid or revoked.
402insufficient_creditsYour balance is too low. Buy a pack or wait for the monthly free grant.
429rate_limitedToo many requests per second for your plan. Retry after the Retry-After header.
503upstream_errorGoogle 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 in error.details[0].reason and error.request_id.