{"openapi":"3.1.0","info":{"title":"UK Postcode API","version":"1.0.0","description":"UK postcode and geography lookup as an API, built on the open postcodes.io dataset. Resolve any UK postcode to its latitude/longitude and full administrative hierarchy — district, ward, county, parish, parliamentary constituency, region, NHS health authority and statistical areas (LSOA, MSOA). Validate a postcode, reverse-geocode coordinates to the nearest postcodes (with distance), find postcodes near a given one, autocomplete a partial postcode for address forms, look up an outcode (the first half, e.g. SW1A) and fetch a random postcode. Real data, no key needed upstream. Ideal for checkout and address forms, delivery and logistics, store locators, and UK geo-analytics.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/postcode-api","description":"oanor gateway"}],"tags":[{"name":"Postcodes"},{"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/autocomplete":{"get":{"operationId":"get_v1_autocomplete","tags":["Postcodes"],"summary":"Autocomplete a partial postcode","description":"","parameters":[{"name":"postcode","in":"query","required":true,"description":"A partial postcode, e.g. SW1A","schema":{"type":"string"},"example":"SW1A"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":10,"query":"SW1A","completions":["SW1A 0AA","SW1A 0PW","SW1A 0RS","SW1A 1AA","SW1A 1AB","SW1A 1AG","SW1A 1AH","SW1A 1BA","SW1A 1BB","SW1A 1BD"]},"meta":{"timestamp":"2026-06-08T01:19:43.201Z","request_id":"dc2e07a1-1ded-4ac0-95ec-6e75e39b91c8"},"status":"ok","message":"Autocomplete completed successfully","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/lookup":{"get":{"operationId":"get_v1_lookup","tags":["Postcodes"],"summary":"Full details for a postcode","description":"","parameters":[{"name":"postcode","in":"query","required":true,"description":"A UK postcode, e.g. SW1A 1AA","schema":{"type":"string"},"example":"SW1A1AA"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"postcode":{"ccg":"NHS North West London","lsoa":"Westminster 018C","msoa":"Westminster 018","nuts":"Westminster","incode":"1AA","parish":"Westminster, unparished area","region":"London","country":"England","outcode":"SW1A","quality":1,"eastings":529090,"latitude":51.50101,"postcode":"SW1A 1AA","longitude":-0.141563,"northings":179645,"admin_ward":"St James's","admin_district":"Westminster","primary_care_trust":"Westminster","nhs_health_authority":"London","european_electoral_region":"London","parliamentary_constituency":"Cities of London and Westminster"}},"meta":{"timestamp":"2026-06-08T01:19:43.312Z","request_id":"f1a99214-d985-43f0-afe5-69128e33ab32"},"status":"ok","message":"Postcode retrieved successfully","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/nearest":{"get":{"operationId":"get_v1_nearest","tags":["Postcodes"],"summary":"Postcodes near a postcode","description":"","parameters":[{"name":"postcode","in":"query","required":true,"description":"A UK postcode","schema":{"type":"string"},"example":"SW1A1AA"},{"name":"limit","in":"query","required":false,"description":"Max results (default 10)","schema":{"type":"string"},"example":"10"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":1,"postcode":"SW1A1AA","postcodes":[{"ccg":"NHS North West London","lsoa":"Westminster 018C","msoa":"Westminster 018","nuts":"Westminster","incode":"1AA","parish":"Westminster, unparished area","region":"London","country":"England","outcode":"SW1A","quality":1,"eastings":529090,"latitude":51.50101,"postcode":"SW1A 1AA","longitude":-0.141563,"northings":179645,"admin_ward":"St James's","distance_m":0,"admin_district":"Westminster","primary_care_trust":"Westminster","nhs_health_authority":"London","european_electoral_region":"London","parliamentary_constituency":"Cities of London and Westminster"}]},"meta":{"timestamp":"2026-06-08T01:19:43.416Z","request_id":"a48aa394-5f92-474d-8cee-fd285138bdec"},"status":"ok","message":"Nearest postcodes retrieved successfully","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/outcode":{"get":{"operationId":"get_v1_outcode","tags":["Postcodes"],"summary":"Outcode (area) detail","description":"","parameters":[{"name":"outcode","in":"query","required":true,"description":"An outcode (first half), e.g. SW1A","schema":{"type":"string"},"example":"SW1A"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"outcode":{"parish":["Wandsworth, unparished area","Westminster, unparished area"],"country":["England"],"outcode":"SW1A","latitude":51.50454046527776,"longitude":-0.13218813888888892,"admin_ward":["Nine Elms","St James's"],"admin_county":[],"admin_district":["Wandsworth","Westminster"]}},"meta":{"timestamp":"2026-06-08T01:19:43.511Z","request_id":"926480c9-2861-4e22-805b-4813ddb88e41"},"status":"ok","message":"Outcode retrieved successfully","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/random":{"get":{"operationId":"get_v1_random","tags":["Postcodes"],"summary":"A random postcode","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"postcode":{"ccg":"NHS Devon","lsoa":"Plymouth 027E","msoa":"Plymouth 027","nuts":"Plymouth","incode":"1EP","parish":"Plymouth, unparished area","region":"South West","country":"England","outcode":"PL1","quality":1,"eastings":247578,"latitude":50.370653,"postcode":"PL1 1EP","longitude":-4.144743,"northings":54507,"admin_ward":"St Peter and the Waterfront","admin_district":"Plymouth","primary_care_trust":"Plymouth Teaching","nhs_health_authority":"South West","european_electoral_region":"South West","parliamentary_constituency":"Plymouth Sutton and Devonport"}},"meta":{"timestamp":"2026-06-08T01:19:43.616Z","request_id":"10f4dd4f-1472-4fab-be3a-0131cad9d533"},"status":"ok","message":"Random postcode retrieved successfully","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/reverse":{"get":{"operationId":"get_v1_reverse","tags":["Postcodes"],"summary":"Nearest postcodes to coordinates","description":"","parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude","schema":{"type":"string"},"example":"51.501"},{"name":"lon","in":"query","required":true,"description":"Longitude","schema":{"type":"string"},"example":"-0.1416"},{"name":"limit","in":"query","required":false,"description":"Max results (default 10)","schema":{"type":"string"},"example":"10"},{"name":"radius","in":"query","required":false,"description":"Search radius in metres (max 2000)","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":1,"latitude":51.501,"longitude":-0.1416,"postcodes":[{"ccg":"NHS North West London","lsoa":"Westminster 018C","msoa":"Westminster 018","nuts":"Westminster","incode":"1AA","parish":"Westminster, unparished area","region":"London","country":"England","outcode":"SW1A","quality":1,"eastings":529090,"latitude":51.50101,"postcode":"SW1A 1AA","longitude":-0.141563,"northings":179645,"admin_ward":"St James's","distance_m":2.7920763597315994,"admin_district":"Westminster","primary_care_trust":"Westminster","nhs_health_authority":"London","european_electoral_region":"London","parliamentary_constituency":"Cities of London and Westminster"}]},"meta":{"timestamp":"2026-06-08T01:19:43.734Z","request_id":"ea20a0aa-70e3-48d9-b68a-36d3d154c9e2"},"status":"ok","message":"Reverse geocode completed successfully","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/validate":{"get":{"operationId":"get_v1_validate","tags":["Postcodes"],"summary":"Validate a postcode","description":"","parameters":[{"name":"postcode","in":"query","required":true,"description":"A UK postcode","schema":{"type":"string"},"example":"SW1A1AA"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"valid":true,"postcode":"SW1A1AA"},"meta":{"timestamp":"2026-06-08T01:19:43.827Z","request_id":"d4755a58-64c2-4b5f-9969-90117b93d36d"},"status":"ok","message":"Validation completed successfully","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":"Service description & endpoints","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"service":"postcode-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/lookup":"Full details for a postcode (postcode=).","GET /v1/random":"A random postcode.","GET /v1/nearest":"Postcodes near a postcode (postcode=, limit=).","GET /v1/outcode":"Outcode (area) detail (outcode=, e.g. SW1A).","GET /v1/reverse":"Nearest postcodes to coordinates (lat=, lon=, radius=, limit=).","GET /v1/validate":"Validate a postcode (postcode=).","GET /v1/autocomplete":"Autocomplete a partial postcode (postcode=)."},"description":"UK postcode & geography lookup via postcodes.io: resolve a postcode to coordinates and administrative areas (district, ward, county, parliamentary constituency, region, NHS area), validate a postcode, reverse-geocode coordinates to the nearest postcodes, find nearby postcodes, autocomplete a partial postcode, look up an outcode and fetch a random postcode. Real data, no key."},"meta":{"timestamp":"2026-06-08T01:19:43.901Z","request_id":"3b00c7fa-0846-4a11-9afe-28169f940d4a"},"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":10000,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":300,"monthly_call_quota":130000,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1700,"monthly_call_quota":700000,"rps_limit":25,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":6500,"monthly_call_quota":3500000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/postcode-api"}