Documentation

API documentation

Everything you need to integrate the BeeGeo geocoder: endpoints, keys, response languages, every method's parameters, limits and ready-to-use code.

Prompt for AI agents

Coding with Claude, ChatGPT, Cursor or Copilot? Copy the prompt, add your task and send it to the agent.

Prompt
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

  1. Get a free key in the dashboard (email or Telegram — the key appears instantly).
  2. 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

EndpointPurpose
https://api.beegeo.ruprimary
https://api2.beegeo.rubackup: 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 the X-Api-Key header.
  • 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:

MethodsParameterLanguages
/search, /reverse, /lookupaccept-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/reverselangonly 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-languageResult
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=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.

ParameterWhat it does
qfree-form query: address, city, place, postcode
street, city, county, state, country, postalcodestructured query instead of q
formatjsonv2 (recommended), json, geojson, geocodejson
limitnumber of results, up to 40 (default 10)
countrycodesonly these countries, ISO codes comma-separated: ru,by,kz
viewbox + bounded=1search only inside a box lon1,lat1,lon2,lat2
featureTypecountry | state | city | settlement
addressdetails=1address broken into parts: house, street, city, region, country
extratags=1extra tags: website, phone, opening hours, Wikipedia
namedetails=1the name in all languages
polygon_geojson=1object outline as GeoJSON

/reverse — coordinates to address

Required: lat, lon. Detail level is set by zoom:

zoomReturns
18building
17street
14suburb
10city
8county
5state
3country

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.

ParameterWhat it does
qquery text
limitnumber of suggestions
langdefault | ru | en | de | fr
lat + lonboost results near a point
layerhouse | street | city | district | state | country
osm_tagfilter by tag: amenity:pharmacy, place:city, !amenity
bboxminLon,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: around radius, bounding box, poly polygon. Named-area search (area[name=…]) is not supported yet.

Map tiles

PathWhat it is
/tiles/{z}/{x}/{y}.png256 px raster (Leaflet, OpenLayers)
/tiles/{z}/{x}/{y}@2x.pngretina
/tiles/512/{z}/{x}/{y}.png512 px raster
/tiles/vector/{z}/{x}/{y}.pbfvector tiles (Protomaps schema), zoom up to 15
/tiles/style.jsonready 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

ParameterMethodsWhat it does
timezone=1/search, /reverse, /lookup, /photon/*adds the IANA time zone (e.g. Europe/Berlin)
layout=0/search, /photon/apidisable 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

CodeWhenWhat to do
401no keyadd key= or X-Api-Key
403invalid or revoked keycheck the key in your dashboard
429per-second limit or daily quota exceededwait Retry-After seconds; the quota resets at 00:00 UTC
503server busy (global load peak)retry in a second (Retry-After)
502server temporarily unavailableretry against api2.beegeo.ru
ServiceRatePer day per key
Nominatim1 req/s50 000
Photonno hard limit500 000
Overpass1 concurrent2 000
Tiles50/s1 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.