通过一个简单的 HTTP API 完成地理编码、IP 和时区查询
将地址转换为坐标,也可以反向转换;查出 IPv4 或 IPv6 地址所在的位置;获取任意地点的时区或海拔;解析邮政编码。发送 GET 请求,读取 JSON 即可。无需安装任何东西。
任何地址每天 2,500 次免费请求,无需密钥,无需账户。需要更多?用您的姓名和电子邮件注册,以每次请求 €0.0001 的价格充值预付额度,或以每月 €50 的价格获取 Unlimited 密钥。支持银行卡和加密货币付款。
$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/reverse?lat=48.8584&lon=2.2945"{ "status": "ok", "result": { "formatted": "5 Avenue Anatole France, 75007 Paris, France", "lat": 48.85837, "lon": 2.29448, "distance_m": 12, "precision": "house", "components": { "house_number": "5", "road": "Avenue Anatole France", "city": "Paris", "postcode": "75007", "country": "France", "country_code": "fr" } } }
八种查询,一个基础 URL
每个端点都位于 https://api.mygeocode.com/v1/ 之下,接受查询参数,并以相同的外层结构返回 JSON。学会一个,就全都会了。
正向地理编码 API
GET /v1/forward 端点发送一个地址、地名或大致描述,即可获得坐标、规范化后的地址及其各个组成部分。
详情和示例逆地理编码 API
GET /v1/reverse 端点发送纬度和经度,即可获得最近的地址,并分别列出城市、地区、邮政编码和国家。
详情和示例地址自动补全 API
GET /v1/autocomplete 端点在用户输入时推荐地址。每条建议都附带坐标,因此您很少需要第二次调用。
详情和示例IPv4 查询 API
GET /v1/ipv4 端点任意 IPv4 地址的国家、地区、城市、坐标、时区和网络所有者;如果不提供地址,则返回调用方的信息。
详情和示例IPv6 查询 API
GET /v1/ipv6 端点为 IPv6 地址提供同样的详细信息,另外还包括该地址所属的已宣告前缀。
详情和示例时区查询 API
GET /v1/timezone 端点任意坐标的 IANA 时区名称、UTC 偏移量、夏令时状态和当地时间,可以是当前时间,也可以是您选择的时间戳。
详情和示例海拔查询 API
GET /v1/elevation 端点一个点的海拔高度(以米为单位),或在一次调用中查询最多 100 个点。
详情和示例邮政编码查询 API
GET /v1/postcode 端点将邮政编码转换为地名、地区和坐标。适用于大多数国家的 ZIP 码、邮政编码及其对应形式。
详情和示例每个结果都注明其精度
当您查询门牌号时却返回城市中心的地理编码服务,比直接说找不到该房屋的服务更糟糕。我们返回的每个结果都带有一个 precision 字段,取四个值之一,这样您的代码就可以决定如何处理粗略的匹配,而不必猜测。
覆盖范围并非处处相同,我们宁愿展示给您看,也不愿笼统地宣称。覆盖范围页面列出了我们在 249 个国家和地区中各自能达到的最佳精度级别。
| 级别 | 该点代表什么 |
|---|---|
house | 建筑物或地块本身。该点位于该物业上。 |
street | 街道上的一个位置,根据该街段的门牌号范围插值得出。 |
postcode | 邮政编码区域的中心。 |
admin | 城市、区县、地区或国家的中心,取我们能做到的最具体的匹配。 |
已经在使用其他服务商的 API?更改主机名即可。
我们运行着兼容替换主机,接受与 Google Maps、Bing Maps、HERE、Mapbox、Geocode.Farm、Nominatim 以及另外十一家服务商相同的路径和参数,并以它们的响应格式返回我们的数据。您的解析代码无需改动。把您的 My Geocode 密钥放在原来密钥的位置即可。
$ 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"同样的思路也适用于 JavaScript 库。从 gapi.mygeocode.com 加载 Google Maps JavaScript API,google.maps.Map、Geocoder 和 Places Autocomplete 都能继续工作,而且地图加载不收取任何费用。我们还为 Bing Maps V8 控件、HERE Maps for JavaScript 和 MapQuest.js 提供加载器,并为 MapLibre、Mapbox GL 和 Leaflet 地理编码插件提供配置。
- Google Maps
- Bing Maps
- HERE
- Mapbox
- Geocode.Farm
- Nominatim
- OpenCage
- LocationIQ
- Geoapify
- TomTom
- MapQuest
- Geocodio
- PositionStack
- ip-api
- ipinfo
- ipstack
- Open-Elevation
只要能发送 HTTP 请求,就能使用它
无需 SDK。这些示例对一个地址进行地理编码并打印其坐标。各语言的官方库正在开发中,它们将始终只是对这些相同调用的轻量封装。
$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/forward?q=221B+Baker+Street,+London"
$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/forward?q=221B+Baker+Street,+London"const url = new URL("https://api.mygeocode.com/v1/forward");
url.searchParams.set("q", "221B Baker Street, London");
const res = await fetch(url, { headers: { "X-API-Key": process.env.MYGEOCODE_KEY } });
const data = await res.json();
const [first] = data.results;
console.log(first.lat, first.lon, first.precision);import os
import requests
r = requests.get(
"https://api.mygeocode.com/v1/forward",
params={"q": "221B Baker Street, London"},
headers={"X-API-Key": os.environ["MYGEOCODE_KEY"]},
timeout=10,
)
r.raise_for_status()
first = r.json()["results"][0]
print(first["lat"], first["lon"], first["precision"])<?php
$url = "https://api.mygeocode.com/v1/forward?" . http_build_query([
"q" => "221B Baker Street, London",
]);
$context = stream_context_create(["http" => ["header" => "X-API-Key: " . getenv("MYGEOCODE_KEY")]]);
$data = json_decode(file_get_contents($url, false, $context), true);
$first = $data["results"][0];
echo $first["lat"], ", ", $first["lon"], " (", $first["precision"], ")\n";package main
import (
"encoding/json"
"fmt"
"net/http"
"net/url"
"os"
)
func main() {
q := url.Values{"q": {"221B Baker Street, London"}}
req, _ := http.NewRequest("GET", "https://api.mygeocode.com/v1/forward?"+q.Encode(), nil)
req.Header.Set("X-API-Key", os.Getenv("MYGEOCODE_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var data struct {
Results []struct {
Lat float64 `json:"lat"`
Lon float64 `json:"lon"`
Precision string `json:"precision"`
} `json:"results"`
}
json.NewDecoder(resp.Body).Decode(&data)
fmt.Println(data.Results[0].Lat, data.Results[0].Lon, data.Results[0].Precision)
}import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
public class Geocode {
public static void main(String[] args) throws Exception {
String q = URLEncoder.encode("221B Baker Street, London", StandardCharsets.UTF_8);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.mygeocode.com/v1/forward?q=" + q))
.header("X-API-Key", System.getenv("MYGEOCODE_KEY"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}using System.Net.Http;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("MYGEOCODE_KEY"));
var q = Uri.EscapeDataString("221B Baker Street, London");
var json = await client.GetStringAsync($"https://api.mygeocode.com/v1/forward?q={q}");
using var doc = JsonDocument.Parse(json);
var first = doc.RootElement.GetProperty("results")[0];
Console.WriteLine($"{first.GetProperty("lat")}, {first.GetProperty("lon")} ({first.GetProperty("precision")})");require "net/http"
require "json"
uri = URI("https://api.mygeocode.com/v1/forward")
uri.query = URI.encode_www_form(q: "221B Baker Street, London")
req = Net::HTTP::Get.new(uri)
req["X-API-Key"] = ENV["MYGEOCODE_KEY"]
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
first = JSON.parse(res.body)["results"][0]
puts "#{first["lat"]}, #{first["lon"]} (#{first["precision"]})"注册只需一个电子邮件地址
任何地址每天都有 2,500 次免费请求,完全不需要密钥,适用于所有端点和兼容替换主机,从 UTC 00:00 起计算。需要密钥时,一分钟就能拿到:用您的姓名、电子邮件地址和密码注册,您的第一个密钥就会显示在屏幕上。无需公司信息,无需银行卡。每个密钥每天有各自的 2,500 次免费请求,而来自同一网络的无密钥请求共享这一配额,因此账户带来的是额度、套餐和使用记录,而不是第二份免费的 2,500 次。
密钥与使用它们的机器绑定。按量付费密钥在任意滚动的 24 小时内可服务两个 IP 地址,Unlimited 密钥可服务三个。每个地址从其第一次请求起占用名额 24 小时,然后释放。来自更多地址的请求会被拒绝且不计数,正是这一点让泄露的密钥对其他任何人都毫无用处。需要更多地址?创建更多密钥或添加套餐。
-
注册,获取密钥
电子邮件和密码。密钥只显示一次,请复制保存。每天 2,500 次免费请求,最多可从两个 IP 地址使用。
-
需要更多时充值额度
通过银行卡或加密货币充值,最低 €5。超出密钥免费配额的请求,每次从余额中扣除 €0.0001。额度永不过期,也不会自动扣费。
-
或者选择 Unlimited 密钥
每月 €50 即可获得一个不按请求收费的密钥,每个滚动的 24 小时内可从三个 IP 地址使用。您有多少个应用,就可以订购多少个套餐。
免费起步,付费简单
每个端点价格相同。每个兼容替换主机计数方式相同。没有档位,没有按席位收费,没有合同。价格以欧元计,可用银行卡或加密货币支付。
免费密钥
每个密钥每天 2,500 次请求。用您的姓名和电子邮件注册,无需银行卡。数据和端点与付费使用完全相同。
额度
超出密钥每天 2,500 次免费请求后每次请求 €0.0001,从您随时可以充值的余额中扣除。无月费,不过期。一天 10,000 次请求消耗 €0.75 额度。
Unlimited 密钥
每月 €50。一个在所有端点和所有兼容替换主机上都不按请求收费的密钥,每个滚动的 24 小时内最多可从三个 IP 地址使用。
官方库,每种语言一个,全部轻量
我们正在为 JavaScript 和 TypeScript、Python、PHP、Go、Java、C#、Ruby 和 Rust 编写小型客户端库。每个库都会为您提供带类型的响应、合理的超时设置、在 429 和 503 时自动重试,仅此而已。某个库就绪后,会连同安装命令一起发布在 SDK 页面上。
试用需要密钥吗?
不需要。任何地址每天都有 2,500 次请求,无需密钥,无需账户。演示页面无需密钥即可直接从浏览器发送请求。当您需要额度、Unlimited 套餐或使用记录时,一分钟就能获得免费密钥。
第 2,501 次请求时会发生什么?
如果您的账户有额度,请求会正常通过并消耗 €0.0001 额度。如果没有,您会收到 HTTP 402,直到 UTC 00:00 或您充值为止。使用 Unlimited 密钥则不受任何影响。
为什么一个密钥只能用于两个或三个 IP 地址?
密钥是为服务器设计的,这一限制意味着泄露到公开代码仓库的密钥无法被一百台机器使用。每个地址从其第一次请求起占用名额 24 小时,然后释放名额。按量付费密钥有两个名额,Unlimited 密钥有三个。如需更多机器,请创建更多密钥或添加套餐。
我可以存储结果吗?
可以。缓存它们、保存到您的数据库、显示在其他服务商的地图上都可以。条款只要求您不要把原始数据作为您自己的地理编码服务转售。