使用 POST JSON 请求，并在 X-API-Key 请求头传入 API key。成功和失败都会返回 JSON body。
公共响应结构
成功请求按 1 或 2 点扣费
support trace id
curl -X POST https://test-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"}'接口成功响应会返回同一套顶层元数据。接口自己的数据只放在 organic、images、news、videos、places 或 place 这类结果字段里。
statusnumber必填
业务状态码，0 表示成功。
request_idstring必填
稳定请求 ID，用于支持、重试和日志关联。
elapsed_msnumber必填
网关观测到的请求耗时，单位毫秒。
credits_chargednumber必填
退款逻辑处理后实际扣除的点数。
search_typestring必填
解析后的接口类型：search、images、news、videos、maps_search 或 maps_detail。
/google/search搜索
Google 风格自然结果，并包含可解析的 SERP 模块。
qstring必填
搜索查询字符串。
hlstring可选
语言代码，默认 en。
glstring可选
国家代码，默认 us。
pagenumber可选
从 1 开始的页码，默认 1。
querystring必填
请求中的标准化 query。
pagenumber必填
当前页码，从 1 开始。
organicOrganicResult[]解析到自然结果时返回。
自然搜索结果。
top_storiesTopStory[]SERP 包含 Top Stories 时返回。
Top Stories 模块。
people_also_askPAA[]存在 People Also Ask 时返回。
问题、答案和来源链接。
knowledge_graphKnowledgeGraph解析到知识面板时返回。
实体面板数据。
related_searchesstring[]找到相关搜索时返回。
相关搜索词。
ranknumber必填
当前响应里的 1-based 排名。
positionnumber可用时作为 rank 的别名。
给客户端使用的标准化排名别名。
titlestring必填
结果标题。
linkstring必填
parser 返回的主链接。
urlstring结果链接可归一化时返回。
规范化目标 URL，通常和 link 相同。
source_urlstring只有观测到 Google 跳转/来源 URL 时返回。
保留的原始 Google URL，用于调试和溯源。
display_urlstring当 Google 展示文本或域名可解析时返回。
展示 URL 或来源域名。
display_linkstringGoogle 展示文本存在时返回。
Google 原始展示链接文本。
snippetstring解析到摘要时返回。
自然结果摘要。
datestringGoogle 摘要中带日期时返回。
从摘要中提取的原始日期文本。
published_atstring解析到日期时作为日期别名返回。
标准化日期别名。
iconstring解析到图标或图片时返回。
结果图标 URL。
sitelinks{ title, link, url, source_url?, display_url? }[]存在站内链接时返回。
自然结果下的站内链接。
curl -X POST https://test-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
}'搜索 grounding、SEO 检查、答案提取。
Search 还可能返回 ai_overview、weather、finance、flight、result_stats，取决于 SERP 是否出现这些模块。
/google/images图片搜索
图片 URL、缩略图、来源页面和域名。
qstring必填
搜索查询字符串。
hlstring可选
语言代码，默认 en。
glstring可选
国家代码，默认 us。
pagenumber可选
从 1 开始的页码，默认 1。
querystring必填
请求中的标准化 query。
pagenumber必填
当前页码，从 1 开始。
imagesImageResult[]解析到图片结果时返回。
Google 图片结果。
ranknumber必填
当前响应里的 1-based 排名。
positionnumber可用时作为 rank 的别名。
给客户端使用的标准化排名别名。
titlestring解析到图片标题或 alt 文本时返回。
结果标题。
linkstring必填
parser 返回的主链接。
urlstring结果链接可归一化时返回。
规范化目标 URL，通常和 link 相同。
source_urlstring只有观测到 Google 跳转/来源 URL 时返回。
保留的原始 Google URL，用于调试和溯源。
display_urlstring当 Google 展示文本或域名可解析时返回。
展示 URL 或来源域名。
image_urlstring必填
完整图片 URL。
thumbnail_urlstringGoogle 暴露缩略图时返回。
缩略图 URL。
thumbnailstring可用时作为 thumbnail_url 的别名。
标准化缩略图别名。
sourcestring解析到来源文本时返回。
图片来源名称。
domainstring能从来源页面解析域名时返回。
来源页面域名。
curl -X POST https://test-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
}'视觉搜索、商品监控、图片来源发现。
Google 图片存在多种页面结构，有些样本只稳定暴露 rank/link，不一定都有 url、display_url、source_url、position、thumbnail 这些别名，客户端应按可选字段处理。
/google/news新闻搜索
新闻文章，包含发布方、时间文本、摘要和缩略图。
qstring必填
搜索查询字符串。
hlstring可选
语言代码，默认 en。
glstring可选
国家代码，默认 us。
pagenumber可选
从 1 开始的页码，默认 1。
querystring必填
请求中的标准化 query。
pagenumber必填
当前页码，从 1 开始。
newsNewsResult[]解析到新闻结果时返回。
Google 新闻结果。
ranknumber必填
当前响应里的 1-based 排名。
positionnumber可用时作为 rank 的别名。
给客户端使用的标准化排名别名。
titlestring必填
结果标题。
linkstring必填
parser 返回的主链接。
urlstring结果链接可归一化时返回。
规范化目标 URL，通常和 link 相同。
source_urlstring只有观测到 Google 跳转/来源 URL 时返回。
保留的原始 Google URL，用于调试和溯源。
display_urlstring当 Google 展示文本或域名可解析时返回。
展示 URL 或来源域名。
sourcestring解析到发布方文本时返回。
发布方或来源名称。
timestringGoogle 暴露时间文本时返回。
原始发布时间文本。
published_atstring解析到 time 时返回的发布时间别名。
标准化发布时间别名。
snippetstring解析到摘要时返回。
新闻摘要。
thumbnail_urlstringGoogle 暴露缩略图时返回。
缩略图 URL。
thumbnailstring可用时作为 thumbnail_url 的别名。
标准化缩略图别名。
curl -X POST https://test-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
}'品牌监控、趋势跟踪、媒体发现。
source 和 time 来自 Google 紧凑元数据文本，客户端应按可选字段处理。
/google/videos视频搜索
视频结果链接，包含来源、时长、时间和缩略图。
qstring必填
搜索查询字符串。
hlstring可选
语言代码，默认 en。
glstring可选
国家代码，默认 us。
pagenumber可选
从 1 开始的页码，默认 1。
querystring必填
请求中的标准化 query。
pagenumber必填
当前页码，从 1 开始。
videosVideoResult[]解析到视频结果时返回。
Google 视频结果。
ranknumber必填
当前响应里的 1-based 排名。
positionnumber可用时作为 rank 的别名。
给客户端使用的标准化排名别名。
titlestring必填
结果标题。
linkstring必填
parser 返回的主链接。
urlstring结果链接可归一化时返回。
规范化目标 URL，通常和 link 相同。
source_urlstring只有观测到 Google 跳转/来源 URL 时返回。
保留的原始 Google URL，用于调试和溯源。
display_urlstring当 Google 展示文本或域名可解析时返回。
展示 URL 或来源域名。
sourcestring解析到来源或频道时返回。
视频来源或频道。
durationstring结果文本包含时长时返回。
视频时长文本。
timestring解析到发布时间时返回。
原始发布时间文本。
published_atstring解析到 time 时返回的时间别名。
标准化发布时间别名。
thumbnail_urlstringGoogle 暴露缩略图时返回。
缩略图 URL。
thumbnailstring可用时作为 thumbnail_url 的别名。
标准化缩略图别名。
curl -X POST https://test-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
}'视频搜索、教程发现、媒体监控。
如果没有解析到专用视频卡片，parser 会对兼容的 Google 布局回退到 news 风格提取。
/google/maps/search地图搜索
本地地点搜索，可返回坐标、联系信息、分类、营业时间和照片。
qstring必填
搜索查询字符串。
hlstring可选
语言代码，默认 en。
glstring可选
国家代码，默认 us。
pagenumber可选
从 1 开始的页码，默认 1。
latnumber可选
地图中心纬度，必须和 lng 一起传。
lngnumber可选
地图中心经度，必须和 lat 一起传。
zoomnumber可选
地图缩放级别 1 到 21；传坐标时默认 14。
querystring必填
请求中的标准化 query。
pagenumber必填
当前页码，从 1 开始。
placesMapsPlace[]解析到本地地点时返回。
本地地点结果。
positionnumber仅 Maps Search 返回。
地点在本地结果列表中的排名。
namestring必填
地点名称。
titlestring必填
name 的别名。
feature_idstring必填
Google Maps feature id。
place_idstringGoogle 暴露时返回。
Google place id。
data_idstringfeature_id 的别名。
Maps data id。
cidstring可从 feature_id 解析时返回。
Google CID。
kgmidstringMaps payload 中存在时返回。
知识图谱机器 ID。
google_maps_urlstringGoogle 暴露 Maps URL 时返回。
Google Maps URL。
urlstring来自 google_maps_url，缺失时回退到 website。
地点主 URL。
ratingnumber存在评分时返回。
Google 评分。
typesstring[]存在分类时返回。
地点类型标签。
categoryobject解析到分类块时返回。
结构化分类数据。
addressstring存在地址时返回。
格式化地址。
address_componentsobject存在地址组件时返回。
街道、城市、邮编、国家代码。
plus_codeobject存在 plus code 时返回。
global_code 和 compound_code。
phonestring存在电话时返回。
本地电话号码。
phone_internationalstring存在时返回。
国际电话号码。
phone_uristring存在时返回。
电话 URI。
websitestring存在官网时返回。
商户官网。
website_domainstring存在官网域名时返回。
商户官网域名。
latitudenumber存在坐标时返回。
纬度。
longitudenumber存在坐标时返回。
经度。
imagestring存在图片时返回。
地点主图。
thumbnailstringimage 可用时作为别名返回。
主图别名。
photosMapsPhoto[]解析到照片时返回。
照片 ID、URL、尺寸和可选坐标。
hoursRecord<string,string>解析到营业时间时返回。
按星期组织的营业时间。
open_statusobject存在营业状态时返回。
营业状态文本和当前营业时间。
attributesobject[]解析到属性时返回。
分组地点属性。
related_placesobject[]存在相关地点时返回。
Maps payload 中的相关地点。
short_descriptionstring存在描述块时返回。
地点短描述。
descriptionstring存在描述块时返回。
地点长描述。
snippetstring来自 short_description 或 description。
标准化文本摘要。
timezonestring存在时返回。
地点时区。
regionstring存在时返回。
区域标签。
country_codestring存在时返回。
国家代码。
languagestring存在时返回。
Maps payload 中的语言代码。
curl -X POST https://test-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
}'本地发现、门店查询、地理定向审计。
lat 和 lng 必须一起传。zoom 只有传坐标时才有效，默认 14。
/google/maps/detail地图详情
通过 Google Maps feature_id 获取单个地点详情。
feature_idstring必填
Google Maps feature id，格式类似 0x...:0x...。
hlstring可选
语言代码，默认 en。
glstring可选
国家代码，默认 us。
feature_idstring必填
地图详情请求解析出的 feature_id。
pagenumber必填
地图详情固定为 1。
placeMapsPlace解析到地点详情时返回。
单个地点详情对象。
positionnumber仅 Maps Search 返回。
地点在本地结果列表中的排名。
namestring必填
地点名称。
titlestring必填
name 的别名。
feature_idstring必填
Google Maps feature id。
place_idstringGoogle 暴露时返回。
Google place id。
data_idstringfeature_id 的别名。
Maps data id。
cidstring可从 feature_id 解析时返回。
Google CID。
kgmidstringMaps payload 中存在时返回。
知识图谱机器 ID。
google_maps_urlstringGoogle 暴露 Maps URL 时返回。
Google Maps URL。
urlstring来自 google_maps_url，缺失时回退到 website。
地点主 URL。
ratingnumber存在评分时返回。
Google 评分。
typesstring[]存在分类时返回。
地点类型标签。
categoryobject解析到分类块时返回。
结构化分类数据。
addressstring存在地址时返回。
格式化地址。
address_componentsobject存在地址组件时返回。
街道、城市、邮编、国家代码。
plus_codeobject存在 plus code 时返回。
global_code 和 compound_code。
phonestring存在电话时返回。
本地电话号码。
phone_internationalstring存在时返回。
国际电话号码。
phone_uristring存在时返回。
电话 URI。
websitestring存在官网时返回。
商户官网。
website_domainstring存在官网域名时返回。
商户官网域名。
latitudenumber存在坐标时返回。
纬度。
longitudenumber存在坐标时返回。
经度。
imagestring存在图片时返回。
地点主图。
thumbnailstringimage 可用时作为别名返回。
主图别名。
photosMapsPhoto[]解析到照片时返回。
照片 ID、URL、尺寸和可选坐标。
hoursRecord<string,string>解析到营业时间时返回。
按星期组织的营业时间。
open_statusobject存在营业状态时返回。
营业状态文本和当前营业时间。
attributesobject[]解析到属性时返回。
分组地点属性。
related_placesobject[]存在相关地点时返回。
Maps payload 中的相关地点。
short_descriptionstring存在描述块时返回。
地点短描述。
descriptionstring存在描述块时返回。
地点长描述。
snippetstring来自 short_description 或 description。
标准化文本摘要。
timezonestring存在时返回。
地点时区。
regionstring存在时返回。
区域标签。
country_codestring存在时返回。
国家代码。
languagestring存在时返回。
Maps payload 中的语言代码。
curl -X POST https://test-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"
}'地点补全、本地 CRM 数据、详情页。
通常先从 Maps Search 结果拿 feature_id，再请求详情。
errorstring必填
可读错误信息。
请求成功完成。
请求体或参数缺失/无效。
API key 缺失、无效或已撤销。
账号余额不足。
QPS 或并发限制已触发。
意外的内部服务错误。
worker 返回上游抓取或解析错误。
当前没有可用 worker 会话。
网关等待 worker 结果超时。
{
"status": 1001,
"error": "unauthorized",
"request_id": "0f3576b2-6e2e-4f1e-bb0e-8cb0d4a60195",
"elapsed_ms": 0,
"credits_charged": 0
}