all-project/docs/开发文档/逆地理编码功能使用说明.md

逆地理编码功能使用说明

功能概述

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

• 获取用户当前位置的详细地址信息
• 将GPS坐标转换为可读的地址描述
• 支持地址组件的详细解析（省、市、区、街道等）

快速开始

1. 配置高德地图API密钥

在 backend/ruoyi-admin/src/main/resources/application-dev.yml 中配置您的高德地图API密钥：

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

2. 获取高德地图API密钥

1. 访问 高德开放平台
2. 注册并登录账号
3. 创建应用并获取API密钥
4. 将密钥配置到配置文件中

3. 调用API接口

接口信息

• 路径: /system/SysRegion/reverse-geocode
• 方法: POST
• 权限: system:SysRegion:geocode

请求示例

// 前端调用示例
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);
}

响应示例

{
  "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"
      }
    }
  }
}

功能特性

1. 参数验证

• 经度范围：-180.0 到 180.0
• 纬度范围：-90.0 到 90.0
• 自动参数校验和错误提示

2. 详细地址解析

• 格式化地址：完整的地址字符串
• 地址组件：省、市、区、街道等详细信息
• 行政区划代码：标准的行政区划编码
• 城市编码：城市电话区号

3. 错误处理

• 完善的错误码说明
• 详细的错误信息返回
• 异常情况的友好提示

使用场景

1. 移动端定位

// 获取用户当前位置并转换为地址
navigator.geolocation.getCurrentPosition(async (position) => {
  const { longitude, latitude } = position.coords;
  
  const response = await fetch('/system/SysRegion/reverse-geocode', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token
    },
    body: JSON.stringify({ longitude, latitude })
  });
  
  const result = await response.json();
  if (result.code === 200) {
    const address = result.data.regeocode.formattedAddress;
    // 显示用户当前位置
    showUserLocation(address);
  }
});

2. 地图标记点信息

// 为地图标记点获取详细地址信息
async function getMarkerAddress(longitude, latitude) {
  const response = await fetch('/system/SysRegion/reverse-geocode', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token
    },
    body: JSON.stringify({ longitude, latitude })
  });
  
  const result = await response.json();
  if (result.code === 200) {
    const addressComponent = result.data.regeocode.addressComponent;
    return {
      province: addressComponent.province,
      city: addressComponent.city,
      district: addressComponent.district,
      street: addressComponent.street
    };
  }
  return null;
}

3. 地址选择器

// 根据坐标获取地址供用户选择
async function getAddressOptions(longitude, latitude) {
  const response = await fetch('/system/SysRegion/reverse-geocode', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token
    },
    body: JSON.stringify({ longitude, latitude })
  });
  
  const result = await response.json();
  if (result.code === 200) {
    const regeocode = result.data.regeocode;
    return [
      regeocode.formattedAddress,
      `${regeocode.addressComponent.province}${regeocode.addressComponent.city}`,
      `${regeocode.addressComponent.city}${regeocode.addressComponent.district}`,
      regeocode.addressComponent.street
    ];
  }
  return [];
}

测试验证

运行测试脚本

项目提供了完整的测试脚本，可以验证功能是否正常工作：

cd test
python 逆地理编码API测试脚本.py

测试坐标点

测试脚本包含以下坐标点：

• 杭州第一技师学院 (120.1551, 30.2741)
• 西湖 (120.1551, 30.2741)
• 杭州东站 (120.2099, 30.2936)

注意事项

1. API密钥安全

• 请妥善保管高德地图API密钥
• 不要将密钥提交到版本控制系统
• 生产环境使用环境变量管理密钥

2. 请求频率限制

• 高德地图API有请求频率限制
• 建议实现本地缓存机制
• 避免频繁重复请求相同坐标

3. 坐标精度

• 建议使用高精度GPS坐标
• 室内定位可能精度较低
• 考虑坐标漂移问题

4. 网络要求

• 需要能够访问高德地图API服务器
• 建议配置网络超时处理
• 考虑网络异常情况

相关文档

• 逆地理编码API文档
• 高德地图开放平台文档
• 测试脚本

技术支持

如有问题，请参考：

1. 检查API密钥配置是否正确
2. 确认网络连接是否正常
3. 查看服务器日志获取详细错误信息
4. 参考高德地图API官方文档