Response Schema
ResultsPage、Suggestions、Place、App、Trends 等 SERP API 返回的所有类型，逐字段说明。
所有引擎返回同一套共享类型。同一个字段在所有引擎上含义相同。
可选字段确实是可选的：缺失表示页面没有说明。没有 rating 表示没有显示星级，而不是零星。时间为 ISO 8601、UTC。
每个对象都可能带有 ext，其中以该引擎自己的名称保存只有它才有的信息。
| 操作 | 返回 |
|---|---|
search | ResultsPage（应用商店：AppsPage） |
suggestions | Suggestions |
places · place · reviews | PlacesPage · Place · PlaceReviewsPage |
app · reviews（应用商店） | App · AppReviewsPage |
explore · trending（Google Trends） | TrendsExplore · TrendingPage |
Google Shopping 返回电商平台类型 SearchResult、Product 和 ReviewPage，见
Marketplace Response Schema。
ResultsPage
一页结果，按页面显示顺序包含所有区块。
| 字段 | 类型 | 说明 |
|---|---|---|
engine | string | google bing yahoo duckduckgo yandex baidu naver yahoo-japan seznam daum sogou |
query | string | 请求的查询；以图搜图时为引擎给该图片起的名称 |
type | string | web news images videos image |
outcome | string | results，或引擎说明没有结果时为 noResults。被拦截或无法读取的页面是错误，绝不是 noResults |
country lang device timeRange safe | string? | 构成本次搜索的输入，原样返回 |
image | string? | 以图搜图所用的图片 |
correctedQuery | string? | 引擎改写查询时实际搜索的内容（"显示的是以下查询的结果：…"） |
totalResults | integer? | 仅当页面明确给出时（"约 1,230,000 条结果"） |
page | integer | 第一页为 1 |
items | Item[] | 所有区块，按页面顺序。见下文 |
cursor | string? | 下一页。只带 cursor 传入 |
fetchedAt | string | 读取页面的时间 |
每一项都有 type、rank（在页面所有项中从 1 开始的位置）和 ext，其余字段取决于 type：
type | 字段 |
|---|---|
organic | position（仅在自然结果中的排名，跨页连续计数）、url、title、snippet?、site?、displayUrl?、date?、sitelinks?、thumbnail?、image?、imageWidth?、imageHeight?、images?、durationSec?、lang?、favicon?、badges?、facts?、rating?、ratingScale?、reviewCount? |
ad | block?（top bottom side）、url、title、snippet?、advertiser?、displayUrl?、sitelinks?、thumbnail?、phone?、extensions?、favicon?、badges?、rating?、reviewCount?、promotion? |
news | url、title、snippet?、source?、sourceUrl?、sourceLogo?、date?、thumbnail?、favicon? |
image | imageUrl、thumbnail?、width?、height?、title?、url?（图片所在页面）、source?、date?、format?、favicon? |
video | url、title、snippet?、source?、channel?、channelUrl?、avatar?、date?、durationSec?、views?、viewsText?、thumbnail?、embedUrl?、preview?、favicon? |
topStories videoCarousel imagePack shopping twitter discussions | title?、items（区块内的条目）、sponsored?、moreUrl?、total? |
peopleAlsoAsk | title?、questions：{question, answer?, url?, title?}[] |
relatedSearches | title?、queries：string[] |
knowledgePanel | title、subtitle?、description?、source?、facts?、images?、website?、links? |
localPack | places：Place[]、moreUrl?、total? |
aiOverview | answer：AI Answers API 的 Answer 类型，原样不变 |
other | kind（引擎对该区块的称呼）、title?、text?、links? |
sitelinks 和 links 为 {url, title?, snippet?}[]。facts 为按显示顺序排列的 {label, value}[]。badges 是页面给结果
加的标签，逐字保留。rating 使用页面自己的刻度；页面给出刻度时，ratingScale 为其最大值（8.1/10 → 10）。结构中尚无
对应形式的区块以 other 返回，绝不丢弃。
Suggestions
| 字段 | 类型 | 说明 |
|---|---|---|
engine | string | |
query | string | 输入的内容 |
country lang | string? | 传入时原样返回 |
suggestions | array | {text, type?}：引擎的联想词，按引擎顺序。type 为引擎给出的类别（查询、实体等） |
Place
商家或兴趣点。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 引擎的稳定地点 id；传给 place 和 reviews |
name | string | |
url | string? | 该地点在引擎上的页面 |
address | object? | {full?, street?, city?, region?, postalCode?, country?} |
lotAddress | string? | 韩国在道路地址旁显示的地号地址 |
coordinates | object? | {lat, lng} |
categories | string[]? | |
rating reviewCount | number? | 满分 5 的星级及旁边的评论数 |
priceLevel | string? | 按显示原样：$$、₩₩ |
phone website | string? | |
hours | array? | {day, hours}，每个列出的日子一条，时间按显示原样 |
status | string? | open closed temporarilyClosed permanentlyClosed |
statusText | string? | 营业状态原文（"Closed · Opens 7 AM"） |
photos | string[]? | 页面带有的照片；该地点的照片总数为 photoCount |
attributes | array? | {group?, label, value?}：设施、服务选项、支付方式 |
description neighborhood logo | string? | |
verifiedOwner | boolean? | 业主已认领该商家 |
reviewsUrl | string? | 该地点的评论页面 |
lang | string? | 原样返回 |
PlacesPage
| 字段 | 类型 | 说明 |
|---|---|---|
engine query | string | |
outcome | string | results 或 noResults |
type | string? | maps（地图列表）或 local（Google 本地结果） |
location near country lang | string? | 原样返回 |
places | Place[] | |
page | object | {index, size, total?}。仅当引擎给出数量时才有 total |
cursor | string? | 下一页 |
fetchedAt | string |
PlaceReviewsPage
| 字段 | 类型 | 说明 |
|---|---|---|
engine placeId | string | |
summary | object? | {average, count?, distribution?} |
starCounts | object? | 星级 → 评论数，按给出的数值（{"5": 2409, …}） |
sort | string? | |
page | object | {index, size, total?} |
reviews | array | 见下文 |
cursor | string? | |
fetchedAt | string |
评论与电商平台商品评论字段相同：id?、author?、authorAvatarUrl?、rating?、title?、body?、date?、
helpfulCount?、language?、images、reply?（{body, date?, author?}，业主的回复）。地点评论另有 authorId?、
authorUrl? 和 pinned?。地点评论可能没有星级（Naver 访客常留下关键词而非星级），此时 rating 缺失，绝不为 0。
AppsPage
Google Play 和 App Store 的 search 结果。
| 字段 | 类型 | 说明 |
|---|---|---|
engine | string | google-play app-store |
query | string | |
outcome | string | results 或 noResults |
country lang | string? | 原样返回 |
apps | array | 列表中显示的 App，外加 rank |
page | object | {index, size, total?} |
cursor | string? | |
fetchedAt | string |
App
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | Play 为包名（com.strava），Apple 为数字 id（426826309） |
name | string | |
url icon video | string? | |
developer | object? | {id?, name, url?, website?, email?, address?} |
summary | string? | 名称下方的一句话介绍 |
description whatsNew | string? | |
screenshots | string[]? | |
categories | string[]? | 主类别在前 |
rating | object? | {average, count?} |
starCounts | object? | 星级 → 评分数 |
editorsChoice | boolean? | |
price | object? | {currency, amount}；免费应用为 amount: 0 |
inAppPurchases | boolean? | |
contentRating version requires | string? | 按显示原样（"Teen"、"12+"、"Requires iOS 16.0 or later"） |
releasedAt updatedAt | string? | |
country lang | string? | 原样返回 |
related moreByDeveloper | App[]? | 页面在旁边列出的应用，按列表形式（仅 app） |
privacyPolicyUrl | string? | 仅 app |
chart | object? | {name, position}：应用在商店榜单中的位置（仅 app） |
AppReviewsPage
| 字段 | 类型 | 说明 |
|---|---|---|
engine appId | string | |
sort country lang | string? | 原样返回 |
page | object | {index, size, total?} |
reviews | array | id?、author?、rating、title?、body?、date?、helpfulCount?、images、reply?（开发者的回复） |
cursor | string? | |
fetchedAt | string |
TrendsExplore
Google Trends 对最多五个搜索词显示的内容。Trends 给出的是 0 到 100 的相对热度，以本次请求中最热的时间点为基准。
0 也是 Trends 给出的值，因此按 0 返回。
| 字段 | 类型 | 说明 |
|---|---|---|
terms | string[] | 按请求顺序 |
country subregion timeRange category property lang | 输入原样返回。没有 country 表示全球 | |
interestOverTime | object? | {points, averages?}。每个点为 {date, values, partial?, noData?}，每个搜索词一个值 |
interestByRegion | object? | {resolution?, measure?, regions}。地区为 {code?, name, values, noData?, coordinates?}。一个搜索词时 measure 为 interest；多个搜索词时为 share，即各搜索词在该地区相关搜索中的占比 |
related | array? | {term, topics?, queries?}，各自有 top 和 rising 列表，条目为 {title, kind?, id?, value?, growth?, growthValue?, url?} |
fetchedAt | string |
TrendingPage
某个国家当前的热门搜索。
| 字段 | 类型 | 说明 |
|---|---|---|
country subregion window category lang | 原样返回 | |
items | array | {rank, query, volume?, minVolume?, growth?, startedAt?, endedAt?, active?, categories?, related?, articles?} |
fetchedAt | string |
volume 为显示的搜索量（200K+），minVolume 为其下限。articles 为 {title, url, source?, date?, image?}；使用
include=articles 时，返回 Trends 为每个趋势收录的全部文章。