Prompt for AI agents
Coding with Claude, ChatGPT, Cursor or Copilot? Copy the prompt, add your task and send it to the agent.
Integrate the BeeGeo geocoding API (free, worldwide, OpenStreetMap). Full reference: https://beegeo.ru/llms.txt - Base URL https://api.beegeo.ru, backup https://api2.beegeo.ru (same keys) — fall back on errors. - Key: ?key= or X-Api-Key header, read from env BEEGEO_API_KEY. - Nominatim-compatible /search, /reverse, /lookup (language: accept-language). Autocomplete: /photon/api (lang only default|en|de|fr|ru). - Limits: 1 req/s per key for Nominatim; respect 429 Retry-After. Show "© OpenStreetMap contributors". My task:
Full reference for agents — /llms.txt.
Quick start
- Get a free key in the dashboard (email or Telegram — the key appears instantly).
- Make your first request:
curl "https://api.beegeo.ru/search?q=Berlin, Unter den Linden 77&format=jsonv2&key=YOUR_KEY"
The response is Nominatim-format JSON: coordinates, address, object type. Try it without a key in the sandbox.
Endpoints and keys
| Endpoint | Purpose |
|---|---|
https://api.beegeo.ru | primary |
https://api2.beegeo.ru | backup: same keys and methods. During maintenance we point it to a mirror — configure it as a fallback |
- Pass the key as the
key=parameter or theX-Api-Keyheader. - HTTPS only. CORS is enabled — you can call it from the browser, but a server-side proxy keeps your key private.
- Up to three active keys per account — one per project.
Coverage: worldwide
The geocoder, autocomplete, Overpass and tiles cover the whole world — the full OpenStreetMap database: every country and territory, cities, streets, buildings, places. Data is updated daily.
Accuracy depends on how well an area is mapped in OpenStreetMap: down to the building in big cities, sometimes only to the street or settlement in rural areas.
Response language
You can get place names and addresses in the language you need. Nominatim and Photon handle it differently:
| Methods | Parameter | Languages |
|---|---|---|
/search, /reverse, /lookup | accept-language (or the Accept-Language HTTP header) | any language the name exists in on OpenStreetMap: en, de, fr, es, it, ru, zh, ja, ar… List several by priority, comma-separated: en,de |
/photon/api, /photon/reverse | lang | only en, de, fr, ru and default (local name). Other values return a 400 error |
If there's no translation, the local name is returned. Example — the same point (Moscow) with different accept-language:
| accept-language | Result |
|---|---|
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=YOUR_KEY" curl "https://api.beegeo.ru/photon/api?q=Moscow&lang=de&limit=3&key=YOUR_KEY"
Without lang, Photon answers in English; pass lang=default to get local names.
/search — address to coordinates
| Parameter | What it does |
|---|---|
q | free-form query: address, city, place, postcode |
street, city, county, state, country, postalcode | structured query instead of q |
format | jsonv2 (recommended), json, geojson, geocodejson |
limit | number of results, up to 40 (default 10) |
countrycodes | only these countries, ISO codes comma-separated: ru,by,kz |
viewbox + bounded=1 | search only inside a box lon1,lat1,lon2,lat2 |
featureType | country | state | city | settlement |
addressdetails=1 | address broken into parts: house, street, city, region, country |
extratags=1 | extra tags: website, phone, opening hours, Wikipedia |
namedetails=1 | the name in all languages |
polygon_geojson=1 | object outline as GeoJSON |
/reverse — coordinates to address
Required: lat, lon. Detail level is set by zoom:
| zoom | Returns |
|---|---|
18 | building |
17 | street |
14 | suburb |
10 | city |
8 | county |
5 | state |
3 | country |
Supports the same format, addressdetails, extratags, namedetails, polygon_geojson, accept-language.
/lookup — objects by OSM ID
osm_ids — up to 50 comma-separated IDs with a type prefix: N — node, W — way, R — relation. Example: osm_ids=N240109189,W5013364.
Photon — search as you type
Fast search for autocomplete: handles partial words and typos, answers in tens of milliseconds. Response is a GeoJSON FeatureCollection.
| Parameter | What it does |
|---|---|
q | query text |
limit | number of suggestions |
lang | default | ru | en | de | fr |
lat + lon | boost results near a point |
layer | house | street | city | district | state | country |
osm_tag | filter by tag: amenity:pharmacy, place:city, !amenity |
bbox | minLon,minLat,maxLon,maxLat |
/photon/reverse — nearest objects to a point: lat, lon, limit, radius (km).
Overpass API
Query any OpenStreetMap objects in Overpass QL. Send the query in the data parameter (GET or POST form) or as a raw POST body.
curl -X POST https://api.beegeo.ru/overpass -H "X-Api-Key: YOUR_KEY" \ --data-urlencode 'data=[out:json][timeout:25];node["amenity"="cafe"](around:500,48.8584,2.2945);out;'
- 1 concurrent request per key, timeout up to 60 seconds.
- Areas:
aroundradius, bounding box,polypolygon. Named-area search (area[name=…]) is not supported yet.
Map tiles
| Path | What it is |
|---|---|
/tiles/{z}/{x}/{y}.png | 256 px raster (Leaflet, OpenLayers) |
/tiles/{z}/{x}/{y}@2x.png | retina |
/tiles/512/{z}/{x}/{y}.png | 512 px raster |
/tiles/vector/{z}/{x}/{y}.pbf | vector tiles (Protomaps schema), zoom up to 15 |
/tiles/style.json | ready MapLibre GL style — your key is already filled into the sources |
Map label language — the lang parameter: ru (default) or en. Works for raster tiles and style.json. In countries with another script, the local name is shown under the English one.
L.tileLayer("https://api.beegeo.ru/tiles/{z}/{x}/{y}.png?key=YOUR_KEY&lang=en", {
maxZoom: 20, attribution: "© OpenStreetMap contributors" }).addTo(map);
new maplibregl.Map({ container: "map", style: "https://api.beegeo.ru/tiles/style.json?key=YOUR_KEY&lang=en" });
Extras
| Parameter | Methods | What it does |
|---|---|---|
timezone=1 | /search, /reverse, /lookup, /photon/* | adds the IANA time zone (e.g. Europe/Berlin) |
layout=0 | /search, /photon/api | disable keyboard-layout correction. By default a query typed in the wrong keyboard layout is fixed: Ищтт → “Bonn”, dkflbrfdrfp → “Владикавказ”. The corrected query is in the X-Layout-Fixed header |
Errors and limits
| Code | When | What to do |
|---|---|---|
401 | no key | add key= or X-Api-Key |
403 | invalid or revoked key | check the key in your dashboard |
429 | per-second limit or daily quota exceeded | wait Retry-After seconds; the quota resets at 00:00 UTC |
503 | server busy (global load peak) | retry in a second (Retry-After) |
502 | server temporarily unavailable | retry against api2.beegeo.ru |
| Service | Rate | Per day per key |
|---|---|---|
| Nominatim | 1 req/s | 50 000 |
| Photon | no hard limit | 500 000 |
| Overpass | 1 concurrent | 2 000 |
| Tiles | 50/s | 1 000 000 |
Not enough for your non-profit project? Write to us — we can double the rate and quotas.
Cache responses on your side and don't scan coordinates on a grid — for bulk extraction download OpenStreetMap dumps.
Code samples
Python
import requests
KEY = "YOUR_KEY"
HOSTS = ["https://api.beegeo.ru", "https://api2.beegeo.ru"] # primary and backup
def geocode(q, lang="en"):
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("Paris, Rue de Rivoli 1"))
JavaScript (browser / Node 18+)
const KEY = "YOUR_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: "en", key: KEY });
const res = await fetch(url);
if (res.ok) return (await res.json()).features;
} catch (e) { /* try the backup */ }
}
return [];
}
PHP
$q = http_build_query(["lat" => 55.7539, "lon" => 37.6208, "format" => "jsonv2",
"accept-language" => "en", "key" => "YOUR_KEY"]);
$data = json_decode(file_get_contents("https://api.beegeo.ru/reverse?" . $q), true);
echo $data["display_name"];
Attribution
Data © OpenStreetMap contributors, ODbL license. If you display or store results, show “© OpenStreetMap contributors” with a link to openstreetmap.org/copyright. More in the terms of use.