# Geocoding API
> Forward & reverse geocoding and OSM object lookup powered by OpenStreetMap: turn addresses/places into coordinates, coordinates into addresses, and look up OSM objects by id.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/geocoding-api/..."
```

## Pricing
- **Free** (Free) — 100 calls/Mo, 1 req/s
- **Basic** ($15/Mo) — 25,000 calls/Mo, 10 req/s
- **Pro** ($49/Mo) — 100,000 calls/Mo, 20 req/s
- **Mega** ($149/Mo) — 500,000 calls/Mo, 50 req/s

## Endpoints

### Geocoding

#### `GET /v1/reverse` — Reverse geocoding (coordinates → address)

**Parameters:**
- `lat` (query, required, string) — Latitude Example: `52.5163`
- `lon` (query, required, string) — Longitude Example: `13.3777`
- `zoom` (query, optional, string) — Detail level 0-18 Example: `18`
- `lang` (query, optional, string) — Result language Example: `en`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/geocoding-api/v1/reverse?lat=52.5163&lon=13.3777&zoom=18&lang=en"
```

**Response:**
```json
{
    "data": {
        "lat": 52.5163,
        "lon": 13.3777,
        "place": {
            "lat": 52.51627,
            "lon": 13.3777021,
            "name": "Quadriga with Victoria",
            "type": "artwork",
            "osm_id": 3786417057,
            "address": {
                "city": "Berlin",
                "road": "Platz des 18. März",
                "suburb": "Mitte",
                "borough": "Mitte",
                "country": "Germany",
                "quarter": "Friedrich-Wilhelm-Stadt",
                "tourism": "Quadriga with Victoria",
                "postcode": "10117",
                "country_code": "de",
                "ISO3166-2-lvl4": "DE-BE"
            },
            "category": "tourism",
            "osm_type": "node",
            "place_id": 145366925,
            "importance": 8.875486381318407e-5,
            "place_rank": 30,
            "addresstype": "tourism",
            "boundingbox": [
                52.51622,
                52.51632,
                13.3776521,
                13.3777521
            ],
            "display_name": "Quadriga with Victoria, Platz des 18. März, Friedrich-Wilhelm-Stadt, Mitte, Berlin, 10117, Germany"
        }
    },
    "meta": {
        "timestamp": "2026-05-29T20:06:48.772Z",
        "request_id": "f36f1f46-fa26-4b1c-a0ee-545ddcaec5ae"
    },
    "status": "ok",
    "message": "Reverse geocoding retrieved successfully",
    "success": true
}
```

#### `GET /v1/search` — Forward geocoding (address → coordinates)

**Parameters:**
- `q` (query, required, string) — Address or place name Example: `Brandenburg Gate Berlin`
- `limit` (query, optional, string) — Max results (1-40) Example: `10`
- `countrycodes` (query, optional, string) — Comma-separated ISO country codes Example: `de`
- `lang` (query, optional, string) — Result language Example: `en`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/geocoding-api/v1/search?q=Brandenburg+Gate+Berlin&limit=10&countrycodes=de&lang=en"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "query": "Brandenburg Gate Berlin",
        "results": [
            {
                "lat": 52.5162699,
                "lon": 13.3777034,
                "name": "Brandenburg Gate",
                "type": "attraction",
                "osm_id": 518071791,
                "address": {
                    "city": "Berlin",
                    "road": "Pariser Platz",
                    "suburb": "Mitte",
                    "borough": "Mitte",
                    "country": "Germany",
                    "quarter": "Friedrich-Wilhelm-Stadt",
                    "tourism": "Brandenburg Gate",
                    "postcode": "10117",
                    "country_code": "de",
                    "house_number": "1",
                    "ISO3166-2-lvl4": "DE-BE"
                },
                "category": "tourism",
                "osm_type": "way",
                "place_id": 145792549,
                "importance": 0.5504719991549523,
                "place_rank": 30,
                "addresstype": "tourism",
                "boundingbox": [
                    52.516117,
                    52.5164328,
                    13.3775798,
                    13.3778251
                ],
                "display_name": "Brandenburg Gate, 1, Pariser Platz, Friedrich-Wilhelm-Stadt, Mitte, Berlin, 10117, Germany"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-29T20:06:49.401Z",
        "request_id": "6743b5
…(truncated, see openapi.json for full schema)
```

### Lookup

#### `GET /v1/lookup` — Look up OSM objects by id

**Parameters:**
- `osm_ids` (query, required, string) — Comma-separated OSM ids (N/W/R) Example: `R62422,N240109189`
- `lang` (query, optional, string) — Result language Example: `en`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/geocoding-api/v1/lookup?osm_ids=R62422%2CN240109189&lang=en"
```

**Response:**
```json
{
    "data": {
        "count": 2,
        "results": [
            {
                "lat": 52.5173885,
                "lon": 13.3951309,
                "name": "Berlin",
                "type": "administrative",
                "osm_id": 62422,
                "address": {
                    "city": "Berlin",
                    "country": "Germany",
                    "country_code": "de",
                    "ISO3166-2-lvl4": "DE-BE"
                },
                "category": "boundary",
                "osm_type": "relation",
                "place_id": 144602669,
                "importance": 0.8522196536088086,
                "place_rank": 7,
                "addresstype": "city",
                "boundingbox": [
                    52.3382448,
                    52.6755087,
                    13.088345,
                    13.7611609
                ],
                "display_name": "Berlin, Germany"
            },
            {
                "lat": 52.5173885,
                "lon": 13.3951309,
                "name": "Berlin",
                "type": "city",
                "osm_id": 240109189,
                "address": {
                    "city": "Berlin",
                    "country": "Germany",
                    "country_code": "de",
                    "ISO3166-2-lvl4": "DE-BE"
                },
                "category": "place",
                "osm_type": "node",
                "place_id": 144598842,
                "importance": 0.200
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/geocoding-api
OpenAPI spec: https://www.oanor.com/api/geocoding-api/openapi.json