Геокодирование, определение IP и часовых поясов через один простой HTTP API
Превращайте адреса в координаты и обратно, узнавайте, где находится IPv4- или IPv6-адрес, получайте часовой пояс или высоту любой точки и определяйте почтовые индексы. Отправьте GET-запрос, прочитайте JSON. Ничего не нужно устанавливать.
2 500 бесплатных запросов в день с любого адреса, без ключа и без аккаунта. Нужно больше? Зарегистрируйтесь, указав имя и адрес электронной почты, пополните предоплаченный баланс по 0,0001 € за запрос или возьмите ключ Unlimited за 50 € в месяц. Принимаем карты и криптовалюту.
$ 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Подсказывайте адреса, пока пользователь печатает. Каждая подсказка приходит с координатами, так что второй вызов нужен редко.
Подробности и примерыAPI определения IPv4
Эндпоинт GET /v1/ipv4Страна, регион, город, координаты, часовой пояс и владелец сети для любого IPv4-адреса или для вызывающей стороны, если адрес не указан.
Подробности и примерыAPI определения IPv6
Эндпоинт 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-библиотек. Загрузите Google Maps JavaScript API с gapi.mygeocode.com, и 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 бесплатных запросов в день вообще без ключа, по всем эндпоинтам и совместимым хостам, с отсчётом от 00:00 UTC. Ключ, когда он вам понадобится, получается за минуту: зарегистрируйтесь, указав имя, адрес электронной почты и пароль, и ваш первый ключ появится на экране. Без компании, без карты. У каждого ключа свои 2 500 бесплатных запросов в день, а запросы без ключа из той же сети делят эту квоту, так что аккаунт добавляет баланс, пакеты и историю использования, а не вторые бесплатные 2 500.
Ключи привязаны к машинам, которые их используют. Ключ с оплатой по мере использования обслуживает два IP-адреса в любом скользящем окне 24 ч, ключ Unlimited три. Каждый адрес занимает свой слот 24 ч с момента первого запроса, а затем освобождает его. Запрос с ещё одного адреса отклоняется и не учитывается, и именно поэтому утёкший ключ бесполезен для посторонних. Нужно больше адресов? Создайте больше ключей или добавьте пакеты.
-
Зарегистрируйтесь и получите ключ
Электронная почта и пароль. Ключ показывается один раз, скопируйте его. 2 500 запросов в день бесплатно, максимум с двух IP-адресов.
-
Пополните баланс, когда нужно больше
Пополнение от 5 € картой или криптовалютой. Запросы сверх бесплатной квоты ключа списывают с баланса по 0,0001 € за каждый. Баланс не сгорает, и ничего не списывается автоматически.
-
Или возьмите ключ Unlimited
За 50 € в месяц вы получаете ключ без платы за запросы, который можно использовать с трёх IP-адресов в скользящем окне 24 ч. Заказывайте столько пакетов, сколько у вас приложений.
Бесплатно для старта, просто в оплате
Каждый эндпоинт стоит одинаково. Каждый совместимый хост учитывается одинаково. Никаких уровней, никакой платы за рабочие места, никакого договора. Цены в евро, оплата картой или криптовалютой.
Бесплатный ключ
2 500 запросов в день на каждый ключ. Регистрация по имени и адресу электронной почты, без карты. Те же данные и те же эндпоинты, что и при платном использовании.
Баланс
0,0001 € за запрос сверх бесплатных 2 500 ключа в день, списывается с баланса, который вы пополняете когда угодно. Без ежемесячной платы, без срока действия. 10 000 запросов за день расходуют 0,75 € баланса.
Ключ Unlimited
50 € в месяц. Ключ без платы за запросы на всех эндпоинтах и всех совместимых хостах, максимум с трёх IP-адресов в скользящем окне 24 ч.
Официальные библиотеки, по одной на язык, все тонкие
Мы пишем небольшие клиентские библиотеки для JavaScript и TypeScript, Python, PHP, Go, Java, C#, Ruby и Rust. Каждая даст типизированные ответы, разумные тайм-ауты, повторы при 429 и 503, и ничего больше. Когда библиотека будет готова, она появится на странице SDK вместе с командой установки.
Нужен ли ключ, чтобы попробовать?
Нет. Любой адрес получает 2 500 запросов в день без ключа и без аккаунта. Демо-страница отправляет запросы прямо из браузера без ключа. Бесплатный ключ получается за минуту, когда вам нужны баланс, пакет Unlimited или история использования.
Что происходит с запросом № 2 501?
Если на балансе вашего аккаунта есть средства, запрос проходит и списывает 0,0001 €. Если нет, вы получаете HTTP 402 до 00:00 UTC или до пополнения баланса. На ключе Unlimited ничего не меняется.
Почему ключ ограничен двумя или тремя IP-адресами?
Ключи предназначены для серверов, и это ограничение означает, что ключ, утёкший в публичный репозиторий, нельзя использовать с сотни машин. Каждый адрес занимает свой слот 24 ч с момента первого запроса, затем слот освобождается. У ключа с оплатой по мере использования два слота, у ключа Unlimited три. Для большего числа машин создайте больше ключей или добавьте пакеты.
Можно ли хранить результаты?
Да. Кэшируйте их, сохраняйте в своей базе данных, показывайте на карте другого провайдера. Условия просят лишь не перепродавать исходные данные в виде собственного сервиса геокодирования.
Отправьте первый запрос прямо сейчас
Демо отправляет реальные запросы из вашего браузера с вашим ключом и открывает ответ в JSON. Для бесплатного ключа нужны имя, адрес электронной почты и минута времени; когда 2 500 в день станет мало, пополните баланс или добавьте ключ Unlimited.