SERP guide · migrating from Custom Search
Google Custom Search API Alternative: When a Live SERP Fits Better
You already call the Custom Search JSON API and wonder whether a live SERP endpoint would serve you better. Three questions settle it, and if the answer is yes, one request is all you need to port.
Published · Updated
What Custom Search is good at
Google describes the Custom Search JSON API as a way to retrieve results from a Programmable Search Engine you configure.
- Searching your own site or a hand-picked set of sites, defined by a search engine ID (cx).
- Running under Google's own terms of service for that API, which some teams need for compliance reviews.
- Returning metadata for each hit (title, link, snippet) from the index behind your search engine.
- Custom Search JSON API overview (Google) — quotas and terms are defined there; this page does not restate them
Decision checklist: stay or switch?
Answer three questions in order; the first yes decides.
Do you only search inside your own site or a fixed list of sites?
If yes: Stay on Custom Search: site-restricted search is what it is for.
If no: Go to the next question.
Do you need the rank a page holds on the public results page?
If yes: Use a live SERP endpoint: organic[].rank is the position on the page that was fetched.
If no: Go to the next question.
Do you need the same query on more than one engine?
If yes: Use /v1/serp: each engine has its own organic path with the same response shape.
If no: Either tool can work; compare the fields you actually read.
Param mapping: one CSE call, ported
Custom Search parameter names follow Google's documentation; the right column is the /v1/serp/google/organic body.
q
Meaning: Query text
/v1/serp/google/organic: q
Default: required, 1–512 characters
gl
Meaning: Country to geolocate results
/v1/serp/google/organic: country
Default: US
hl
Meaning: Interface language
/v1/serp/google/organic: hl
Default: en
cx
Meaning: Your Programmable Search Engine ID
/v1/serp/google/organic: no equivalent: the live results page has no site scope
Default: —
key (query string)
Meaning: API key
/v1/serp/google/organic: Authorization: Bearer header
Default: —
curl -X POST https://kieapi.com/v1/serp/google/organic \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: cse-port-0001" \
-d '{"q":"trail running shoes","country":"GB","hl":"en"}'Read organic[] instead of items[]; each row has rank, title, url, display_url and snippet.
What you give up by switching
- Site-restricted search: there is no cx, so you cannot limit results to your own domains.
- The usage model of Google's own API terms: a SERP API reads the public results page, so review the terms that apply to your use.
- Custom Search response fields such as pagemap; /v1/serp returns its own normalized rows.
Launch status for this page
Check engine availability before choosing an endpoint. Google also supports News, Images and asynchronous tasks.
- GoogleGoogle is callable today with a Bearer API key.
SERP searches are charged per successful search at a display rate of 2 Credits per search; failed searches are not charged. Polling task status is free. The current rate is on Pricing.
Frequently asked questions
Does this replace a site-restricted Custom Search engine?
No. /v1/serp searches the public results page and has no cx-style site scope, so keep Custom Search for search inside your own site.
What maps to Custom Search's gl and hl?
country (default US) takes the place of gl, and hl (default en) keeps its name on /v1/serp/google/organic.
What does a ported call cost?
The display rate is 2 Credits per search. Searches are charged per successful search; failed searches are not charged.
Can I call the Google endpoint today?
Google is callable today with a Bearer API key. The SERP API as a whole is not GA.
Port one Custom Search call
Swap gl for country, keep q and hl, and read organic[] with real result positions.