{"openapi":"3.1.0","info":{"title":"Maidenhead Locator API","version":"1.0.0","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 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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/maidenhead-api","description":"oanor gateway"}],"tags":[{"name":"Maidenhead"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/decode":{"get":{"operationId":"get_v1_decode","tags":["Maidenhead"],"summary":"Locator to coordinates","description":"","parameters":[{"name":"locator","in":"query","required":true,"description":"A Maidenhead locator","schema":{"type":"string"},"example":"JN58td"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/distance":{"get":{"operationId":"get_v1_distance","tags":["Maidenhead"],"summary":"Distance between two locators","description":"","parameters":[{"name":"from","in":"query","required":true,"description":"A locator","schema":{"type":"string"},"example":"JN58td"},{"name":"to","in":"query","required":true,"description":"A locator","schema":{"type":"string"},"example":"IO91wm"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/encode":{"get":{"operationId":"get_v1_encode","tags":["Maidenhead"],"summary":"Coordinates to locator","description":"","parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude","schema":{"type":"string"},"example":"48.1397"},{"name":"lon","in":"query","required":true,"description":"Longitude","schema":{"type":"string"},"example":"11.6083"},{"name":"precision","in":"query","required":false,"description":"4|6|8|10 (default 6)","schema":{"type":"string"},"example":"6"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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 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 (km 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."},"meta":{"timestamp":"2026-06-03T17:42:03.967Z","request_id":"ec7cc89d-45d2-465d-ae12-4ae4db9af39e"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":8535,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1005,"monthly_call_quota":18050,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":2995,"monthly_call_quota":231500,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":6795,"monthly_call_quota":1200000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/maidenhead-api"}