# Maidenhead Locator API
> Convert between latitude/longitude and the Maidenhead Locator System — the grid-square "QTH locator" (like JN58td or IO91wm) used by amateur radio, APRS and contesting to describe a position compactly. The encode endpoint turns a latitude and longitude into a locator at 4-, 6-, 8- or 10-character precision. The decode endpoint turns a locator back into the centre coordinates, the south-west corner and the size of the grid square. The distance endpoint gives the great-circle distance (kilometres and miles) and bearing between the centres of two locators — the classic "how far and which way is that station". Everything is computed locally and deterministically, so it is instant and private. Ideal for amateur-radio and APRS tools, contest logging, antenna aiming, and grid-based mapping. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is the Maidenhead system; for Plus Codes, MGRS, UTM and DMS use a geo-convert API and for precise geodesic distance use a geodesy API.

## 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/maidenhead-api/..."
```

## Pricing
- **Free** (Free) — 8,535 calls/Mo, 2 req/s
- **Starter** ($10/Mo) — 18,050 calls/Mo, 8 req/s
- **Pro** ($30/Mo) — 231,500 calls/Mo, 20 req/s
- **Mega** ($68/Mo) — 1,200,000 calls/Mo, 50 req/s

## Endpoints

### Maidenhead

#### `GET /v1/decode` — Locator to coordinates

**Parameters:**
- `locator` (query, required, string) — A Maidenhead locator Example: `JN58td`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/maidenhead-api/v1/decode?locator=JN58td"
```

**Response:**
```json
{
    "data": {
        "center": {
            "lat": 48.14583,
            "lon": 11.625
        },
        "locator": "JN58TD",
        "grid_size_deg": {
            "lat": 0.0416667,
            "lon": 0.0833333
        },
        "southwest_corner": {
            "lat": 48.125,
            "lon": 11.58333
        }
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:03.714Z",
        "request_id": "13e32c7c-7447-4cc8-bf9e-cde655c023e1"
    },
    "status": "ok",
    "message": "Decode locator",
    "success": true
}
```

#### `GET /v1/distance` — Distance between two locators

**Parameters:**
- `from` (query, required, string) — A locator Example: `JN58td`
- `to` (query, required, string) — A locator Example: `IO91wm`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/maidenhead-api/v1/distance?from=JN58td&to=IO91wm"
```

**Response:**
```json
{
    "data": {
        "to": "IO91WM",
        "from": "JN58TD",
        "to_center": {
            "lat": 51.52083,
            "lon": -0.125
        },
        "bearing_deg": 298.42,
        "distance_km": 921.151,
        "distance_mi": 572.377,
        "from_center": {
            "lat": 48.14583,
            "lon": 11.625
        }
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:03.795Z",
        "request_id": "30eddbb8-7d5d-4f6e-ab54-67ea7ca0e88c"
    },
    "status": "ok",
    "message": "Grid distance",
    "success": true
}
```

#### `GET /v1/encode` — Coordinates to locator

**Parameters:**
- `lat` (query, required, string) — Latitude Example: `48.1397`
- `lon` (query, required, string) — Longitude Example: `11.6083`
- `precision` (query, optional, string) — 4|6|8|10 (default 6) Example: `6`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/maidenhead-api/v1/encode?lat=48.1397&lon=11.6083&precision=6"
```

**Response:**
```json
{
    "data": {
        "lat": 48.1397,
        "lon": 11.6083,
        "locator": "JN58td",
        "precision": 6
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:03.889Z",
        "request_id": "02df7794-12c0-4a6a-905e-76af72d4c6f8"
    },
    "status": "ok",
    "message": "Encode locator",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/maidenhead-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Maidenhead Locator API",
        "notes": "Field 20°×10°, square 2°×1°, subsquare 5′×2.5′. Distance uses the great-circle between grid centres. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/encode",
                "params": {
                    "lat": "latitude",
                    "lon": "longitude",
                    "precision": "4|6|8|10 (default 6)"
                },
                "returns": "the Maidenhead locator"
            },
            {
                "path": "/v1/decode",
                "params": {
                    "locator": "a Maidenhead locator, e.g. JN58td"
                },
                "returns": "the centre, south-west corner and grid size"
            },
            {
                "path": "/v1/distance",
                "params": {
                    "to": "a locator",
                    "from": "a locator"
                },
                "returns": "great-circle distance and bearing between the grids"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Convert between latitude/longitude and the Maidenhead Locator System — the grid-square \"QTH locator\" (like JN58td or IO91wm) used by amateur radio, APRS and contesting to describe a position compactly. The encode endpoint turns a latitu
…(truncated, see openapi.json for full schema)
```


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