Геокодирование, определение 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"
    }
  }
}
2 500бесплатных запросов в день на каждый ключ
0,0001 €за запрос с предоплаченного баланса
50 €в месяц за ключ Unlimited
17совместимых хостов для API других провайдеров
Эндпоинты

Восемь видов запросов, один базовый 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

Совместимые 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 бесплатных запросов в день вообще без ключа, по всем эндпоинтам и совместимым хостам, с отсчётом от 00:00 UTC. Ключ, когда он вам понадобится, получается за минуту: зарегистрируйтесь, указав имя, адрес электронной почты и пароль, и ваш первый ключ появится на экране. Без компании, без карты. У каждого ключа свои 2 500 бесплатных запросов в день, а запросы без ключа из той же сети делят эту квоту, так что аккаунт добавляет баланс, пакеты и историю использования, а не вторые бесплатные 2 500.

Ключи привязаны к машинам, которые их используют. Ключ с оплатой по мере использования обслуживает два IP-адреса в любом скользящем окне 24 ч, ключ Unlimited три. Каждый адрес занимает свой слот 24 ч с момента первого запроса, а затем освобождает его. Запрос с ещё одного адреса отклоняется и не учитывается, и именно поэтому утёкший ключ бесполезен для посторонних. Нужно больше адресов? Создайте больше ключей или добавьте пакеты.

  1. Зарегистрируйтесь и получите ключ

    Электронная почта и пароль. Ключ показывается один раз, скопируйте его. 2 500 запросов в день бесплатно, максимум с двух IP-адресов.

  2. Пополните баланс, когда нужно больше

    Пополнение от 5 € картой или криптовалютой. Запросы сверх бесплатной квоты ключа списывают с баланса по 0,0001 € за каждый. Баланс не сгорает, и ничего не списывается автоматически.

  3. Или возьмите ключ Unlimited

    За 50 € в месяц вы получаете ключ без платы за запросы, который можно использовать с трёх IP-адресов в скользящем окне 24 ч. Заказывайте столько пакетов, сколько у вас приложений.

Цены

Бесплатно для старта, просто в оплате

Каждый эндпоинт стоит одинаково. Каждый совместимый хост учитывается одинаково. Никаких уровней, никакой платы за рабочие места, никакого договора. Цены в евро, оплата картой или криптовалютой.

Бесплатный ключ

2 500 запросов в день на каждый ключ. Регистрация по имени и адресу электронной почты, без карты. Те же данные и те же эндпоинты, что и при платном использовании.

Баланс

0,0001 € за запрос сверх бесплатных 2 500 ключа в день, списывается с баланса, который вы пополняете когда угодно. Без ежемесячной платы, без срока действия. 10 000 запросов за день расходуют 0,75 € баланса.

Ключ Unlimited

50 € в месяц. Ключ без платы за запросы на всех эндпоинтах и всех совместимых хостах, максимум с трёх IP-адресов в скользящем окне 24 ч.

Все цены и примеры расчётов

SDK

Официальные библиотеки, по одной на язык, все тонкие

Мы пишем небольшие клиентские библиотеки для JavaScript и TypeScript, Python, PHP, Go, Java, C#, Ruby и Rust. Каждая даст типизированные ответы, разумные тайм-ауты, повторы при 429 и 503, и ничего больше. Когда библиотека будет готова, она появится на странице SDK вместе с командой установки.

Следить за ходом работы над SDK

Нужен ли ключ, чтобы попробовать?

Нет. Любой адрес получает 2 500 запросов в день без ключа и без аккаунта. Демо-страница отправляет запросы прямо из браузера без ключа. Бесплатный ключ получается за минуту, когда вам нужны баланс, пакет Unlimited или история использования.

Что происходит с запросом № 2 501?

Если на балансе вашего аккаунта есть средства, запрос проходит и списывает 0,0001 €. Если нет, вы получаете HTTP 402 до 00:00 UTC или до пополнения баланса. На ключе Unlimited ничего не меняется.

Почему ключ ограничен двумя или тремя IP-адресами?

Ключи предназначены для серверов, и это ограничение означает, что ключ, утёкший в публичный репозиторий, нельзя использовать с сотни машин. Каждый адрес занимает свой слот 24 ч с момента первого запроса, затем слот освобождается. У ключа с оплатой по мере использования два слота, у ключа Unlimited три. Для большего числа машин создайте больше ключей или добавьте пакеты.

Можно ли хранить результаты?

Да. Кэшируйте их, сохраняйте в своей базе данных, показывайте на карте другого провайдера. Условия просят лишь не перепродавать исходные данные в виде собственного сервиса геокодирования.

Отправьте первый запрос прямо сейчас

Демо отправляет реальные запросы из вашего браузера с вашим ключом и открывает ответ в JSON. Для бесплатного ключа нужны имя, адрес электронной почты и минута времени; когда 2 500 в день станет мало, пополните баланс или добавьте ключ Unlimited.