图片搜索实时高级结果

接口概述

该接口用于实时获取指定在图片搜索结果页中的前 100 条图片结果，并返回的 SERP素数据，例如图片结果、搜索细分标签（refinement chips）、搜索等。

请求方式：POST
接口地址：https://api.seermartech.cn/v3/serp/wp/images/live/advanced

说明：
本接口为实时请求接口，请求发出后立即返回解析结果。
每次调用支持提交 1 个任务。
QPS/吞吐限制：最多 2000 次 API 调用/分钟。
POST 请求体为 JSON 数组 格式：[{ ... }]

计费说明

每次请求都会计费。

参考价约 ¥0.0320 / 次
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

depth：

默认返回深度为 100
当 depth 大于 100 时，如果搜索引擎返回 100 条结果，可能产生额外费用
计费按每个最多 100 条结果的 SERP 分段计算
若设置的 depth 高于返回结果数，差额通常会自动退回账户余额

请求参数

主要参数

字段	类型	填	说明
`keyword`	string	是	搜索，最长 700 个字符。字段中的 `%##` 会被解码，`+` 会被解码为空格。如果中需要保留 `%`，请写为 `%25`；需要保留 `+`，请写为 `%2B`。若 `allinanchor:`、`allintext:`、`allintitle:`、`allinurl:`、`define:`、`filetype:`、`id:`、`inanchor:`、`info:`、`intext:`、`intitle:`、`inurl:`、`link:`、`related:`、`site:` 等高级搜索操作符，单任务费用会变为 5 倍。 `cache:` 的查询不受支持，会返回校验错误。
`location_code`	integer	条件填	搜索位置编码。当未提供 `location_name` 或 `location_coordinate` 时填。填写后无需再传 `location_name` 或 `location_coordinate`。位置列表可通过 `/v3/serp/google/locations` 获取。示例：`2840`
`language_code`	string	条件填	搜索语言编码。当未提供 `language_name` 时填。填写后无需再传 `language_name`。语言列表可通过 `/v3/serp/google/languages` 获取。示例：`en`
`depth`	integer	否	解析深度，即期望返回的结果数。默认值：`100`；最大值：`700`

附加参数

字段	类型	填	说明
`location_name`	string	条件填	完整位置名称。当未提供 `location_code` 或 `location_coordinate` 时填。示例：`London,England,United Kingdom`
`language_name`	string	条件填	完整语言名称。当未提供 `language_code` 时填。示例：`English`
`os`	string	否	设备操作系统。该接口返回桌面端结果。可选值：`windows`、`macos`。默认值：`windows`
`tag`	string	否	用户自定义任务标识，最长 `255` 个字符。可用于请求与结果对账，响应中的 `data` 对象会回传该值
`max_crawl_pages`	integer	否	最大抓取结果页数。最大值：`100`。该参数与 `depth`合使用
`search_param`	string	否	搜索附加参数，用于补搜索查询条件
`url`	string	否	直接传搜索 URL，由系统自动拆解为所需字段。此方式解析难度较高，且要求 URL 中准确语言与位置参数，通常不建议优使用。
`location_coordinate`	string	条件填	GPS 坐标位置。当未提供 `location_name` 或 `location_code` 时填。格式：`latitude,longitude,radius`。经纬度最多 7 位小数，`radius` 范围为 `199.9` 到 `199999`（毫米）。示例：`53.476225,-2.243572,200`
`se_domain`	string	否	搜索引擎域名。系统会根据位置和语言自动选择合适域名，也可以手动指定，例如：`google.co.uk`、`google.com.au`、`google.de`

请求示例

curl

bash

curl --location --request POST "https://api.seermartech.cn/v3/serp/wp/images/live/advanced" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/images/live/advanced"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript

import axios from "axios";

async function main {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/wp/images/live/advanced",
 [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein",
 },
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 console.log(response.data);
}

main.catch(console.error);

响应结构

接口返回 JSON 编码结果，顶层 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码，完整列表见 `/v3/appendix/errors`
`status_message`	string	通用状态信息，完整列表见 `/v3/appendix/errors`
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数
`tasks_error`	integer	返回错误的任务数
`tasks`	array	任务结果数组

任务层字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`，完整列表见 `/v3/appendix/errors`
`status_message`	string	任务状态说明
`time`	string	任务执行耗时
`cost`	float	任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	URL 路径
`data`	object	回显请求时提交的参数
`result`	array	结果数组

结果层字段

字段	类型	说明
`keyword`	string	请求中的。返回时 `%##` 会被解码，`+` 会被解码为空格
`type`	string	请求中的搜索引擎类型
`se_domain`	string	请求中的搜索引擎域名
`location_code`	integer	请求中的位置编码
`language_code`	string	请求中的语言编码
`check_url`	string	搜索结果直达链接，可用于人工核验结果准确性
`datetime`	string	数据抓取时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`spell`	object	搜索引擎自动纠错信息
`refinement_chips`	object	搜索细分标签
`item_types`	array	当前 SERP 中出现的结果类型，可能：`carousel`、`images_search`、`related_searches`
`se_results_count`	integer	SERP 总结果数
`items_count`	integer	`items` 数组中的返回数量
`items`	array	SERP 结果项列表

`spell` 字段

当搜索引擎对进行了自动纠错时，会返回该对象。

字段	类型	说明
`keyword`	string	自动纠正后的
`type`	string	自动纠错类型，可选值：`did_you_mean`、`showing_results_for`、`no_results_found_for`、`including_results_for`

`refinement_chips` 字段

字段	类型	说明
`type`	string	固定为 `refinement_chips`
`xpath`	string	素的 XPath
`items`	array	细分标签项

refinement_chips.items 子项字段：

字段	类型	说明
`type`	string	固定为 `refinement_chips_element`
`title`	string	标签标题
`url`	string	带细分参数的搜索 URL
`domain`	string	SERP 中对应域名
`options`	array	进一步细分选项

options 子项字段：

字段	类型	说明
`type`	string	固定为 `refinement_chips_option`
`title`	string	选项标题
`url`	string	带细分参数的搜索 URL
`domain`	string	SERP 中对应域名

SERP素类型说明

1）`carousel`

与目标搜索词的与图片轮播区。

字段	类型	说明
`type`	string	固定为 `carousel`
`rank_group`	integer	同类型中的组排名
`rank_absolute`	integer	在整个 SERP 中的绝对排名
`position`	string	素在页面中的位置，可为 `left`、`right`
`xpath`	string	素 XPath
`title`	string	轮播区标题
`items`	array	与搜索词的和图片
`rectangle`	object	结果块矩形参数。该搜索引擎类型当前不支持 `calculate_rectangles`，因此该字段始终为 `null`

carousel.items 子项字段：

字段	类型	说明
`type`	string	固定为 `carousel_element`
`title`	string	素标题，通常可作为图片搜索细化
`subtitle`	string	素副标题
`image_url`	string	压缩后的特色图片地址
`rectangle`	object	矩形参数。当前始终为 `null`

2）`images_search`

图片搜索结果项。

字段	类型	说明
`type`	string	固定为 `images_search`
`rank_group`	integer	同类型中的组排名
`rank_absolute`	integer	在整个 SERP 中的绝对排名
`xpath`	string	素 XPath
`title`	string	图片结果标题
`subtitle`	string	图片来源站点或副标题
`alt`	string	图片的 alt 文本
`url`	string	图片所在页面 URL
`source_url`	string	原始图片 URL
`encoded_url`	string	搜索引擎缓存的图片 URL

3）`related_searches`

搜索模块。

字段	类型	说明
`type`	string	固定为 `related_searches`
`rank_group`	integer	同类型中的组排名
`rank_absolute`	integer	在整个 SERP 中的绝对排名
`position`	string	素位置，可为 `left`、`right`
`xpath`	string	素 XPath
`items`	array	额外子项；若无则为 `null`
`rectangle`	object	矩形参数。当前始终为 `null`

响应示例

json

{
 "version": "0.1.20220627",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "34.4921 sec.",
 "cost": 0.002,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "live",
 "se": "google",
 "se_type": "images",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "iphone wallpaper",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 0,
 "items_count": 101,
 "items": [
 {
 "type": "carousel",
 "xpath": "/body/div/c-wiz/div/div/c-wiz/scrolling-carousel/div",
 "title": null,
 "items": [],
 "rectangle": null
 },
 {
 "type": "images_search",
 "rank_group": 1,
 "rank_absolute": 2,
 "xpath": "/html/body/div/c-wiz/div/div/div/div/div/div/div/span/div/div",
 "title": "50,000+ Best iPhone Wallpaper Photos ...",
 "subtitle": "pexels.com",
 "alt": "50,000+ Best iPhone Wallpaper Photos · 100% Free Download · Pexels Stock Photos",
 "url": "https://www.pexels.com/search/iphone%20wallpaper/",
 "source_url": "https://images.pexels.com/photos/2486168/pexels-photo-2486168.jpeg?cs=srgb&dl=pexels-roberto-nickson-2486168.jpg&fm=jpg",
 "encoded_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQX_myk5jX77-Ljy3cvcOWEVAcS_QuVL3DTXKYUmpz8hYCnzWj7j6tbd8almtUsQSxSXe0&usqp=CAU"
 },
 {
 "type": "images_search",
 "rank_group": 2,
 "rank_absolute": 3,
 "xpath": "/html/body/div/c-wiz/div/div/div/div/div/div/div/span/div/div",
 "title": "75 IPhone Wallpaper Cool Backgrounds ...",
 "subtitle": "artisthue.com",
 "alt": "75 IPhone Wallpaper Cool Backgrounds For You To Save | Artist Hue",
 "url": "https://artisthue.com/75-cool-iphone-wallpapers-backgrounds-for-you-to-save/",
 "source_url": "https://i0.wp.com/artisthue.com/wp-content/uploads/2020/12/Aesthetic-Full-Moon-Wallpaper.jpg?resize=576%2C1024&ssl=1",
 "encoded_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRv9rxrX1GwaadHzrRf3v23ZKZ2dKHBuS64y-hqojob0NQ8m0WU2Zuvgv4DnNZWkjaEh6w&usqp=CAU"
 },
 {
 "type": "images_search",
 "rank_group": 3,
 "rank_absolute": 4,
 "xpath": "/html/body/div/c-wiz/div/div/div/div/div/div/div/span/div/div",
 "title": "M1 MacBook Pro inspired iPhone wallpapers",
 "subtitle": "idownloadblog.com",
 "alt": "M1 MacBook Pro inspired iPhone wallpapers",
 "url": "https://www.idownloadblog.com/2022/01/30/m1-macbook-pro-inspired-iphone-wallpapers/",
 "source_url": "https://media.idownloadblog.com/wp-content/uploads/2022/01/M1-MacBook-Pro-inspired-wave-wallpaper-for-iPhone-V1.png",
 "encoded_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTgnzannbhGH-EpEluA0ZTu3sIeiH4bPm_uSk2MwFIfdSflCQGagoRr9YY7iwK5exBtvyA&usqp=CAU"
 },
 {
 "type": "related_searches",
 "rank_group": 1,
 "rank_absolute": 25,
 "position": "left",
 "xpath": "/html/body/div/c-wiz/div/div/div/div/div/div/div/div/span/div/div",
 "items": [],
 "rectangle": null
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

请重点处理以下两层状态：

顶层状态：status_code、status_message
任务层状态：tasks[].status_code、tasks[].status_message

完整错误码与说明请参考：

/v3/appendix/errors

建议在集成时至少处理以下：

请求参数缺失或格式错误
keyword含不支持的查询操作符，例如 cache:
位置、语言参数冲突或缺失 -出接口频率限制
任务执行成功但返回结果为空

使用说明与注意事项

每次实时请求只能提交 一个任务
请求体是数组格式，即使只有一个任务也要写成 [{...}]
图片搜索结果支持 桌面端
os 支持 windows 和 macos
如无特殊需求，建议优使用 location_code + language_code
url 方式虽然可用，但解析复杂，通常不建议作为常规调用方式
若要核对结果准确性，可使用返回中的 check_url
当前该搜索类型下 rectangle 字段始终为 null

实用场景

监控图片可见性：按抓取图片搜索结果，评估品牌图片、商品图或图是否前排结果。
识别图片流量来源页：通过 url、source_url、subtitle 分析哪些页面与站点在图片搜索中占优，为图片 SEO 和外链投放提供依据。
挖掘图片搜索细分意图：利用 refinement_chips 和 carousel 中的词发现用户常见图片筛选方向，指导图库分类、落地页命名和扩展。
分析竞品图片资产布局：对竞品品牌词或产品词进行图片 SERP 抓取，识别重点分发渠道、素材样式和占位页面。
校验图片数据优化效果：结合返回的 title、alt、source_url 等字段，验证图片标题、替代文本和图片落地页优化是否带来更好的搜索。

图片搜索实时高级结果 ​

接口概述 ​

计费说明 ​

请求参数 ​

主要参数 ​

附加参数 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务层字段 ​

结果层字段 ​

spell 字段 ​

refinement_chips 字段 ​

SERP素类型说明 ​

1）carousel ​

2）images_search ​

3）related_searches ​

响应示例 ​

状态码与错误处理 ​

使用说明与注意事项 ​

实用场景 ​