# 逆地理编码API文档

## 概述

逆地理编码API提供将经纬度坐标转换为详细地址信息的功能，基于高德地图API实现。

## 接口信息

- **接口路径**: `/system/SysRegion/reverse-geocode`
- **请求方法**: `POST`
- **权限要求**: `system:SysRegion:geocode`
- **数据格式**: `application/json`

## 请求参数

### 请求体参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| longitude | Double | 是 | - | 经度，范围：-180.0 到 180.0 |
| latitude | Double | 是 | - | 纬度，范围：-90.0 到 90.0 |
| output | String | 否 | "json" | 返回格式，目前仅支持json |
| batch | Integer | 否 | 1 | 批量查询控制 |
| roadlevel | Integer | 否 | 0 | 道路等级 |

### 请求示例

```json
{
  "longitude": 120.1551,
  "latitude": 30.2741,
  "output": "json",
  "batch": 1,
  "roadlevel": 0
}
```

## 响应参数

### 响应结构

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "status": "1",
    "info": "OK",
    "infocode": "10000",
    "regeocode": {
      "formattedAddress": "浙江省杭州市西湖区文三路",
      "addressComponent": {
        "country": "中国",
        "province": "浙江省",
        "city": "杭州市",
        "district": "西湖区",
        "township": "文三街道",
        "street": "文三路",
        "number": "123号",
        "adcode": "330106",
        "citycode": "0571"
      },
      "pois": [],
      "roads": [],
      "roadIntersections": [],
      "aois": []
    }
  }
}
```

### 响应字段说明

#### 顶层字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| status | String | 状态码，"1"表示成功 |
| info | String | 状态信息 |
| infocode | String | 信息码 |
| regeocode | Object | 逆地理编码结果 |

#### regeocode字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| formattedAddress | String | 格式化地址 |
| addressComponent | Object | 地址组件 |
| pois | Array | 兴趣点信息 |
| roads | Array | 道路信息 |
| roadIntersections | Array | 道路交叉口信息 |
| aois | Array | 兴趣区域信息 |

#### addressComponent字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| country | String | 国家 |
| province | String | 省份 |
| city | String | 城市 |
| district | String | 区县 |
| township | String | 乡镇 |
| street | String | 街道 |
| number | String | 门牌号 |
| adcode | String | 行政区划代码 |
| citycode | String | 城市编码 |

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 10000 | 请求正常 |
| 10001 | key不正确或过期 |
| 10002 | 请求超出配额 |
| 10003 | 请求过于频繁 |
| 10004 | 请求参数错误 |
| 10005 | 请求IP白名单校验失败 |
| 10006 | 请求签名校验失败 |
| 10007 | 请求IP不在白名单中 |
| 10008 | 请求不在白名单中 |
| 10009 | 请求IP不在白名单中 |
| 10010 | 请求IP不在白名单中 |
| 10011 | 请求IP不在白名单中 |
| 10012 | 请求IP不在白名单中 |
| 10013 | 请求IP不在白名单中 |
| 10014 | 请求IP不在白名单中 |
| 10015 | 请求IP不在白名单中 |
| 10016 | 请求IP不在白名单中 |
| 10017 | 请求IP不在白名单中 |
| 10018 | 请求IP不在白名单中 |
| 10019 | 请求IP不在白名单中 |
| 10020 | 请求IP不在白名单中 |

## 使用示例

### JavaScript示例

```javascript
// 发送逆地理编码请求
const response = await fetch('/system/SysRegion/reverse-geocode', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token,
    'clientid': 'e5cd7e4891bf95d1d19206ce24a7b32e'
  },
  body: JSON.stringify({
    longitude: 120.1551,
    latitude: 30.2741
  })
});

const result = await response.json();
if (result.code === 200) {
  const address = result.data.regeocode.formattedAddress;
  console.log('地址:', address);
}
```

### Python示例

```python
import requests

# 发送逆地理编码请求
response = requests.post(
    'http://localhost:8080/system/SysRegion/reverse-geocode',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + token,
        'clientid': 'e5cd7e4891bf95d1d19206ce24a7b32e'
    },
    json={
        'longitude': 120.1551,
        'latitude': 30.2741
    }
)

result = response.json()
if result['code'] == 200:
    address = result['data']['regeocode']['formattedAddress']
    print('地址:', address)
```

## 配置说明

### 高德地图配置

在 `application-dev.yml` 中配置高德地图API密钥：

```yaml
# 高德地图配置
amap:
  # 高德地图API密钥（请替换为您的实际密钥）
  key: your_amap_key_here
  # 高德地图API基础URL
  url: https://restapi.amap.com
```

### 获取高德地图API密钥

1. 访问 [高德开放平台](https://lbs.amap.com/)
2. 注册并登录账号
3. 创建应用并获取API密钥
4. 将密钥配置到 `application-dev.yml` 中

## 注意事项

1. **API密钥安全**: 请妥善保管高德地图API密钥，不要泄露给他人
2. **请求频率限制**: 高德地图API有请求频率限制，请合理控制请求频率
3. **坐标精度**: 建议使用高精度GPS坐标以获得更准确的地址信息
4. **网络要求**: 需要能够访问高德地图API服务器
5. **权限配置**: 确保用户具有 `system:SysRegion:geocode` 权限

## 相关文件

- 控制器: `SysRegionController.java`
- 服务接口: `IAmapService.java`
- 服务实现: `AmapServiceImpl.java`
- 请求BO: `GeocodingRequestBo.java`
- 响应VO: `GeocodingResponseVo.java`
- 测试脚本: `test/逆地理编码API测试脚本.py`

## 更新日志

- 2025-01-03: 初始版本，实现基础逆地理编码功能