# 迈云位置服务（LTS）AI 接入指南

> 本文档专为 AI 编码助手（Claude Code、Cursor、GitHub Copilot、ChatGPT、通义灵码等）优化。
> 将本文档地址交给 AI，即可获得接入「迈云位置服务」所需的全部关键信息：鉴权方式、接口清单、请求参数、响应结构与错误码。
>
> 官网：https://lts.maiyun.net ｜ 接口文档：https://lts.maiyun.net/docs ｜ 控制台：https://lts.maiyun.net/portal

---

## 一、服务简介

迈云位置服务（LTS）提供高精度位置 API，覆盖坐标转换、正逆地址解析、POI 搜索、距离计算、行政区划、IP 定位、融合定位与天气查询等能力。所有接口仅覆盖中国大陆地区，统一使用 JSON 数据格式。

### 接口总览

| 接口 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| 坐标转换 | POST | `/api/service/geoconv` | 多坐标系（WGS84/BD09/BD09MC）转 GCJ02 |
| 正地址解析 | POST | `/api/service/geocoding` | 文字地址转经纬度坐标 |
| 逆地址解析 | POST | `/api/service/geocode` | 坐标转详细地址与行政区划 |
| 历史地址标准化 | POST | `/api/service/division` | 将 2005 年以来可明确识别的历史行政区划名称转换为当前名称 |
| POI 简易搜索 | POST | `/api/service/search` | 按关键词快速搜索地点 |
| 标准 POI 搜索 | POST | `/api/service/placesearch` | 城市/行政区限定的专业 POI 搜索 |
| 周边 POI 搜索 | POST | `/api/service/nearbysearch` | 按中心点与半径检索附近地点 |
| 距离计算 | POST | `/api/service/distance` | 多个坐标点对直线距离 |
| 天气查询 | POST | `/api/service/weather` | 按城市行政区划编码查询实时天气或天气预报 |
| 行政区列表 | GET | `/api/service/scenario/list` | 全国四级行政区划列表 |
| 下级行政区 | POST | `/api/service/scenario/children` | 按上级 adcode 查直属下级 |
| 行政区搜索 | POST | `/api/service/scenario/search` | 按名称或 adcode 模糊搜索 |
| IP 定位 | POST | `/api/service/ip` | IP 归属地查询 |
| 融合定位 | POST | `/api/service/location` | 基站 + Wi-Fi 信号定位 |

---

## 二、快速开始

### 1. 获取 API Key

1. 打开控制台 https://lts.maiyun.net/portal 注册账号。
2. 进入「密钥管理」，创建 API Key。
3. 新注册账号自带免费测试额度，可直接开始调用。

### 2. 发起第一个请求

以「正地址解析」为例，将一段中文地址转换为经纬度坐标：

```bash
curl -X POST https://lts.maiyun.net/api/service/geocoding \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"北京市昌平区龙泽龙域北街3号院1号"}'
```

```javascript
fetch('https://lts.maiyun.net/api/service/geocoding', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        address: '北京市昌平区龙泽龙域北街3号院1号',
    }),
})
    .then(r => r.json())
    .then(data => {
        console.log(data.lat, data.lng); // 40.067784 116.313784
    });
```

### 3. 判断调用是否成功

- 普通接口：响应 JSON 中 `result === 1` 表示成功。
- 行政区划接口（`scenario/*`）：响应 JSON 中 `status === 0` 表示成功。
- 失败时：普通接口的 `result !== 1`，行政区划接口的 `status !== 0`；普通接口的错误描述在 `msg` 字段，行政区划接口在 `message` 字段。

---

## 三、基础约定

### Base URL

```
https://lts.maiyun.net
```

所有业务接口的完整地址为 `https://lts.maiyun.net/api/service/...`。

### 鉴权方式

除「历史地址标准化」外，在请求头中携带 Bearer Token：

```
Authorization: Bearer <API_KEY>
```

「历史地址标准化」支持游客调用，无需携带 API Key；游客请求受 IP 频率限制。携带有效 API Key 调用时，按所在团队的 QPS 与通用额度执行。

### 请求格式

- POST 接口：`Content-Type: application/json`，请求体为 JSON 对象。
- 坐标相关接口默认输入 GCJ02 坐标，如需 WGS84 / BD09 输入，通过 `from` 参数指定。

### 坐标系说明

| 值 | 坐标系 | 说明 |
| --- | --- | --- |
| 0 | WGS84 | GPS 原始坐标 |
| 1 | BD09（BD09LL） | 百度经纬度坐标系 |
| 2 | BD09MC | 百度墨卡托坐标系 |
| 3 | GCJ02 | 国测局火星坐标系（服务默认） |

---

## 四、统一响应与错误码

### 通用错误码

| 错误码 | 含义 | 处理建议 |
| --- | --- | --- |
| `-1` ~ `-8` | 接口专属的参数或业务错误 | 按各接口错误描述处理 |
| `-10` | 额度不足 | 前往控制台充值或升级套餐 |
| `-400` | 未提供授权信息 | 检查是否携带 Authorization 请求头 |
| `-401` | Token 不存在或已过期 | 重新创建或检查 API Key |
| `-402` | 关联的团队账号不存在 | 联系商务 |
| `-429` | 超出 QPS 限制 | 降低请求频率，或升级套餐提升 QPS |
| `-21` ~ `-24` | 扣减服务异常 | 稍后重试；持续出现时联系技术支持 |

---

## 五、接口详情

### 5.1 坐标转换 `POST /api/service/geoconv`

将 WGS84 / BD09 / BD09MC 坐标批量转换为 GCJ02 坐标。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `from` | integer | 是 | 源坐标系：0=WGS84，1=BD09，2=BD09MC |
| `points` | array | 是 | 坐标点列表，每项 `{ lat: number, lng: number }` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `list` | array | 转换后的坐标列表，与请求顺序对应，每项含 `lng`、`lat` |

**请求示例**

```json
{
    "from": 0,
    "points": [{ "lat": 39.961317, "lng": 116.336145 }]
}
```

**响应示例**

```json
{
    "result": 1,
    "list": [{ "lng": 116.342304, "lat": 39.962646 }]
}
```

**错误码**：`-1` from 错误；`-2` points 错误；`-3` points 超过 10 个；`-10/-400/-401/-402/-429` 见通用错误码。

---

### 5.2 正地址解析 `POST /api/service/geocoding`

将文字地址解析为 GCJ02 经纬度坐标，仅支持中国大陆地区。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `address` | string | 是 | 待解析地址，支持省市区街道门牌等粒度，如「北京市昌平区龙泽龙域北街3号院1号」 |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `lat` | number | 纬度，GCJ02，精确到小数点后 6 位 |
| `lng` | number | 经度，GCJ02，精确到小数点后 6 位 |
| `address.name` | string | 标准化后的地址字符串 |
| `address.context` | array | 行政区划上下文，每项含 `type`（province/city/district/township）、`name`、`code` |

**响应示例**

```json
{
    "result": 1,
    "lat": 40.067784,
    "lng": 116.313784,
    "address": {
        "name": "北京市昌平区回龙观街道昌平龙泽龙域北街3号院1号",
        "context": [
            { "type": "province", "name": "北京市", "code": "110000" },
            { "type": "city", "name": "北京市", "code": "110100" },
            { "type": "district", "name": "昌平区", "code": "110114" },
            { "type": "township", "name": "回龙观街道", "code": "110114011" }
        ]
    }
}
```

**错误码**：`-1` address 参数错误；`-3` 地址解析服务暂不可用；`-4` 地址无法解析。

---

### 5.3 逆地址解析 `POST /api/service/geocode`

根据坐标返回详细地址与行政区划信息。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `from` | integer | 是 | 输入坐标系：0=WGS84，1=BD09，2=BD09MC，3=GCJ02 |
| `point` | object | 是 | 查询点坐标 `{ lat: number, lng: number }` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `name` | string | 格式化后的完整地址字符串 |
| `point` | object | 标准化后的 GCJ02 坐标，含 `lng`、`lat` |
| `address.name` | string | 完整地址 |
| `address.context` | object | 行政区划：`country`、`province`、`city`、`district`、`township`，每项 `{ name, code }` |

**响应示例**

```json
{
    "result": 1,
    "name": "市南区**定位点",
    "point": {
        "lng": 120.387783,
        "lat": 36.067109
    },
    "address": {
        "name": "山东省青岛市市南区香港中路街道徐州路新贵都",
        "context": {
            "country": { "name": "中国", "code": "CN" },
            "province": { "name": "山东省", "code": "370000" },
            "city": { "name": "青岛市", "code": "370200" },
            "district": { "name": "市南区", "code": "370202" },
            "township": { "name": "香港中路街道", "code": "370202001" }
        }
    }
}
```

**错误码**：`-1` from 错误；`-2` point 缺失；`-4` point 坐标错误；`-5` 服务暂不可用；`-6` 未找到地址。

---

### 5.4 POI 简易搜索 `POST /api/service/search`

按地址或关键词快速搜索地点，适合轻量级场景。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `address` | string | 是 | 搜索地址或关键词，如「威海 水饺」 |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `list` | array | POI 列表，每项含 `id`、`point`（GCJ02 坐标）、`type`、`name`、`code`（地点编码）、`categories`（分类列表）、`address`、`relevance`（相关度）、`distance`（米）、`phone` |

**响应示例**

```json
{
    "result": 1,
    "list": [
        {
            "id": "2a9c1c0d49800c0d7c29bdde",
            "point": { "lng": 122.123891, "lat": 37.505005 },
            "type": "Entity",
            "name": "威海**特色水饺",
            "code": "",
            "categories": [{ "id": "100100", "name": "餐饮服务" }],
            "address": {
                "name": "山东省威海市环翠区鲸园街道威高广场负一楼食尚地美食广场",
                "context": {
                    "country": { "name": "中国", "code": "CN" },
                    "province": { "name": "山东省", "code": "370000" },
                    "city": { "name": "威海市", "code": "371000" },
                    "district": { "name": "环翠区", "code": "371002" },
                    "township": { "name": "鲸园街道", "code": "371002001" }
                }
            },
            "relevance": 166.73686,
            "distance": 0,
            "phone": ""
        }
    ]
}
```

**错误码**：`-1` address 参数错误；`-3` 服务暂不可用；`-4` 未找到匹配地点。

---

### 5.5 标准 POI 搜索 `POST /api/service/placesearch`

在指定城市或行政区内精确搜索 POI，支持分页。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 地点名称，支持模糊搜索 |
| `city` | string | 否 | 城市名称或 adcode，与 `code` 二选一 |
| `code` | string | 否 | 行政区编码，与 `city` 二选一 |
| `page` | integer | 否 | 页码，从 1 开始，默认 1 |
| `count` | integer | 否 | 每页数量，可选 5/10/20，默认 20 |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `list` | array | POI 列表，每项含 `id`、`point`、`type`、`name`、`code`（地点编码）、`categories`、`address`、`relevance`、`distance`、`phone`（数组） |

**响应示例**

```json
{
    "result": 1,
    "list": [
        {
            "id": "e943c4e7490fea2a6c4760f2",
            "point": { "lng": 104.096249, "lat": 30.551096 },
            "type": "Entity",
            "name": "**民宿(**地铁站店)",
            "code": "",
            "categories": [{ "id": "100000", "name": "住宿服务" }],
            "address": {
                "name": "四川省成都市双流区中和街道中和大道三段香榭宸光里1栋",
                "context": {
                    "country": { "name": "中国", "code": "CN" },
                    "province": { "name": "四川省", "code": "510000" },
                    "city": { "name": "成都市", "code": "510100" },
                    "district": { "name": "双流区", "code": "510116" },
                    "township": { "name": "中和街道", "code": "510116010" }
                }
            },
            "relevance": 283.14478,
            "distance": 500,
            "phone": ["187****2901"]
        }
    ]
}
```

**错误码**：`-1` name 错误；`-2` city 类型错误；`-3` code 类型错误；`-4` 未提供 city/code 或 page 类型错误；`-5` count 仅支持 5/10/20；`-6` 城市名称或编码不正确。

---

### 5.6 周边 POI 搜索 `POST /api/service/nearbysearch`

以指定坐标为中心，按半径检索附近地点，支持关键词与分类过滤。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `from` | integer | 否 | 输入坐标系，默认 3（GCJ02）：0=WGS84，1=BD09，2=BD09MC，3=GCJ02 |
| `point` | object | 是 | 中心点坐标 `{ lat, lng }` |
| `radius` | integer | 是 | 搜索半径，单位米 |
| `name` | string | 否 | 地点关键词过滤 |
| `category` | string | 否 | 地点分类过滤 |
| `page` | integer | 否 | 页码，默认 1 |
| `count` | integer | 否 | 每页数量，可选 5/10/20，默认 20 |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `list` | array | POI 列表，每项含 `id`、`point`、`type`、`name`、`code`（地点编码）、`categories`、`address`、`relevance`、`distance`（与中心点距离，米）、`phone` |

**响应示例**

```json
{
    "result": 1,
    "list": [
        {
            "id": "e943c4e7490fea2a6c4760f2",
            "point": { "lng": 104.096249, "lat": 30.551096 },
            "type": "Entity",
            "name": "**民宿(**地铁站店)",
            "code": "",
            "categories": [{ "id": "100000", "name": "住宿服务" }],
            "address": {
                "name": "四川省成都市双流区中和街道中和大道三段香榭宸光里1栋",
                "context": {
                    "country": { "name": "中国", "code": "CN" },
                    "province": { "name": "四川省", "code": "510000" },
                    "city": { "name": "成都市", "code": "510100" },
                    "district": { "name": "双流区", "code": "510116" },
                    "township": { "name": "中和街道", "code": "510116010" }
                }
            },
            "relevance": 283.14478,
            "distance": 500,
            "phone": ["187****2901"]
        }
    ]
}
```

**错误码**：`-1` from/point 错误；`-2` radius 错误；`-3` name 类型错误；`-4` category 类型错误；`-5` page 类型错误；`-6` count 必须为 5/10/20。

---

### 5.7 距离计算 `POST /api/service/distance`

计算多个坐标点对之间的直线距离。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `points` | array | 是 | 坐标点对数组，每项为二维数组 `[[from_lat, from_lng], [to_lat, to_lng]]` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `list` | array | 各点对直线距离列表，单位米 |

**响应示例**

```json
{ "result": 1, "list": [12839.3, 151.01, 463450.4] }
```

**错误码**：`-1` points 参数错误；`-2` points 超过 10 个。

---

### 5.8 天气查询 `POST /api/service/weather`

按城市行政区划编码查询实时天气或天气预报。`extensions` 传 `base` 获取实时天气，传 `all` 获取天气预报。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `city` | integer | 是 | 城市行政区划编码，如北京市为 `110000` |
| `extensions` | string | 是 | 查询类型：`base`=实时天气，`all`=天气预报 |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `lives` | array | 实时天气列表，元素含省市名称、行政区划编码、天气现象、气温、风向、风力、湿度和发布时间 |
| `forecasts` | array | 天气预报列表，元素含省市名称、行政区划编码、预报发布时间和逐日预报 `casts` |

**请求示例**

```json
{
    "city": 110000,
    "extensions": "base"
}
```

**响应示例**

```json
{
    "result": 1,
    "lives": [
        {
            "province": "北京",
            "city": "北京市",
            "adcode": "110000",
            "weather": "晴",
            "temperature": "20",
            "winddirection": "北",
            "windpower": "≤3",
            "humidity": "38",
            "reporttime": "2026-08-08 14:00:00"
        }
    ],
    "forecasts": []
}
```

**错误码**：`-1` city 参数错误；`-2` extensions 仅支持 base 或 all；`-3` 天气服务暂不可用。

---

### 5.9 历史地址标准化 `POST /api/service/division`

将中国大陆完整地址开头的历史行政区划名称标准化为当前名称，适用于清洗历史订单、客户资料和地址库。数据覆盖 2005 年以来可明确识别的行政区划变更。

支持省地县、省县、地县及直辖市区县等常见层级组合。系统只处理地址开头的行政区划，详细地址不会被替换；拆分归属无法确定时保留原地址。

本接口支持游客调用，无需 API Key；游客请求受 IP 频率限制。携带有效 API Key 时按团队 QPS 与通用额度执行。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `address` | string | 是 | 待标准化的完整地址，如「山东省临沂市苍山县卞庄街道文峰路」 |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `address` | string | 标准化后的地址；没有可明确转换的区划或归属无法判断时，返回原地址 |

**请求示例**

```json
{
    "address": "山东省临沂市苍山县卞庄街道文峰路"
}
```

**响应示例**

```json
{
    "result": 1,
    "address": "山东省临沂市兰陵县卞庄街道文峰路"
}
```

**错误码**：`-1` address 字段缺失或不是字符串；`-10` 携带 API Key 调用时额度不足；`-429` 请求频率超限。

---

### 5.10 行政区列表 `GET /api/service/scenario/list`

获取全国四级行政区划列表（省、市、区县、乡镇）。

**请求参数**：无。

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `status` | integer | 状态码，0 为成功 |
| `message` | string | 返回信息 |
| `data_version` | string | 数据版本号，如 `20250721` |
| `result` | array | 行政区列表，每项含 `adcode`、`province`、`level`（1=省，2=市，3=区县，4=乡镇）、`location`（中心坐标 `{lat, lng}`）、`city`（level≥2）、`district`（level≥3） |

**响应示例**

```json
{
    "status": 0,
    "message": "success",
    "data_version": "20250721",
    "result": [
        {
            "adcode": "110000",
            "province": "北京市",
            "level": 1,
            "location": { "lat": 39.911, "lng": 116.405 }
        },
        {
            "adcode": "110100",
            "province": "北京市",
            "city": "北京市",
            "level": 2,
            "location": { "lat": 39.911, "lng": 116.405 }
        },
        {
            "adcode": "110101",
            "province": "北京市",
            "city": "北京市",
            "district": "东城区",
            "level": 3,
            "location": { "lat": 39.917, "lng": 116.418 }
        }
    ]
}
```

**错误码**：`-2` 行政区划服务暂不可用；`-10` 额度不足；`-400/-401/-402/-429` 见通用错误码。

---

### 5.11 下级行政区 `POST /api/service/scenario/children`

按上级 adcode 查询直属下级行政区，可选返回边界坐标。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `parent` | string | 否 | 上级行政区 adcode，不传返回省级列表 |
| `polygon` | boolean | 否 | 是否返回边界坐标，默认 false |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `status` | integer | 状态码，0 为成功 |
| `message` | string | 返回信息 |
| `data_version` | string | 数据版本号，如 `20250721` |
| `result` | array | 下级行政区列表，每项含 `adcode`、`province`、`city`、`district`、`level`、`location`；`polygon=true` 时含 `polygon`（边界坐标点数组，每项 `[lng, lat]`） |

**响应示例**

```json
{
    "status": 0,
    "message": "success",
    "data_version": "20250721",
    "result": [
        {
            "adcode": "110101",
            "province": "北京市",
            "city": "北京市",
            "district": "东城区",
            "level": 3,
            "location": { "lat": 39.917, "lng": 116.418 },
            "polygon": [
                [116.3621, 39.9443],
                [116.4283, 39.9443],
                [116.4283, 39.8899],
                [116.3621, 39.8899]
            ]
        }
    ]
}
```

**错误码**：`-1` parent 类型错误；`-2` polygon 类型错误；`-4` 行政区划服务暂不可用；`-10` 额度不足；`-400/-401/-402/-429` 见通用错误码。

---

### 5.12 行政区搜索 `POST /api/service/scenario/search`

按名称或 adcode 模糊搜索行政区。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `keyword` | string | 是 | 搜索关键词，支持名称或 adcode |
| `polygon` | boolean | 否 | 是否返回边界坐标，默认 false |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `status` | integer | 状态码，0 为成功 |
| `message` | string | 返回信息 |
| `data_version` | string | 数据版本号，如 `20250721` |
| `result` | array | 匹配结果列表，每项为该行政区的完整层级路径数组，层级项含 `adcode`、`name`、`level`、`location`、`address`（完整路径如「北京市/北京市/东城区」）、`polygon`（可选） |

**响应示例**

```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 缺失或为空；`-2` polygon 类型错误；`-4` 行政区划服务暂不可用；`-10` 额度不足；`-400/-401/-402/-429` 见通用错误码。

---

### 5.13 IP 定位 `POST /api/service/ip`

根据 IP 地址返回归属省市与运营商所在城市中心坐标。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `ip` | string | 是 | 目标 IP 地址（IPv4 或 IPv6） |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `country` | string | 国家名称 |
| `province` | string | 省份名称 |
| `city` | string | 城市名称 |
| `district` | string | 区县名称 |
| `point` | object | 城市中心坐标（GCJ02），含 `lng`、`lat` |

**请求示例**

```json
{
    "ip": "222.211.237.85"
}
```

**响应示例**

```json
{
    "result": 1,
    "country": "中国",
    "province": "四川省",
    "city": "成都市",
    "district": "双流区",
    "point": { "lng": 103.92342, "lat": 30.574884 }
}
```

**错误码**：`-1` ip 字段缺失或不是字符串；`-4` IP 定位服务暂不可用；`-5` IP 无法解析。

---

### 5.14 融合定位 `POST /api/service/location`

综合利用基站与 Wi-Fi 热点信号定位，适合 GPS 信号弱的室内场景。`cellulars` 与 `wifis` 至少提供一项。

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `from` | integer | 是 | 返回坐标系：0=WGS84，1=BD09，3=GCJ02 |
| `time` | integer | 是 | 当前时间戳（毫秒） |
| `asset` | string | 是 | 设备唯一标识编号 |
| `cellulars` | array | 否 | 基站列表，每项含 `cell`（Cell ID）、`primary`（是否主基站）、`asu`（信号强度，与 dbm 至少填 1 个）、`dbm`（信号功率，单位 dBm）、`country`（MCC 码）、`network`（MNC 码）、`area`（区域码，范围 0-65535） |
| `wifis` | array | 否 | Wi-Fi 热点列表，每项含 `mac`（MAC 地址，Beacon 广播帧公开信息）、`signal`（信号强度 dBm） |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | integer | 成功标识，1 为成功 |
| `name` | string | 地点名称 |
| `point` | object | 融合后坐标，含 `lng`、`lat`、`source`（fusion/wifi/cell/gnss）、`accuracy`（精度，米） |
| `address` | object | 地址信息，含 `name` 与 `context`（country/province/city/district/township） |

**请求示例**

```json
{
    "from": 3,
    "time": 1768535120038,
    "asset": "byabc",
    "cellulars": [
        {
            "cell": 132605532,
            "primary": false,
            "asu": 80,
            "dbm": -113,
            "country": 460,
            "network": 0,
            "area": 12321
        }
    ],
    "wifis": [
        { "mac": "9E:2B:A6:86:2A:0E", "signal": -74 },
        { "mac": "54:52:84:86:03:A8", "signal": -79 },
        { "mac": "EE:60:73:AF:AD:0C", "signal": -81 },
        { "mac": "50:64:2B:94:A4:7F", "signal": -87 },
        { "mac": "D8:15:0D:FE:5C:09", "signal": -90 }
    ]
}
```

**响应示例**

```json
{
    "result": 1,
    "name": "代码示例位置",
    "point": { "lng": 117.334369, "lat": 39.116094, "source": "fusion", "accuracy": 300 },
    "address": {
        "name": "天津市东丽区万新街道平盈路8号服务8100室",
        "context": {
            "country": { "name": "中国", "code": "CN" },
            "province": { "name": "天津市", "code": "120000" },
            "city": { "name": "天津市", "code": "120100" },
            "district": { "name": "东丽区", "code": "120110" },
            "township": { "name": "万新街道", "code": "120110006" }
        }
    }
}
```

**错误码**：`-1` from 错误；`-2` time 错误；`-3` asset 错误；`-4` cellulars 格式错误；`-5` wifis 格式错误；`-6` 未提供 cellulars 与 wifis；`-7` 基站信号缺少 asu/dbm 或定位服务暂不可用；`-8` 未找到位置。

---

## 六、配额与限流

- 新注册账号自带免费测试额度，可在控制台查看剩余额度。
- 接口按套餐计费，套餐包含每日调用次数与 QPS 上限，超出后返回 `-429`。
- 「标准 POI 搜索」与「周边 POI 搜索」按 POI 搜索额度单独计费，其余接口按通用额度计费。
- 额度与套餐详情见定价页：https://lts.maiyun.net/pricing

---

## 七、安全建议

- **API Key 是敏感凭证**：禁止硬编码在前端代码或提交到公开仓库。
- 应用服务端通过环境变量读取 API Key，并由服务端发起 API 请求。
- 为每个业务或环境创建独立 Key，便于独立限流与审计。

---

## 八、更多资源

- 完整接口文档：https://lts.maiyun.net/docs
- 5 分钟快速入门：https://lts.maiyun.net/guide
- 定价方案：https://lts.maiyun.net/pricing
- 控制台（注册 / 密钥 / 用量）：https://lts.maiyun.net/portal