Send POST JSON requests and pass your API key in the X-API-Key header. The response body is JSON for both success and failure cases.
Common response envelope
1 or 2 credits per successful request
support trace id
curl -X POST https://api.serpbase.dev/google/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"q":"openai realtime api","hl":"en","gl":"us"}'Successful endpoint responses return the same top-level metadata. Endpoint-specific data lives in one result key such as organic, images, news, videos, places, or place.
statusnumberrequired
Business status code. 0 means success.
request_idstringrequired
Stable request identifier for support, retries, and log correlation.
elapsed_msnumberrequired
Gateway-observed request latency in milliseconds.
credits_chargednumberrequired
Credits charged after refund logic is applied.
search_typestringrequired
Resolved type: search, images, news, videos, maps_search, or maps_detail.
/google/searchGoogle-style organic results plus rich SERP modules.
/google/imagesImage result URLs, thumbnails, source pages, and domains.
/google/newsNews articles with publisher, time text, snippets, and thumbnails.
/google/videosVideo result links with source, duration, time, and thumbnails.
/google/maps/searchLocal place search with coordinates, contact data, categories, hours, and photos when available.
/google/maps/detailSingle place details by Google Maps feature_id.
/google/searchSearch
Google-style organic results plus rich SERP modules.
qstringrequired
Search query string.
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
pagenumberoptional
1-based page number. Defaults to 1.
querystringrequired
Normalized query from the request.
pagenumberrequired
Current 1-based page number.
organicOrganicResult[]When organic results are parsed.
Organic search results.
top_storiesTopStory[]When the SERP contains top stories.
Top stories module.
people_also_askPAA[]When People Also Ask is present.
Question, answer, and source links.
knowledge_graphKnowledgeGraphWhen a knowledge panel is parsed.
Entity panel data.
related_searchesstring[]When related search suggestions are found.
Related search queries.
ranknumberrequired
1-based ranking position in this response.
positionnumberAlias for rank when available.
Normalized rank alias for clients that expect position.
titlestringrequired
Result title.
linkstringrequired
Primary link returned by the parser.
urlstringPresent for normalized result links.
Canonical target URL, usually the same value as link.
source_urlstringOnly when Google redirect/source URL is observed.
Original Google URL kept for debugging and provenance.
display_urlstringWhen Google display text or a domain can be derived.
Display URL or source domain.
display_linkstringWhen Google display text is present.
Raw Google display link text.
snippetstringWhen a snippet is parsed.
Organic result summary.
datestringWhen Google includes a date in the snippet.
Raw date text extracted from snippet.
published_atstringAlias for parsed date when available.
Normalized date alias.
iconstringWhen a favicon/image is exposed.
Result icon URL.
sitelinks{ title, link, url, source_url?, display_url? }[]When sitelinks are present.
Nested sitelinks for the organic result.
curl -X POST https://api.serpbase.dev/google/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "python asyncio",
"hl": "en",
"gl": "us",
"page": 1
}'Search grounding, SEO checks, answer extraction.
Search can also return ai_overview, weather, finance, flight, and result_stats when those modules appear in the SERP.
/google/imagesImages
Image result URLs, thumbnails, source pages, and domains.
qstringrequired
Search query string.
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
pagenumberoptional
1-based page number. Defaults to 1.
querystringrequired
Normalized query from the request.
pagenumberrequired
Current 1-based page number.
imagesImageResult[]When image results are parsed.
Google Images results.
ranknumberrequired
1-based ranking position in this response.
positionnumberAlias for rank when available.
Normalized rank alias for clients that expect position.
titlestringWhen image title or alt text is parsed.
Result title.
linkstringrequired
Primary link returned by the parser.
urlstringPresent for normalized result links.
Canonical target URL, usually the same value as link.
source_urlstringOnly when Google redirect/source URL is observed.
Original Google URL kept for debugging and provenance.
display_urlstringWhen Google display text or a domain can be derived.
Display URL or source domain.
image_urlstringrequired
Full image URL.
thumbnail_urlstringWhen Google exposes a thumbnail.
Thumbnail URL.
thumbnailstringAlias for thumbnail_url when available.
Normalized thumbnail alias.
sourcestringWhen source text is parsed.
Image source label.
domainstringWhen source page domain can be derived.
Source page domain.
curl -X POST https://api.serpbase.dev/google/images \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "iphone 15 pro blue",
"hl": "en",
"gl": "us",
"page": 1
}'Visual search, product monitoring, image source discovery.
Some Google Images payload shapes expose rank/link but not every normalized alias. Treat url, display_url, source_url, position, and thumbnail as optional.
/google/newsNews
News articles with publisher, time text, snippets, and thumbnails.
qstringrequired
Search query string.
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
pagenumberoptional
1-based page number. Defaults to 1.
querystringrequired
Normalized query from the request.
pagenumberrequired
Current 1-based page number.
newsNewsResult[]When news results are parsed.
Google News results.
ranknumberrequired
1-based ranking position in this response.
positionnumberAlias for rank when available.
Normalized rank alias for clients that expect position.
titlestringrequired
Result title.
linkstringrequired
Primary link returned by the parser.
urlstringPresent for normalized result links.
Canonical target URL, usually the same value as link.
source_urlstringOnly when Google redirect/source URL is observed.
Original Google URL kept for debugging and provenance.
display_urlstringWhen Google display text or a domain can be derived.
Display URL or source domain.
sourcestringWhen publisher text is parsed.
Publisher/source label.
timestringWhen Google exposes time text.
Raw published time text.
published_atstringAlias for parsed time when available.
Normalized published time alias.
snippetstringWhen a snippet is parsed.
Article summary snippet.
thumbnail_urlstringWhen Google exposes a thumbnail.
Thumbnail URL.
thumbnailstringAlias for thumbnail_url when available.
Normalized thumbnail alias.
curl -X POST https://api.serpbase.dev/google/news \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "apple event",
"hl": "en",
"gl": "us",
"page": 1
}'Brand monitoring, trend tracking, media discovery.
Source and time are parsed from compact Google metadata text, so clients should treat both as optional.
/google/videosVideos
Video result links with source, duration, time, and thumbnails.
qstringrequired
Search query string.
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
pagenumberoptional
1-based page number. Defaults to 1.
querystringrequired
Normalized query from the request.
pagenumberrequired
Current 1-based page number.
videosVideoResult[]When video results are parsed.
Google Videos results.
ranknumberrequired
1-based ranking position in this response.
positionnumberAlias for rank when available.
Normalized rank alias for clients that expect position.
titlestringrequired
Result title.
linkstringrequired
Primary link returned by the parser.
urlstringPresent for normalized result links.
Canonical target URL, usually the same value as link.
source_urlstringOnly when Google redirect/source URL is observed.
Original Google URL kept for debugging and provenance.
display_urlstringWhen Google display text or a domain can be derived.
Display URL or source domain.
sourcestringWhen source/channel can be parsed.
Video source or channel label.
durationstringWhen duration appears in result text.
Video duration text.
timestringWhen posted time can be parsed.
Raw posted time text.
published_atstringAlias for parsed time when available.
Normalized posted time alias.
thumbnail_urlstringWhen Google exposes a thumbnail.
Thumbnail URL.
thumbnailstringAlias for thumbnail_url when available.
Normalized thumbnail alias.
curl -X POST https://api.serpbase.dev/google/videos \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "python asyncio tutorial",
"hl": "en",
"gl": "us",
"page": 1
}'Video search, tutorial discovery, media monitoring.
If no dedicated video cards are parsed, the parser falls back to news-style extraction for compatible Google layouts.
/google/maps/searchMaps Search
Local place search with coordinates, contact data, categories, hours, and photos when available.
qstringrequired
Search query string.
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
pagenumberoptional
1-based page number. Defaults to 1.
latnumberoptional
Map center latitude. Must be sent together with lng.
lngnumberoptional
Map center longitude. Must be sent together with lat.
zoomnumberoptional
Map zoom from 1 to 21. Defaults to 14 when coordinates are sent.
querystringrequired
Normalized query from the request.
pagenumberrequired
Current 1-based page number.
placesMapsPlace[]When local places are parsed.
Local place results.
positionnumberMaps Search only.
Place rank in the local result list.
namestringrequired
Place name.
titlestringrequired
Alias for name.
feature_idstringrequired
Google Maps feature id.
place_idstringWhen Google exposes it.
Google place id.
data_idstringAlias for feature_id.
Maps data id.
cidstringDerived from feature_id when possible.
Google CID.
kgmidstringWhen present in Maps payload.
Knowledge graph machine id.
google_maps_urlstringWhen Google exposes a Maps URL.
Google Maps URL.
urlstringgoogle_maps_url or website fallback.
Primary place URL.
ratingnumberWhen rating is present.
Google rating.
typesstring[]When categories are present.
Place type labels.
categoryobjectWhen category block is parsed.
Structured category data.
addressstringWhen address is present.
Formatted address.
address_componentsobjectWhen components are present.
Street, city, postal code, country code.
plus_codeobjectWhen plus code is present.
Global and compound plus codes.
phonestringWhen phone is present.
Local phone number.
phone_internationalstringWhen present.
International phone number.
phone_uristringWhen present.
Telephone URI.
websitestringWhen website is present.
Business website.
website_domainstringWhen website domain is present.
Business website domain.
latitudenumberWhen coordinates are present.
Latitude.
longitudenumberWhen coordinates are present.
Longitude.
imagestringWhen image is present.
Primary place image.
thumbnailstringAlias for image when available.
Primary image alias.
photosMapsPhoto[]When photos are parsed.
Photo id, URL, size, and optional coordinates.
hoursRecord<string,string>When hours are parsed.
Opening hours by day.
open_statusobjectWhen status is present.
Open status text and current hours.
attributesobject[]When attributes are parsed.
Grouped place attributes.
related_placesobject[]When related places are present.
Related places from Maps payload.
short_descriptionstringWhen description block is present.
Short place description.
descriptionstringWhen description block is present.
Longer place description.
snippetstringshort_description or description fallback.
Normalized text summary.
timezonestringWhen present.
Place timezone.
regionstringWhen present.
Region label.
country_codestringWhen present.
Country code.
languagestringWhen present.
Language code from Maps payload.
curl -X POST https://api.serpbase.dev/google/maps/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "coffee",
"hl": "en",
"gl": "us",
"page": 1,
"lat": 37.7749,
"lng": -122.4194,
"zoom": 14
}'Local discovery, store lookup, geo-targeted auditing.
lat and lng must be sent together. zoom is valid only with coordinates and defaults to 14.
/google/maps/detailMaps Detail
Single place details by Google Maps feature_id.
feature_idstringrequired
Google Maps feature id, formatted like 0x...:0x....
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
feature_idstringrequired
Feature id resolved from the Maps detail request.
pagenumberrequired
Always 1 for maps detail.
placeMapsPlaceWhen place details are parsed.
Single place detail object.
positionnumberMaps Search only.
Place rank in the local result list.
namestringrequired
Place name.
titlestringrequired
Alias for name.
feature_idstringrequired
Google Maps feature id.
place_idstringWhen Google exposes it.
Google place id.
data_idstringAlias for feature_id.
Maps data id.
cidstringDerived from feature_id when possible.
Google CID.
kgmidstringWhen present in Maps payload.
Knowledge graph machine id.
google_maps_urlstringWhen Google exposes a Maps URL.
Google Maps URL.
urlstringgoogle_maps_url or website fallback.
Primary place URL.
ratingnumberWhen rating is present.
Google rating.
typesstring[]When categories are present.
Place type labels.
categoryobjectWhen category block is parsed.
Structured category data.
addressstringWhen address is present.
Formatted address.
address_componentsobjectWhen components are present.
Street, city, postal code, country code.
plus_codeobjectWhen plus code is present.
Global and compound plus codes.
phonestringWhen phone is present.
Local phone number.
phone_internationalstringWhen present.
International phone number.
phone_uristringWhen present.
Telephone URI.
websitestringWhen website is present.
Business website.
website_domainstringWhen website domain is present.
Business website domain.
latitudenumberWhen coordinates are present.
Latitude.
longitudenumberWhen coordinates are present.
Longitude.
imagestringWhen image is present.
Primary place image.
thumbnailstringAlias for image when available.
Primary image alias.
photosMapsPhoto[]When photos are parsed.
Photo id, URL, size, and optional coordinates.
hoursRecord<string,string>When hours are parsed.
Opening hours by day.
open_statusobjectWhen status is present.
Open status text and current hours.
attributesobject[]When attributes are parsed.
Grouped place attributes.
related_placesobject[]When related places are present.
Related places from Maps payload.
short_descriptionstringWhen description block is present.
Short place description.
descriptionstringWhen description block is present.
Longer place description.
snippetstringshort_description or description fallback.
Normalized text summary.
timezonestringWhen present.
Place timezone.
regionstringWhen present.
Region label.
country_codestringWhen present.
Country code.
languagestringWhen present.
Language code from Maps payload.
curl -X POST https://api.serpbase.dev/google/maps/detail \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"feature_id": "0x8085809c2c6fdc63:0x4b3f2d70e4f5a123",
"hl": "en",
"gl": "us"
}'Place enrichment, local CRM data, detail pages.
Use feature_id from Maps Search results to request a detail record.
errorstringrequired
Human-readable failure message.
Request completed successfully.
Missing or invalid body or parameters.
Missing, invalid, or revoked API key.
Account balance is not enough.
QPS or concurrency limit exceeded.
Unexpected internal server error.
Worker returned an upstream fetch or parse error.
No worker session is available.
Gateway timed out waiting for a worker result.
{
"status": 1001,
"error": "unauthorized",
"request_id": "0f3576b2-6e2e-4f1e-bb0e-8cb0d4a60195",
"elapsed_ms": 0,
"credits_charged": 0
}