Документация

Документация API

Всё, что нужно, чтобы подключить геокодер BeeGeo: адреса, ключи, языки ответов, параметры каждого метода, лимиты и готовые примеры кода.

Промпт для ИИ-агента

Пишете код с Claude, ChatGPT, Cursor или Copilot? Скопируйте промпт, допишите свою задачу и отправьте агенту.

Промпт
Подключи API геокодера BeeGeo (бесплатный, весь мир, OpenStreetMap). Полная справка: https://beegeo.ru/llms.txt
- Адрес https://api.beegeo.ru, резервный https://api2.beegeo.ru (те же ключи) — переключаться при ошибках.
- Ключ: ?key= или заголовок X-Api-Key, брать из переменной BEEGEO_API_KEY.
- Как Nominatim: /search, /reverse, /lookup (язык — accept-language). Подсказки: /photon/api (lang только default|ru|en|de|fr).
- Лимит Nominatim 1 запрос/с на ключ, при 429 ждать Retry-After. Показывать «© участники OpenStreetMap».

Моя задача: 

Подробная справка для агентов — /llms.txt.

Быстрый старт

  1. Получите бесплатный ключ в личном кабинете (почта или Telegram, ключ появляется сразу).
  2. Сделайте первый запрос:
curl "https://api.beegeo.ru/search?q=Москва, Тверская 7&format=jsonv2&key=ВАШ_КЛЮЧ"

Ответ — JSON в формате Nominatim: координаты, адрес, тип объекта. Попробовать без ключа можно в песочнице.

Адреса и ключ

АдресНазначение
https://api.beegeo.ruосновной
https://api2.beegeo.ruрезервный: те же ключи и методы. На время работ переключаем его на зеркало — пропишите как запасной
  • Ключ передаётся параметром key= или заголовком X-Api-Key.
  • Только HTTPS. CORS разрешён — можно вызывать из браузера, но лучше через свой сервер, чтобы не светить ключ.
  • До трёх активных ключей на аккаунт, по одному на проект.

Покрытие: весь мир

Геокодер, подсказки, Overpass и тайлы работают по всему миру — это полная база OpenStreetMap: все страны и территории, города, улицы, дома, объекты. Данные обновляются ежедневно.

Точность зависит от того, насколько подробно место нанесено в OpenStreetMap: в крупных городах — до дома и подъезда, в сельской местности иногда до улицы или населённого пункта.

Язык ответов

Названия объектов и адреса можно получить на нужном языке. Для Nominatim и Photon это делается по-разному:

МетодыПараметрЯзыки
/search, /reverse, /lookupaccept-language (или HTTP-заголовок Accept-Language)любой, на котором название есть в OpenStreetMap: ru, en, de, fr, es, it, zh, ja, ar, kk, uk… Можно перечислить через запятую по приоритету: ru,en
/photon/api, /photon/reverselangтолько ru, en, de, fr и default (местное название). Другие значения вернут ошибку 400

Если перевода нет, возвращается местное название. Пример — одна и та же точка (Москва) с разным accept-language:

accept-languageОтвет
ruМосква
enMoscow
deMoskau
esMoscú
zh莫斯科
jaモスクワ
kkМәскеу
curl "https://api.beegeo.ru/reverse?lat=55.7539&lon=37.6208&zoom=10&format=jsonv2&accept-language=es&key=ВАШ_КЛЮЧ"
curl "https://api.beegeo.ru/photon/api?q=Moscow&lang=de&limit=3&key=ВАШ_КЛЮЧ"

Без lang Photon отвечает на английском; передайте lang=default, чтобы получить местные названия.

ПараметрЧто делает
qсвободный запрос: адрес, город, место, индекс
street, city, county, state, country, postalcodeструктурный запрос вместо q
formatjsonv2 (рекомендуем), json, geojson, geocodejson
limitсколько результатов, до 40 (по умолчанию 10)
countrycodesтолько эти страны, ISO-коды через запятую: ru,by,kz
viewbox + bounded=1искать только в прямоугольнике lon1,lat1,lon2,lat2
featureTypecountry | state | city | settlement
addressdetails=1адрес по частям: дом, улица, город, регион, страна
extratags=1доп. теги: сайт, телефон, часы работы, Википедия
namedetails=1название на всех языках
polygon_geojson=1границы объекта в GeoJSON

/reverse — адрес по координатам

Обязательные lat, lon. Детализацию задаёт zoom:

zoomЧто вернётся
18дом
17улица
14район
10город
8округ / область
5регион
3страна

Поддерживает те же format, addressdetails, extratags, namedetails, polygon_geojson, accept-language.

/lookup — объекты по OSM ID

osm_ids — до 50 ID через запятую с префиксом типа: N — точка, W — линия/здание, R — отношение. Пример: osm_ids=N240109189,W5013364.

Photon — подсказки при вводе

Быстрый поиск для автодополнения: понимает начало слова и опечатки, отвечает за десятки миллисекунд. Ответ — GeoJSON FeatureCollection.

ПараметрЧто делает
qтекст запроса
limitсколько подсказок
langdefault | ru | en | de | fr
lat + lonподнять выше результаты рядом с точкой
layerhouse | street | city | district | state | country
osm_tagфильтр по тегу: amenity:pharmacy, place:city, !amenity
bboxminLon,minLat,maxLon,maxLat

/photon/reverse — ближайшие объекты к точке: lat, lon, limit, radius (км).

Overpass API

Выборки любых объектов OpenStreetMap на языке Overpass QL. Запрос — в параметре data (GET или POST-форма), либо сырым телом POST.

curl -X POST https://api.beegeo.ru/overpass -H "X-Api-Key: ВАШ_КЛЮЧ" \
  --data-urlencode 'data=[out:json][timeout:25];node["amenity"="cafe"](around:500,55.7539,37.6208);out;'
  • 1 одновременный запрос на ключ, тайм-аут до 60 секунд.
  • Области: радиус around, прямоугольник, полигон poly. Поиск по именованной области (area[name=…]) пока не поддерживается.

Тайлы карты

ПутьЧто это
/tiles/{z}/{x}/{y}.pngрастр 256 px (Leaflet, OpenLayers)
/tiles/{z}/{x}/{y}@2x.pngретина
/tiles/512/{z}/{x}/{y}.pngрастр 512 px
/tiles/vector/{z}/{x}/{y}.pbfвекторные тайлы (схема Protomaps), зум до 15
/tiles/style.jsonготовый стиль MapLibre GL — ключ уже подставлен в источники

Язык подписей на карте — параметр lang: ru (по умолчанию) или en. Работает для растровых тайлов и style.json. В странах с другим алфавитом под английским названием показывается местное.

L.tileLayer("https://api.beegeo.ru/tiles/{z}/{x}/{y}.png?key=ВАШ_КЛЮЧ", {
  maxZoom: 20, attribution: "© OpenStreetMap contributors" }).addTo(map);

new maplibregl.Map({ container: "map", style: "https://api.beegeo.ru/tiles/style.json?key=ВАШ_КЛЮЧ" });

Наши дополнения

ПараметрМетодыЧто делает
timezone=1/search, /reverse, /lookup, /photon/*добавляет часовой пояс IANA (например Europe/Moscow)
layout=0/search, /photon/apiотключить исправление раскладки. По умолчанию запрос, набранный не в той раскладке, исправляется: dkflbrfdrfp → «Владикавказ», Ищтт → «Bonn». Исправленный запрос — в заголовке X-Layout-Fixed

Ошибки и лимиты

КодКогдаЧто делать
401нет ключадобавьте key= или X-Api-Key
403ключ неверный или отозванпроверьте ключ в кабинете
429превышен лимит в секунду или суточная квотаподождите Retry-After секунд; квота сбрасывается в 00:00 UTC
503сервер занят (общий пик нагрузки)повторите через секунду (Retry-After)
502сервер временно недоступенповторите запрос на api2.beegeo.ru
СервисСкоростьВ сутки на ключ
Nominatim1 запрос/с50 000
Photonбез жёсткого лимита500 000
Overpass1 одновременно2 000
Тайлы50/s1 000 000

Некоммерческому проекту не хватает лимитов? Напишите нам — можем удвоить скорость и квоты.

Кэшируйте ответы на своей стороне и не перебирайте координаты по сетке — для массовой выгрузки скачайте дампы OpenStreetMap.

Примеры кода

Python

import requests

KEY = "ВАШ_КЛЮЧ"
HOSTS = ["https://api.beegeo.ru", "https://api2.beegeo.ru"]  # основной и резервный

def geocode(q, lang="ru"):
    for host in HOSTS:
        try:
            r = requests.get(f"{host}/search", timeout=10, params={
                "q": q, "format": "jsonv2", "limit": 1, "accept-language": lang, "key": KEY})
            r.raise_for_status()
            return r.json()
        except requests.RequestException:
            continue
    raise RuntimeError("geocoder unavailable")

print(geocode("Казань, Баумана 1"))

JavaScript (браузер / Node 18+)

const KEY = "ВАШ_КЛЮЧ";
async function suggest(q) {
  for (const host of ["https://api.beegeo.ru", "https://api2.beegeo.ru"]) {
    try {
      const url = new URL(host + "/photon/api");
      url.search = new URLSearchParams({ q, limit: 5, lang: "ru", key: KEY });
      const res = await fetch(url);
      if (res.ok) return (await res.json()).features;
    } catch (e) { /* пробуем резервный */ }
  }
  return [];
}

PHP

$q = http_build_query(["lat" => 55.7539, "lon" => 37.6208, "format" => "jsonv2",
                       "accept-language" => "ru", "key" => "ВАШ_КЛЮЧ"]);
$data = json_decode(file_get_contents("https://api.beegeo.ru/reverse?" . $q), true);
echo $data["display_name"];

Атрибуция

Данные — © участники OpenStreetMap, лицензия ODbL. Если показываете или храните результаты, укажите рядом «© участники OpenStreetMap» со ссылкой на openstreetmap.org/copyright. Подробнее — в условиях использования.