SERP 图片实时高级接口

本接口通过实时采集，返回指定、搜索引擎和地理位置下的图片搜索结果，最多支持前 100 个结果。

请求方法与路径：

http

POST https://api.seermartech.cn/v3/serp/wp/images/live/advanced

所有 POST 请求体使用 UTF-8 编码的 JSON 格式，并将任务参数放顶层 JSON 数组中。每次调用只能提交一个任务；平台限流以认证说明中的 30/60/120 次/分钟规则为准。

计费说明

每个任务单独计费。depth 默认获取 100 条结果， 100 条时，可能产生额外费用；如果返回结果少于指定深度，未使用部分会自动退还。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

###填参数

参数	类型	说明
`keyword`	string	填。查询，最长 700 个字符。参数中的 `%##` 编码会被解码，字符 `+` 会被解码为空格。<br><br>如需在中使用 `%`，请写作 `%25`；如需使用 `+`，请写作 `%2B`。<br><br>如果 `allinanchor:`、`allintext:`、`allintitle:`、`allinurl:`、`define:`、`filetype:`、`id:`、`inanchor:`、`info:`、`intext:`、`intitle:`、`inurl:`、`link:`、`related:` 或 `site:` 等搜索运算符，单任务费用将按 5 倍计算。 `cache:` 的查询不受支持，并会返回参数校验错误。
`location_code`	integer	搜索引擎地理位置代码。当未指定 `location_name` 或 `location_coordinate` 时填。使用此参数后，无需再指定另外两个位置参数。可通过 `GET https://api.seermartech.cn/v3/serp/google/locations` 获取可用位置代码。示例：`2840`。
`language_code`	string	搜索引擎语言代码。当未指定 `language_name` 时填。使用此参数后，无需再指定 `language_name`。可通过 `GET https://api.seermartech.cn/v3/serp/google/languages` 获取可用语言代码。示例：`en`。

通用参数

参数	类型	说明
`depth`	integer	SERP 解析深度，即需要返回的结果数量。可选，默认值为 `100`，最大值为 `200`。深度 100 时，如果搜索引擎返回了更多结果，可能产生额外计费。
`location_name`	string	搜索引擎地理位置的完整名称。当未指定 `location_code` 或 `location_coordinate` 时填。使用此参数后，无需再指定另外两个位置参数。可通过 `GET https://api.seermartech.cn/v3/serp/google/locations` 获取可用位置名称。示例：`London,England,United Kingdom`。
`language_name`	string	搜索引擎语言的完整名称。当未指定 `language_code` 时填。使用此参数后，无需再指定 `language_code`。可通过 `GET https://api.seermartech.cn/v3/serp/google/languages` 获取可用语言名称。示例：`English`。
`os`	string	设备操作系统。当前接口提供桌面端结果。可选值：`windows`、`macos`。默认值：`windows`。
`tag`	string	用户自定义任务标识，最长 255 个字符。可用于请求与响应，提交的值会原样返回在响应任务的 `data` 对象中。
`max_crawl_pages`	integer	最大抓取页数，即需要抓取的搜索结果页数量。可选，最大值为 `100`。该参数与 `depth`合使用。
`search_param`	string	搜索查询的附加参数。可用于传递搜索引擎支持的额外查询设置。
`url`	string	搜索查询的完整 URL。接口会从 URL 中解析相应的查询参数。该方式对语言和地理位置要求较高，处理复杂度也更高，通常不建议使用。示例：<br>`https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS`
`location_coordinate`	string	地理位置 GPS 坐标，格式为 `纬度,经度,半径`。纬度和经度最多支持 7 位小数；半径最小值为 `199.9` 米，最大值为 `199999` 米。当未指定 `location_name` 或 `location_code` 时填。示例：`53.476225,-2.243572,200`。
`se_domain`	string	搜索引擎域名。接口会根据位置和语言自动选择对应域名，也可以手动指定。示例：`google.co.uk`、`google.com.au`、`google.de`。

> location_code、location_name、location_coordinate 三只能选择一；language_code 与 language_name 只能选择一。

请求示例

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",
      "depth": 100,
      "os": "windows",
      "tag": "image-serp-demo"
    }
  ]'

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",
}

# 每次请求只能提交一个任务
payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=60)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败：{} {}".format(
            result.get("status_code"),
            result.get("status_message"),
        )
    )

TypeScript

typescript

const response = await fetch(
  "https://api.seermartech.cn/v3/serp/wp/images/live/advanced",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify([
      {
        language_code: "en",
        location_code: 2840,
        keyword: "albert einstein",
      },
    ]),
  }
);

const result = await response.json();

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(result.status_code, result.status_message);
}

响应结构

接口返回 JSON 对象，核心结构如下：

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": [
    {
      "id": "task-uuid",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "34.4921 sec.",
      "cost": 0.002,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "wp",
        "images",
        "live",
        "advanced"
      ],
      "data": {
        "api": "serp",
        "function": "live",
        "se": "google",
        "se_type": "images",
        "language_code": "en",
        "location_code": 2840,
        "keyword": "iphone wallpaper",
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "iphone wallpaper",
          "type": "images",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://www.google.com/search?q=iphone+wallpaper",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "se_results_count": 101,
          "items_count": 101,
          "items": []
        }
      ]
    }
  ]
}

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	顶层状态码。完整错误码请参考 `/v3/appendix/errors`。
`status_message`	string	顶层状态说明。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常处于 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	当前请求的 URL 路径组成部分。
`data`	object	请求中提交的任务参数。
`result`	array	SERP 解析结果数组。

`result` 结果字段

字段	类型	说明
`keyword`	string	请求中的。返回时，`%##` 编码会被解码，字符 `+` 会被解码为空格。
`type`	string	请求使用的搜索引擎类型。
`se_domain`	string	请求使用的搜索引擎域名。
`location_code`	integer	搜索引擎位置代码。
`language_code`	string	搜索引擎语言代码。
`check_url`	string	对应的搜索结果页 URL，可用于核验返回结果。
`datetime`	string	获取结果的时间，使用 UTC 格式 `yyyy-mm-dd hh-mm-ss +00:00`。示例：`2019-11-15 12:57:46 +00:00`。
`spell`	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`。

`carousel` 图片与模块

carousel 表示与当前搜索词的和图片轮播模块。

字段	类型	说明
`type`	string	固定为 `carousel`。
`rank_group`	integer	同类型中的组排名。不同类型之间不会影响该排名。
`rank_absolute`	integer	该在整个 SERP 中的绝对排名。
`position`	string	素在 SERP 中的对齐方式，可选值：`left`、`right`。
`xpath`	string	素在页面中的 XPath。
`title`	string	SERP素标题。
`items`	array	轮播模块中的和图片。
`rectangle`	object/null	素在 SERP 中的矩形坐标和像素尺寸。当前搜索引擎类型暂不支持 `calculate_rectangles`，因此始终为 `null`。

carousel.items 子字段：

字段	类型	说明
`type`	string	固定为 `carousel_element`。
`title`	string	素标题，表示可用于细化图片搜索的。
`subtitle`	string	SERP 中的副标题。
`image_url`	string	压缩特色图片 URL。

`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。

`related_searches` 搜索模块

字段	类型	说明
`type`	string	固定为 `related_searches`。
`rank_group`	integer	同类型中的组排名。
`rank_absolute`	integer	该在整个 SERP 中的绝对排名。
`position`	string	素在 SERP 中的对齐方式，可选值：`left`、`right`。
`xpath`	string	素在页面中的 XPath。
`items`	array/null	素中的附加项目；没有项目时为 `null`。
`rectangle`	object/null	素在 SERP 中的矩形坐标和像素尺寸。当前搜索引擎类型暂不支持 `calculate_rectangles`，因此始终为 `null`。

错误处理

建议根据顶层和任务级别的 status_code、status_message 进行错误处理：

顶层 status_code 用于判断本次 API 请求是否成功。
tasks_error 用于快速判断是否存在失败任务。
每个任务的 status_code 和 status_message 用于定位任务问题。
完整状态码和错误说明请参考 /v3/appendix/errors。

实用场景

监控图片排名：批量获取目标的图片 SERP 结果，评估图片的自然和排名变化。
分析图片 SEO 竞争对手：提取竞争页面的图片标题、alt 文本、来源图片和落地页 URL，定位优化差距。
发现图片搜索扩展词：读取 carousel 和 related_searches 模块，挖掘用户在图片搜索中的需求，扩展选题与库。
评估多地区图片可见性：使用不同位置代码、语言代码和搜索引擎域名采集结果，对比品牌图片在不同市场的表现。
校验图片素材优化效果：通过 title、alt、source_url 和 rank_absolute 等字段，跟踪图片数据优化后对搜索展示的影响。

SERP 图片实时高级接口 ​

计费说明 ​

请求参数 ​

通用参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

result 结果字段 ​

spell 自动纠错字段 ​

carousel 图片与模块 ​

images_search 图片结果 ​

related_searches 搜索模块 ​

错误处理 ​

实用场景 ​