cykj/hzdyjs

0 Fork 0

Files

T

zlwu 2c2e4a52b4 提交代码

2025-08-16 23:02:25 +08:00

6.0 KiB

Raw Permalink Blame History

逆地理编码功能使用说明

功能概述

逆地理编码功能提供将经纬度坐标转换为详细地址信息的能力，基于高德地图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密钥

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

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密钥配置是否正确
确认网络连接是否正常
查看服务器日志获取详细错误信息
参考高德地图API官方文档

6.0 KiB Raw Permalink Blame History