My Geocode

兼容替换

您无需学习这个 API 就能使用它。针对其他十七个地理编码和 IP 查询 API，我们各运行一个主机，接受该服务商的请求格式并以该服务商的响应格式作答，背后是我们的数据。这些服务商提供的 JavaScript 地图库也同样适用。迁移只需更改主机名。

工作原理

每个兼容替换主机都完整实现了一家服务商的公开 HTTP 接口：相同的路径、相同的查询参数、相同的 JSON 字段名、嵌套结构和类型、相同的状态词汇以及相同的错误结构。数值来自我们。您的客户端代码、解析代码和错误处理都无需改动。

  1. 更改主机。 maps.googleapis.com 改为 gapi.mygeocode.com，dev.virtualearth.net 改为 bing.mygeocode.com，依此类推。下表列出了所有对应关系。
  2. 替换密钥，或者去掉它。把您的 My Geocode 密钥放在原密钥所用的参数中（key、apiKey、access_token、token……）。任何地址无需密钥每天即可获得 2,500 个免费请求，每个密钥还自带 2,500 个，因此迁移和测试不花一分钱。
  3. 对比。用一批真实请求样本同时请求两个主机。由于数据不同，坐标会略有差异；字段名则不会。
之前
$ curl "https://maps.googleapis.com/maps/api/geocode/json?address=10+Downing+St+London&key=GOOGLE_KEY"
之后
$ curl "https://gapi.mygeocode.com/maps/api/geocode/json?address=10+Downing+St+London&key=MYGEOCODE_KEY"

所有兼容替换主机

每个主机都与 api.mygeocode.com 运行在相同的基础设施上，使用相同的数据、相同的免费配额和相同的价格。点击某个服务商可查看其端点列表、示例响应和已知差异。

服务商和查询类型原始主机兼容替换主机密钥参数
Google Maps Platform
正向、逆向、自动补全、时区、海拔		maps.googleapis.comgapi.mygeocode.comkey
Bing Maps REST Services
正向、逆向、自动补全、时区、海拔		dev.virtualearth.netbing.mygeocode.comkey
HERE Geocoding and Search
正向、逆向、自动补全		geocode.search.hereapi.com
revgeocode.search.hereapi.com
autosuggest.search.hereapi.com
autocomplete.search.hereapi.com		here.mygeocode.comapiKey
Mapbox Geocoding
正向、逆向、自动补全		api.mapbox.commapbox.mygeocode.comaccess_token
Geocode.Farm
正向、逆向		api.geocode.farm
www.geocode.farm		farm.mygeocode.comkey
OpenStreetMap Nominatim
正向、逆向		nominatim.openstreetmap.orgosm.mygeocode.com无；添加 key 或请求头
OpenCage
正向、逆向		api.opencagedata.comopencage.mygeocode.comkey
LocationIQ
正向、逆向、自动补全、时区		us1.locationiq.com
eu1.locationiq.com		locationiq.mygeocode.comkey
Geoapify
正向、逆向、自动补全、IP 查询		api.geoapify.comgeoapify.mygeocode.comapiKey
TomTom Search
正向、逆向、自动补全		api.tomtom.comtomtom.mygeocode.comkey
MapQuest Geocoding
正向、逆向		www.mapquestapi.com
open.mapquestapi.com		mapquest.mygeocode.comkey
Geocodio
正向、逆向		api.geocod.iogeocodio.mygeocode.comapi_key
PositionStack
正向、逆向		api.positionstack.compositionstack.mygeocode.comaccess_key
ip-api.com
IP 查询		ip-api.com
pro.ip-api.com		ipapi.mygeocode.comkey
ipinfo.io
IP 查询		ipinfo.ioipinfo.mygeocode.comtoken
ipstack
IP 查询		api.ipstack.comipstack.mygeocode.comaccess_key
Open-Elevation
Elevation		api.open-elevation.comopenelevation.mygeocode.com无；添加 key 或请求头

JavaScript 地图库

更换服务商最麻烦的地方在浏览器端，那里地图、地理编码组件和计费纠缠在一起。对于下列库，库本身从我们的主机加载（对于 MapLibre、Mapbox GL 和 Leaflet，则通过配置指向我们的主机），并保留其公开 API：google.maps.Map、Microsoft.Maps.Map、H.Map 等。瓦片、地理编码、自动补全和海拔数据都来自我们。地图加载和瓦片免费；地理编码调用照常计数。

库原加载地址改为从此加载继续可用的功能
Google Maps JavaScript API 地图库maps.googleapis.comgapi.mygeocode.com使用我们瓦片的 google.maps.Map（roadmap、satellite 和 terrain 地图类型）
Bing Maps V8 Web Control 地图控件www.bing.combing.mygeocode.comMicrosoft.Maps.Map、Location、LocationRect、Pushpin、Infobox、Polyline、Polygon 和 Layer
Mapbox GL JS 和 mapbox-gl-geocodermapbox.mygeocode.com矢量瓦片样式：streets、light、dark 和 outdoors，遵循 Mapbox 样式规范
Leaflet 地理编码插件tile.openstreetmap.orgtiles.mygeocode.comLeaflet Control Geocoder：nominatim、google、bing、mapbox、here、opencage、latLng 和 mapquest 地理编码器，各自指向对应的 www.mygeocode.com 主机
HERE Maps API for JavaScript 地图库js.api.here.comhere.mygeocode.comH.Map, H.map.Marker, H.map.Polyline, H.map.Polygon, H.map.Group
MapQuest.jsapi.mqcdn.commapquest.mygeocode.comL.mapquest.map 和 tileLayer（map、hybrid、satellite、light、dark）

JavaScript 兼容替换页面提供了修改前后的代码片段、每个库包含和不包含的功能列表，以及瓦片和样式 URL。

密钥放在哪里

每个主机都在原服务商期望的位置接受密钥，同时也接受 X-API-Key 请求头。密钥是可选的：每个地址每天 2,500 个请求无需密钥。免费密钥一分钟即可获取，并带来额度、套餐和使用记录。按量付费密钥在每滚动 24 小时内可从两个 IP 地址使用，Unlimited 密钥可从三个 IP 地址使用；如需更多地址，请使用更多密钥或套餐（请参阅身份验证）。

参数使用者
keyGoogle Maps、Bing Maps、Geocode.Farm、OpenCage、LocationIQ、TomTom、MapQuest、ip-api（pro）
apiKeyHERE、Geoapify
access_tokenMapbox
api_keyGeocodio
access_keyPositionStack、ipstack
token 或 Authorization: Beareripinfo、HERE
无Nominatim、Open-Elevation。在查询中添加 key=... 或发送 X-API-Key 请求头。

兼容替换主机上的配额和错误

每日配额与其他地方相同，按密钥计算，未发送密钥时则按地址计算，涵盖 api.mygeocode.com 和所有兼容替换主机：每天免费 2,500 个，之后使用额度或 Unlimited 密钥。所有主机都会发送 X-Quota-* 和 X-Key-IPs-* 响应头，因此无论响应正文是什么格式，您都可以从响应头读取真实状态。在响应正文中，限制按服务商自己的方式报告：

主机额度用尽（402）密钥错误、缺失或受 IP 限制无效请求
gapi.mygeocode.comHTTP 200，"status": "OVER_QUERY_LIMIT""status": "REQUEST_DENIED""status": "INVALID_REQUEST"
bing.mygeocode.com响应结构中的 "statusCode": 429"statusCode": 401, authenticationResultCode: InvalidCredentials"statusCode": 400，附带 errorDetails
here.mygeocode.comHTTP 429，{"title": "Too Many Requests", "status": 429}HTTP 401，附带 error_descriptionHTTP 400，附带 title 和 cause
mapbox.mygeocode.comHTTP 429，{"message": "Rate limit exceeded"}HTTP 401，{"message": "Not Authorized - Invalid Token"}HTTP 422，附带 message
osm.mygeocode.comHTTP 429，{"error": {"code": 429, "message": "..."}}不适用HTTP 400，{"error": {"code": 400, "message": "..."}}
ipapi.mygeocode.comHTTP 200，{"status": "fail", "message": "quota"}{"status": "fail", "message": "invalid key"}{"status": "fail", "message": "invalid query"}
其他与服务商文档一致；请参阅各主机的页面

哪些一致，哪些不一致

完全一致

  • 服务商文档中记载的路径、方法和查询参数。
  • 响应结构：字段名、嵌套、数组、类型、坐标顺序（包括 Mapbox 的 [lon, lat]）。
  • 状态和置信度词汇（ROOFTOP、High、houseNumber、EXACT_MATCH……），由我们的 precision 和 confidence 映射而来。
  • 错误结构，因此现有的错误处理可以继续使用。
  • 价格和配额：使用兼容替换主机不额外收费。

不同之处

  • 数据。坐标、格式化字符串和置信度数值来自我们，不会与原服务商逐位一致。门牌级覆盖范围因国家而异；请参阅覆盖范围。
  • 标识符。地点 ID 由我们生成且保持稳定，但不能发送给原服务商。
  • 地理编码、自动补全、IP、时区和海拔以外的任何功能：路线规划、地点详情、照片、交通、街景。各主机的页面列出了缺少的功能。
  • 密钥：按量付费密钥每滚动 24 小时可用于两个 IP 地址，Unlimited 密钥可用于三个，与我们自己的端点相同。

迁移清单

  1. 在您的代码和配置中搜索该服务商的主机名。它往往出现在不止一个地方：服务器代码、移动应用、CDN 规则、缓存的配置。
  2. 将其改为上表中的兼容替换主机。路径保持不变。
  3. 将密钥替换为 My Geocode 密钥。每台服务器使用一个密钥，最多两台共用一个；按量付费密钥每滚动 24 小时接受两个 IP 地址，Unlimited 密钥接受三个。
  4. 运行您现有的测试套件。它应该无需修改即可通过。如果您依赖的某个字段缺失，请查看该主机页面上的已知差异，并告诉我们。
  5. 用几百个真实请求同时请求两个主机，比较坐标以及您展示的字段。在兼容替换主机提供的地方查看 precision（表现为 location_type、accuracy、resultType 等）。
  6. 观察 X-Quota-Used 一天，以确定您的方案：每天少于约 19,000 个请求时使用额度，高于此数时使用 Unlimited 密钥。
  7. 取消原来的计费。

服务商 SDK

大多数官方客户端库都支持自定义基础 URL，因此它们也能与兼容替换主机配合使用：Google Maps Services 客户端（Python 的 googlemaps、@googlemaps/google-maps-services-js）、Mapbox SDK（origin 选项）、HERE 的 REST 客户端、ipinfo 的库，以及 geopy 等 Nominatim 封装库（domain=）。将它们指向表中的主机，并在原服务商密钥的位置传入您的 My Geocode 密钥。

未列出的服务商

如果服务商的格式有文档记载，添加一个主机只需几天的工作。如果您使用的服务不在此列，请告诉我们是哪一家，以及您每天大约发送多少请求。最近新增的主机全都来自用户的请求。