# BeeGeo — free worldwide geocoding API > Free geocoding API on OpenStreetMap data: forward and reverse geocoding (Nominatim-compatible), address autocomplete (Photon), Overpass API and map tiles. Worldwide coverage, updated daily. Free API key. - [Documentation (EN)](https://beegeo.ru/en/docs/) - [Документация (RU)](https://beegeo.ru/docs/) - [Get a free API key](https://beegeo.ru/en/account/) - [Service status](https://beegeo.ru/en/status/) ## Integration guide for AI agents You are helping me integrate the BeeGeo geocoding API — a free, worldwide geocoder built on OpenStreetMap. Use these facts: ENDPOINTS AND AUTH - Base URL: https://api.beegeo.ru ; backup: https://api2.beegeo.ru (same keys and methods). Implement automatic fallback to the backup on network errors and HTTP 5xx. - Auth: query parameter key= or header X-Api-Key: . Read the key from the environment variable BEEGEO_API_KEY; keep it server-side. GEOCODING (Nominatim-compatible, JSON) - GET /search?q=&format=jsonv2&limit=&addressdetails=1 — address/place → coordinates. Structured alternative: street, city, county, state, country, postalcode. Filters: countrycodes=gb,de ; viewbox=lon1,lat1,lon2,lat2&bounded=1 ; featureType=country|state|city|settlement. Extras: extratags=1, namedetails=1, polygon_geojson=1. - GET /reverse?lat=&lon=&zoom=<3..18>&format=jsonv2 — coordinates → address (18 building, 17 street, 14 suburb, 10 city, 8 county, 5 state, 3 country). - GET /lookup?osm_ids=N123,W456,R789&format=jsonv2 — up to 50 OSM objects. - Response language: accept-language= (any language present in OpenStreetMap; comma-separated priority list, e.g. "de,en"). AUTOCOMPLETE (Photon, GeoJSON FeatureCollection) - GET /photon/api?q=&limit=&lang= — ONLY these lang values; others return HTTP 400. Without lang the answer is English; lang=default gives local names. - Optional: lat & lon (boost results near a point), layer=house|street|city|district|state|country, osm_tag=key:value, bbox=minLon,minLat,maxLon,maxLat. - GET /photon/reverse?lat=&lon=&limit=&radius=. - Use Photon (not /search) for search-as-you-type; debounce input by 150–250 ms. OVERPASS - POST /overpass with form field data= (or raw QL body). 1 concurrent request per key, timeout up to 60 s. Named areas (area[name=...]) are not supported — use around:, bbox or poly:. MAP TILES - Raster: /tiles/{z}/{x}/{y}.png?key=&lang= (also @2x.png and /tiles/512/{z}/{x}/{y}.png). - Vector: /tiles/vector/{z}/{x}/{y}.pbf (zoom ≤ 15). MapLibre GL style: /tiles/style.json?key=&lang=. EXTRAS - timezone=1 adds the IANA time zone to /search, /reverse, /lookup and Photon results. - Wrong keyboard layout is fixed automatically for /search and /photon/api (corrected query in the X-Layout-Fixed response header); disable with layout=0. LIMITS AND ERRORS - Per key: Nominatim 1 request/s, Overpass 1 concurrent, tiles 50/s. Daily quotas: Nominatim 50,000; Photon 500,000; Overpass 2,000; tiles 1,000,000 (reset at 00:00 UTC). - 401 = missing key, 403 = invalid/revoked key, 429 = rate limit or daily quota (respect Retry-After), 502 = retry on api2.beegeo.ru. - Cache results on your side; never bulk-scrape or grid-scan. ATTRIBUTION (required) - Show "© OpenStreetMap contributors" linking to https://www.openstreetmap.org/copyright wherever results or tiles are displayed. Docs: https://beegeo.ru/en/docs/ — free key: https://beegeo.ru/en/account/