business_data/business_listings/locations：获取商家列表位置

GET /v3/business_data/business_listings/locations

本接口使用 GET 方法，请求路径为：

/v3/business_data/business_listings/locations

用于获取商家列表服务支持的位置及每个位置的商家数量。也可以通过在路径末尾追加国家或地区代码，获取指定国家或地区的位置列表：

/v3/business_data/business_listings/locations/{country}

例如：

/v3/business_data/business_listings/locations/gb

> 注意：由于地区政策限制，俄罗斯和白俄罗斯的所有位置目前均不支持本平台的服务。

计费说明

调用本接口不收取费用，任务成本为 0。

如需核对扣费，可查看响应头 X-SeerMarTech-Charge-CNY。

请求参数

本接口为 GET 请求，无需请求体。

参数位置	参数名	类型	填	说明
Path	`country`	string	否	ISO 国家代码，例如 `gb`。传后返回指定国家或地区的位置。

请求示例

cURL

bash

curl --location --request GET \
  "https://api.seermartech.cn/v3/business_data/business_listings/locations" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

获取指定国家的位置：

bash

curl --location --request GET \
  "https://api.seermartech.cn/v3/business_data/business_listings/locations/gb" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

Python

python

import requests

url = "https://api.seermartech.cn/v3/business_data/business_listings/locations/gb"

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

response = requests.get(url, headers=headers)
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

import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/business_data/business_listings/locations/gb",
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理返回结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

PHP

php

<?php

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.seermartech.cn/v3/business_data/business_listings/locations/gb',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    echo '请求失败：' . curl_error($ch);
} else {
    $result = json_decode($response, true);
    print_r($result);
}

curl_close($ch);

C#

csharp

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class BusinessLocationsDemo
{
    public static async Task Main()
    {
        using var httpClient = new HttpClient();

        httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "smt_live_YOUR_KEY");

        var response = await httpClient.GetAsync(
            "https://api.seermartech.cn/v3/business_data/business_listings/locations/gb"
        );

        var content = await response.Content.ReadAsStringAsync();

        if (response.IsSuccessStatusCode)
        {
            Console.WriteLine(content);
        }
        else
        {
            Console.WriteLine($"请求失败：{response.StatusCode}");
            Console.WriteLine(content);
        }
    }
}

响应结构

服务端返回 JSON 数据，顶层 tasks 数组。每个任务对象本次请求的状态、执行时间和位置结果。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求的通用状态码。`20000` 表示成功。
`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	位置结果数组。

位置结果字段

字段名	类型	说明
`location_name`	string	位置的完整名称。
`country_iso_code`	string	位置所属国家或地区的 ISO 代码。
`business_count`	integer	数据库中该位置的商家数量。

响应示例

json

{
  "version": "0.1.20221214",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.4116 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1234 sec.",
      "cost": 0,
      "result_count": 2,
      "path": [
        "v3",
        "business_data",
        "business_listings",
        "locations",
        "gb"
      ],
      "data": {
        "api": "business_data",
        "function": "locations",
        "country": "gb"
      },
      "result": [
        {
          "location_name": "London",
          "country_iso_code": "GB",
          "business_count": 125000
        },
        {
          "location_name": "Manchester",
          "country_iso_code": "GB",
          "business_count": 38700
        }
      ]
    }
  ]
}

状态码

20000：请求成功。
状态码：表示请求参数、认证、服务处理或任务执行异常。应结合 status_code 与 status_message 排查问题。

实用场景

筛选目标国家和城市：获取指定国家或地区支持的位置列表，为本地 SEO 项目建立可用的地域范围。
统计区域商家规模：读取 business_count，评估不同城市的商家数量，为市场容量分析和销售区域优级排序提供依据。
构建本地 SEO 数据库：定期同步位置及商家数量，维护城市、国家与商家规模的基础维度表。
校验任务投放范围：在提交商家数据采集或本地搜索任务前，确认目标位置是否受支持，减少无效请求。
分析地域覆盖变化：对不同时间获取的位置数据进行对比，监测平台支持范围及区域商家数据规模的变化。

business_data/business_listings/locations：获取商家列表位置 ​

计费说明 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

PHP ​

C# ​

响应结构 ​

顶层字段 ​

任务字段 ​

位置结果字段 ​

响应示例 ​

状态码 ​

实用场景 ​