Промпт для ИИ-агента
Пишете код с 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.
Быстрый старт
- Получите бесплатный ключ в личном кабинете (почта или Telegram, ключ появляется сразу).
- Сделайте первый запрос:
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, /lookup | accept-language (или HTTP-заголовок Accept-Language) | любой, на котором название есть в OpenStreetMap: ru, en, de, fr, es, it, zh, ja, ar, kk, uk… Можно перечислить через запятую по приоритету: ru,en |
/photon/api, /photon/reverse | lang | только ru, en, de, fr и default (местное название). Другие значения вернут ошибку 400 |
Если перевода нет, возвращается местное название. Пример — одна и та же точка (Москва) с разным accept-language:
| accept-language | Ответ |
|---|---|
ru | Москва |
en | Moscow |
de | Moskau |
es | Moscú |
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, чтобы получить местные названия.
/search — координаты по адресу
| Параметр | Что делает |
|---|---|
q | свободный запрос: адрес, город, место, индекс |
street, city, county, state, country, postalcode | структурный запрос вместо q |
format | jsonv2 (рекомендуем), json, geojson, geocodejson |
limit | сколько результатов, до 40 (по умолчанию 10) |
countrycodes | только эти страны, ISO-коды через запятую: ru,by,kz |
viewbox + bounded=1 | искать только в прямоугольнике lon1,lat1,lon2,lat2 |
featureType | country | 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 | сколько подсказок |
lang | default | ru | en | de | fr |
lat + lon | поднять выше результаты рядом с точкой |
layer | house | street | city | district | state | country |
osm_tag | фильтр по тегу: amenity:pharmacy, place:city, !amenity |
bbox | minLon,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 |
| Сервис | Скорость | В сутки на ключ |
|---|---|---|
| Nominatim | 1 запрос/с | 50 000 |
| Photon | без жёсткого лимита | 500 000 |
| Overpass | 1 одновременно | 2 000 |
| Тайлы | 50/s | 1 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. Подробнее — в условиях использования.