SeerMarTech API 文档

主题

Google 以图搜图实时 SERP HTML ​

本接口使用 POST 方法，路径为：

/v3/serp/google/search_by_image/live/html

实时提交一张图片、搜索引擎及地区信息，获取 Google 以图搜图结果页的原始 HTML。默认返回最多 100 条搜索结果。

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

计费说明 ​

每次请求均会产生费用。参考价约 ¥0.0220 / 次。

当 depth过 100 且搜索引擎返回 100 条结果时，可能产生额外费用。如果指定的 depth 高于返回结果数量，未使用部分将自动退还至账户余额。

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

请求参数 ​

请求体是 JSON 数组，数组中最多一个任务对象。

参数类型填说明
image_urlstring是图片 URL。搜索结果将基于该图片生成。
location_namestring条件填搜索引擎地区的完整名称。当未指定 location_code 或 location_coordinate 时填。使用此参数后，无需再传另外两个地区参数。
location_codeinteger条件填搜索引擎地区编码。当未指定 location_name 或 location_coordinate 时填。使用此参数后，无需再传另外两个地区参数。
location_coordinatestring条件填地区 GPS 坐标，格式为 纬度,经度,半径。当未指定 location_name 或 location_code 时填。
language_namestring条件填搜索引擎语言的完整名称。当未指定 language_code 时填。
language_codestring条件填搜索引擎语言代码。当未指定 language_name 时填。
se_domainstring否搜索引擎域名。平台通常会根据地区和语言自动选择合适的域名，也可以在此参数中指定自定义域名，例如 google.co.uk、google.com.au、google.de。
depthinteger否SERP 解析深度，即需要获取的结果数量。默认值为 100，最大值为 700。
search_paramstring否搜索查询附加参数。
tagstring否用户自定义任务标识，用于请求和响应结果，最大长度为 255 个字符。该值会原样出现在响应的 data 数组中。

地区参数说明 ​

location_name、location_code 和 location_coordinate 三只能选择一个。

  • location_name 示例：London,England,United Kingdom
  • location_code 示例：2840
  • location_coordinate 示例：53.476225,-2.243572,200

location_coordinate 的限制如下：

  • 格式：latitude,longitude,radius
  • 纬度和经度最多保留 7 位小数
  • radius 最小值：199.9 毫米
  • radius 最大值：199999 毫米

可通过地区查询接口获取可用地区及编码：

/v3/serp/wp/locations

语言参数说明 ​

language_name 与 language_code 二选一。

  • language_name 示例：English
  • language_code 示例：en

可通过语言查询接口获取可用语言及代码：

/v3/serp/wp/languages

请求示例 ​

cURL ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/serp/google/search_by_image/live/html" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg"
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/serp/google/search_by_image/live/html"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg",
    }
]

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

result = response.json()
if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：%s，错误信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript ​

typescript
const response = await fetch(
  "https://api.seermartech.cn/v3/serp/google/search_by_image/live/html",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify([
      {
        language_code: "en",
        location_code: 2840,
        image_url:
          "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg",
      },
    ]),
  }
);

const result = await response.json();

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(
    `请求失败，错误码：${result.status_code}，错误信息：${result.status_message}`
  );
}

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组。

字段类型说明
versionstring当前 API 版本。
status_codeinteger局状态码。
status_messagestring局提示信息。
timestring请求执行时间，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数。
tasks_errorintegertasks 数组中执行失败的任务数。
tasksarray任务结果数组。

tasks 字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常位于 10000 至 60000 范围。
status_messagestring任务状态说明。
timestring任务执行时间，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求 URL 路径。
dataarray创建任务时提交的参数。
resultarraySERP 结果数组。

result 字段 ​

字段类型说明
image_urlstring请求中提交的图片 URL。
keywordstringGoogle 根据图片出的。
typestring搜索引擎类型。
se_domainstring实使用的搜索引擎域名。
location_codeinteger实使用的地区编码。
language_codestring实使用的语言代码。
datetimestring获取结果的日期和时间，格式为 YYYY-MM-DD HH:MM:SS +UTC偏移，例如 2019-11-15 12:57:46 +00:00。
items_countintegeritems 数组中返回的结果数量。
itemsarraySERP 结果项数组。

items 字段 ​

字段类型说明
pageinteger返回的 HTML 页面序号。
datestringHTML 页面抓取时间，格式为 YYYY-MM-DD HH:MM:SS +UTC偏移，例如 2019-11-15 12:57:46 +00:00。
htmlstring搜索结果页的原始 HTML。

响应示例 ​

json
{
  "version": "0.1.20200923",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "33.3515 sec.",
  "cost": 0.003,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "33.3515 sec.",
      "cost": 0.003,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "google",
        "search_by_image",
        "live",
        "html"
      ],
      "data": [
        {
          "api": "serp",
          "function": "live",
          "se": "google",
          "se_type": "search_by_image",
          "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg",
          "language_code": "en",
          "location_code": 2840,
          "device": "desktop",
          "os": "windows"
        }
      ],
      "result": [
        {
          "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg",
          "keyword": "example keyword",
          "type": "search_by_image",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": "en",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "items_count": 1,
          "items": [
            {
              "page": 1,
              "date": "2019-11-15 12:57:46 +00:00",
              "html": "<html>...</html>"
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理 ​

请根据以下字段判断请求是否成功：

  • 顶层 status_code
  • 任务级 tasks[].status_code
  • 对应的 status_message

当状态码为 20000 时，表示请求成功。状态码表示请求或任务执行异常，错误信息以 status_message 为准。

实用场景 ​

  • 识别图片：批量获取搜索引擎根据图片生成的，为图片 SEO、标注和扩展提供数据依据。
  • 监测图片搜索：抓取指定地区和语言下的以图搜图结果 HTML，分析品牌图片、产品图片在搜索结果中的可见性。
  • 发现图片盗用页面：对原创图片执行反向图片搜索，定位可能使用该图片的网页，版权保护和维权。
  • 分析竞品视觉素材覆盖：提交竞品产品图或宣传图，比较在不同市场的搜索结果，支持竞品研究和市场分析。
  • 构建图片 SEO 评估流程：结合 location_code、language_code 和 depth 参数，定期采集多地区结果，评估图片优化策略在不同市场的表现。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API