行政区搜索 - 迈云位置服务 API 文档

接口说明

行政区搜索接口支持按行政区名称或 adcode 进行模糊匹配，返回匹配的行政区列表及完整的行政区层级路径，适用于搜索框自动补全、区域快速定位等场景。

请求方式POST

支持地区中国大陆

坐标系GCJ02（火星坐标系）

认证方式

所有 API 请求均需通过 HTTP Authorization 请求头携带 Bearer Token 进行身份验证。 Token 可在控制台的「团队设置 → API 密钥」中创建和管理。

// 请求头示例

Authorization: Bearer <YOUR_API_KEY>

Token 属于密钥凭证，请勿提交到代码仓库或公开渠道。建议通过服务端代理调用 API，避免在前端直接暴露 Token。

请求参数

POST/api/service/scenario/search

参数名	类型	必填	说明
keyword	string	必填	搜索关键词，支持行政区名称或 adcode
polygon	boolean	可选	是否返回边界坐标数据，默认 false

返回字段

成功响应result: 1HTTP 200

字段名	类型	说明
status	integer	状态码，0 为成功
message	string	返回信息
data_version	string	数据版本号，格式如 20250721
result	array	匹配的行政区列表，每个元素为该行政区的完整层级路径数组
└adcode	string	行政区编码
└name	string	行政区名称
└level	integer	行政级别：1=省，2=市，3=区县，4=乡镇
└location	object	行政区中心坐标，GCJ02 坐标系
└lat	number	纬度
└lng	number	经度
└address	string	完整行政区路径，如"北京市/北京市/东城区"
└polygon	array	边界坐标点数组（polygon=true 时返回）

代码示例

请求示例

JavaScript

fetch('https://lts.maiyun.net/api/service/scenario/search', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        keyword: '北京',
        polygon: false,
    }),
})
    .then(r => r.json())
    .then(data => {
        console.log(data.result);
    });

返回示例（成功）

JSON

{
    "status": 0,
    "message": "success",
    "data_version": "20250721",
    "result": [
        [
            {
                "adcode": "110000",
                "name": "北京市",
                "level": 1,
                "location": { "lat": 39.911, "lng": 116.405 },
                "address": "北京市"
            },
            {
                "adcode": "110100",
                "name": "北京市",
                "level": 2,
                "location": { "lat": 39.911, "lng": 116.405 },
                "address": "北京市/北京市"
            }
        ]
    ]
}

错误码

错误码	描述
-1	参数错误：keyword 字段缺失或为空
-400	未提供授权信息，请检查 Authorization 请求头
-401	Token 不存在或已过期，请重新获取
-402	关联的团队账号不存在

当请求失败时，接口将返回对应的 result 值（≤ 0）及错误描述字符串。其中 -400 及以下为通用鉴权错误，其余为当前接口特有错误。