SeerMarTech API 文档

主题

keywords_data/dataforseo_trends/locations ​

GET /v3/keywords_data/dataforseo_trends/locations

接口说明 ​

本接口支持以下两种 GET 请求路径：

  • GET https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/locations
  • GET https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/locations/$country

用于获取趋势数据支持的地理位置列表。通过在路径中指定国家/地区 ISO 代码，可以筛选对应国家/地区的地理位置。

> 注意：由于服务政策调整，俄罗斯和白俄罗斯的地理位置目前不再支持。

趋势数据接口支持的最小地理范围为国家/地区级别。

计费说明 ​

调用本接口不收取费用。

响应中的 cost 字段（平台原始 USD 成本兼容字段）通常为 0。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

路径参数 ​

参数名类型填说明
countrystring否国家/地区 ISO 代码。指定后返回该国家/地区下的地理位置。示例：us

请求示例 ​

获取支持的地理位置：

http
GET https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/locations

获取美国的地理位置：

http
GET https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/locations/us

认证方式 ​

请求时请在 Authorization 请求头中传 Bearer Token：

http
Authorization: Bearer smt_live_YOUR_KEY

响应字段 ​

接口返回 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 路径
dataobjectURL 请求中传的参数
resultarray地理位置结果数组

data 字段 ​

字段名类型说明
apistringAPI 模块名称，通常为 keywords_data
functionstringAPI 功能名称，通常为 locations
sestring数据源标识，通常为 dataforseo_trends

result素字段 ​

字段名类型说明
location_codeinteger地理位置代码
location_namestring地理位置完整名称
location_code_parentinteger上级地理位置代码
country_iso_codestring地理位置所属国家/地区的 ISO 代码
location_typestring地理位置类型，取值遵循广告地理定位类型
geo_namestring趋势数据使用的地理位置名称，可用于匹请求中的 location_name
geo_idstring趋势数据使用的地理位置标识，可用于匹请求中的 location_code

location_code_parent 示例：

json
{
  "location_code": 9041134,
  "location_name": "Vienna International Airport,Lower Austria,Austria",
  "location_code_parent": 20044
}

，父级位置代码 20044 对应：

json
{
  "location_code": 20044,
  "location_name": "Lower Austria,Austria"
}

curl 示例 ​

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

按国家/地区筛选：

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

PHP 示例 ​

php
<?php

$apiUrl = 'https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/locations';

$ch = curl_init($apiUrl);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    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);

    if (($result['status_code'] ?? 0) === 20000) {
        print_r($result);
    } else {
        echo '错误码：' . ($result['status_code'] ?? '未知');
        echo '，错误信息：' . ($result['status_message'] ?? '未知');
    }
}

curl_close($ch);

TypeScript 示例 ​

typescript
import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/locations",
    {
      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);
  });

Python 示例 ​

python
import requests

url = "https://api.seermartech.cn/v3/keywords_data/dataforseo_trends/locations"

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"))
    )

C# 示例 ​

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

public static class TrendsLocationsDemo
{
    public static async Task GetLocationsAsync()
    {
        using var httpClient = new HttpClient
        {
            BaseAddress = new Uri("https://api.seermartech.cn/")
        };

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

        var response = await httpClient.GetAsync(
            "/v3/keywords_data/dataforseo_trends/locations"
        );

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

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

响应示例 ​

json
{
  "version": "0.1.20210917",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1012 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "指定任务唯一标识",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1000 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "dataforseo_trends",
        "locations"
      ],
      "data": {
        "api": "keywords_data",
        "function": "locations",
        "se": "dataforseo_trends"
      },
      "result": [
        {
          "location_code": 9041134,
          "location_name": "Vienna International Airport,Lower Austria,Austria",
          "location_code_parent": 20044,
          "country_iso_code": "AT",
          "location_type": "Airport",
          "geo_name": "Vienna International Airport",
          "geo_id": "指定趋势数据地理位置标识"
        }
      ]
    }
  ]
}

状态码 ​

  • 20000：请求成功。
  • 状态码：请求或任务处理失败，原因以 status_message 为准。

实用场景 ​

  • 获取支持的国家和地区列表，为趋势查询构建可选地理范围，提交不受支持的位置参数。
  • 按国家/地区筛选地理位置，为多市场 SEO 项目生成目标市场，提升研究的地域准确性。
  • 匹 location_code 与 geo_id，将地理位置列表与趋势查询任务，确保请求参数和返回结果使用一致的位置标识。
  • 读取上级地理位置，按国家、地区、城市或层级组织 SEO 报告，支持区域市场对比分析。
  • 校验位置名称与类型，在排名、搜索趋势和市场需求分析流程中减少无效地域。

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

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