Google Open Location Code项目：Plus Codes API开发指南

Google Open Location Code项目：Plus Codes API开发指南

open-location-code 项目地址: https://gitcode.com/gh_mirrors/ope/open-location-code

概述

Google Open Location Code项目中的Plus Codes API是一个用于地理位置编码与解码的实用工具。它可以将经纬度坐标转换为Plus Code编码，也可以将Plus Code反向解析为地理位置信息。本文将详细介绍该API的功能特点、使用方法及最佳实践。

核心功能

Plus Codes API提供以下主要功能：

1. 坐标转编码：将经纬度坐标转换为Plus Code编码
2. 编码转坐标：将Plus Code编码解析为对应的地理坐标和边界框
3. 地址解析：通过集成Google地理编码API，支持地址与Plus Code的相互转换
4. 短码处理：支持带地名的短码解析（如"WF8Q+WF Praia, Cape Verde"）

API请求格式

基本请求URL格式为：

https://plus.codes/api?parameters

关键参数说明

| 参数 | 是否必需 | 说明 | |------|----------|------| | address | 是 | 可以是经纬度、街道地址、全局编码或本地编码+地名 | | key/ekey | 推荐 | Google API密钥，用于启用高级功能 | | language | 可选 | 返回结果的显示语言，默认为英语 | | email | 推荐 | 开发者联系方式，便于问题沟通 |

注意：URL中的特殊字符（特别是"+"）需要进行编码处理（如将"+"编码为"%2B"）。

响应数据结构

API返回JSON格式数据，主要包含以下字段：

{
  "plus_code": {
    "global_code": "796RWF8Q+WF",
    "geometry": {
      "bounds": {
        "northeast": {"lat": 14.917375, "lng": -23.511250},
        "southwest": {"lat": 14.917250, "lng": -23.511375}
      },
      "location": {"lat": 14.9173125, "lng": -23.5113125}
    },
    "local_code": "WF8Q+WF",
    "locality": {
      "local_address": "Praia, Cape Verde"
    }
  },
  "status": "OK"
}

使用示例

基础用法（无需API密钥）

1. 坐标转编码：

   https://plus.codes/api?address=14.917313,-23.511313
   

2. 编码转坐标：

   https://plus.codes/api?address=796RWF8Q%2BWF
   

高级用法（需API密钥）

1. 带地名的短码解析：

   https://plus.codes/api?address=WF8Q%2BWF%20Praia%20Cape%20Verde&ekey=YOUR_KEY
   

2. 地址解析：

   https://plus.codes/api?address=1600+Amphitheatre+Parkway&ekey=YOUR_KEY
   

API密钥管理

获取Google API密钥

1. 访问Google开发者控制台
2. 创建新项目并启用"Geocoding API"
3. 获取API密钥

密钥安全最佳实践

1. 加密密钥：

   https://plus.codes/api?encryptkey=YOUR_RAW_KEY
   

   返回的加密密钥可用于后续请求中的ekey参数

2. Referrer限制：

   https://plus.codes/api?referer=yourdomain.com&encryptkey=YOUR_RAW_KEY
   

   可限制密钥只能在指定域名下使用

3. 多域名支持：

   https://plus.codes/api?referer=domain1.com|domain2.com&encryptkey=YOUR_RAW_KEY
   

技术细节

1. 精度处理：对于大面积区域（如城市），API会返回能完全包含在该区域内的最大精度编码

2. 版本演进：

   • 2016年12月：v1版本发布
   • 2018年10月：v2版本成为默认，返回与Google Maps相同的地名数据

3. 错误处理：响应中的error_message字段会提供详细的错误信息

开发建议

1. 始终处理status字段，检查请求状态
2. 对于生产环境，务必使用加密密钥并设置referrer限制
3. 考虑实现本地缓存机制，减少API调用次数
4. 注意处理大面积区域的精度问题

通过合理使用Plus Codes API，开发者可以轻松实现地理位置信息的编码与解析功能，为应用程序添加强大的地理定位能力。

open-location-code 项目地址: https://gitcode.com/gh_mirrors/ope/open-location-code