通过一个简单的 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"
    }
  }
}
2,500每天免费请求,每个密钥均享有
€0.0001每次请求的预付额度价格
€50每月 Unlimited 密钥价格
17个兼容替换主机,适配其他服务商的 API
端点

八种查询,一个基础 URL

每个端点都位于 https://api.mygeocode.com/v1/ 之下,接受查询参数,并以相同的外层结构返回 JSON。学会一个,就全都会了。

准确性

每个结果都注明其精度

当您查询门牌号时却返回城市中心的地理编码服务,比直接说找不到该房屋的服务更糟糕。我们返回的每个结果都带有一个 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.MapGeocoder 和 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

REST 兼容替换 JavaScript 兼容替换

任意语言

只要能发送 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"]})"

查看 SDK 计划和各语言的完整示例

密钥是可选的

注册只需一个电子邮件地址

任何地址每天都有 2,500 次免费请求,完全不需要密钥,适用于所有端点和兼容替换主机,从 UTC 00:00 起计算。需要密钥时,一分钟就能拿到:用您的姓名、电子邮件地址和密码注册,您的第一个密钥就会显示在屏幕上。无需公司信息,无需银行卡。每个密钥每天有各自的 2,500 次免费请求,而来自同一网络的无密钥请求共享这一配额,因此账户带来的是额度、套餐和使用记录,而不是第二份免费的 2,500 次。

密钥与使用它们的机器绑定。按量付费密钥在任意滚动的 24 小时内可服务两个 IP 地址,Unlimited 密钥可服务三个。每个地址从其第一次请求起占用名额 24 小时,然后释放。来自更多地址的请求会被拒绝且不计数,正是这一点让泄露的密钥对其他任何人都毫无用处。需要更多地址?创建更多密钥或添加套餐。

  1. 注册,获取密钥

    电子邮件和密码。密钥只显示一次,请复制保存。每天 2,500 次免费请求,最多可从两个 IP 地址使用。

  2. 需要更多时充值额度

    通过银行卡或加密货币充值,最低 €5。超出密钥免费配额的请求,每次从余额中扣除 €0.0001。额度永不过期,也不会自动扣费。

  3. 或者选择 Unlimited 密钥

    每月 €50 即可获得一个不按请求收费的密钥,每个滚动的 24 小时内可从三个 IP 地址使用。您有多少个应用,就可以订购多少个套餐。

价格

免费起步,付费简单

每个端点价格相同。每个兼容替换主机计数方式相同。没有档位,没有按席位收费,没有合同。价格以欧元计,可用银行卡或加密货币支付。

免费密钥

每个密钥每天 2,500 次请求。用您的姓名和电子邮件注册,无需银行卡。数据和端点与付费使用完全相同。

额度

超出密钥每天 2,500 次免费请求后每次请求 €0.0001,从您随时可以充值的余额中扣除。无月费,不过期。一天 10,000 次请求消耗 €0.75 额度。

Unlimited 密钥

每月 €50。一个在所有端点和所有兼容替换主机上都不按请求收费的密钥,每个滚动的 24 小时内最多可从三个 IP 地址使用。

完整价格和计算示例

SDK

官方库,每种语言一个,全部轻量

我们正在为 JavaScript 和 TypeScript、Python、PHP、Go、Java、C#、Ruby 和 Rust 编写小型客户端库。每个库都会为您提供带类型的响应、合理的超时设置、在 429503 时自动重试,仅此而已。某个库就绪后,会连同安装命令一起发布在 SDK 页面上。

关注 SDK 进展

试用需要密钥吗?

不需要。任何地址每天都有 2,500 次请求,无需密钥,无需账户。演示页面无需密钥即可直接从浏览器发送请求。当您需要额度、Unlimited 套餐或使用记录时,一分钟就能获得免费密钥。

第 2,501 次请求时会发生什么?

如果您的账户有额度,请求会正常通过并消耗 €0.0001 额度。如果没有,您会收到 HTTP 402,直到 UTC 00:00 或您充值为止。使用 Unlimited 密钥则不受任何影响。

为什么一个密钥只能用于两个或三个 IP 地址?

密钥是为服务器设计的,这一限制意味着泄露到公开代码仓库的密钥无法被一百台机器使用。每个地址从其第一次请求起占用名额 24 小时,然后释放名额。按量付费密钥有两个名额,Unlimited 密钥有三个。如需更多机器,请创建更多密钥或添加套餐。

我可以存储结果吗?

可以。缓存它们、保存到您的数据库、显示在其他服务商的地图上都可以。条款只要求您不要把原始数据作为您自己的地理编码服务转售。

立即发送您的第一个请求

演示页面使用您的密钥从浏览器发送真实请求,并打开 JSON 响应。获取免费密钥只需要您的姓名、一个电子邮件地址和一分钟时间;当每天 2,500 次不够用时,可以充值额度或添加 Unlimited 密钥。