{"openapi":"3.1.0","info":{"title":"Postcoders Location API","description":"Postcode coordinates, spatial nearest neighbours, and fuzzy open-data address search. Postcode source: ONS Postcode Directory, August 2026; current and terminated records. Northern Ireland (BT) is excluded pending separate commercial licensing. Contains OS data © Crown copyright and database right 2026. Contains Royal Mail data © Royal Mail copyright and database right 2026. Source: Office for National Statistics licensed under the Open Government Licence v.3.0. https://www.ons.gov.uk/methodology/geography/licences. Addresses: © OpenStreetMap contributors, ODbL 1.0; incomplete GB coverage. Explicit UPRNs are joined to OS Open UPRN September 2026. Property points may be approximate; other records use labelled postcode centroids. Licence: https://www.openstreetmap.org/copyright. Derived database: https://app.postcoders.co.uk/downloads/addresses-manifest.json","version":"1.0.0"},"paths":{"/v1/postcodes/{code}":{"get":{"tags":["Postcodes"],"summary":"Look up a canonical UK postcode, including terminated records","operationId":"postcode_v1_postcodes__code__get","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Postcode"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unprocessable Content"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal Server Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"}}}},"/v1/places/nearest":{"get":{"tags":["Places"],"summary":"Find active postcodes ordered by spherical distance in metres","operationId":"nearest_v1_places_nearest_get","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"title":"Lat"}},{"name":"lon","in":"query","required":true,"schema":{"type":"number","maximum":180,"minimum":-180,"title":"Lon"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":5,"title":"Limit"}},{"name":"radius_m","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":100000,"exclusiveMinimum":0},{"type":"null"}],"title":"Radius M"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NearestResponse"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unprocessable Content"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal Server Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"}}}},"/v1/addresses/search":{"get":{"tags":["Addresses"],"summary":"Typo-tolerant search of the published address index","operationId":"addresses_v1_addresses_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":8,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressResponse"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unprocessable Content"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal Server Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"}}}}},"components":{"schemas":{"Address":{"properties":{"id":{"type":"string","title":"Id"},"address":{"type":"string","title":"Address"},"postcode":{"type":"string","title":"Postcode"},"post_town":{"type":"string","title":"Post Town"},"uprn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uprn"},"longitude":{"type":"number","title":"Longitude"},"latitude":{"type":"number","title":"Latitude"},"coordinate_accuracy":{"type":"string","enum":["property","postcode_centroid"],"title":"Coordinate Accuracy"},"source":{"type":"string","title":"Source"}},"type":"object","required":["id","address","postcode","post_town","longitude","latitude","coordinate_accuracy","source"],"title":"Address"},"AddressResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/Address"},"type":"array","title":"Results"},"found":{"type":"integer","minimum":0.0,"title":"Found"},"search_time_ms":{"type":"integer","minimum":0.0,"title":"Search Time Ms"},"took_ms":{"type":"number","minimum":0.0,"title":"Took Ms"},"search_cutoff":{"type":"boolean","title":"Search Cutoff","default":false}},"type":"object","required":["results","found","search_time_ms","took_ms"],"title":"AddressResponse"},"ErrorDetail":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"request_id":{"type":"string","title":"Request Id"}},"type":"object","required":["code","message","request_id"],"title":"ErrorDetail"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"type":"object","required":["error"],"title":"ErrorResponse"},"NearestPostcode":{"properties":{"postcode":{"type":"string","title":"Postcode"},"longitude":{"type":"number","title":"Longitude"},"latitude":{"type":"number","title":"Latitude"},"distance_m":{"type":"number","minimum":0.0,"title":"Distance M"}},"type":"object","required":["postcode","longitude","latitude","distance_m"],"title":"NearestPostcode"},"NearestResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/NearestPostcode"},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"NearestResponse"},"Postcode":{"properties":{"postcode":{"type":"string","title":"Postcode"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude"},"introduced_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Introduced On"},"terminated_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Terminated On"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"region_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Code"},"local_authority_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Local Authority Code"},"ward_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ward Code"},"positional_quality":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Positional Quality"},"source":{"type":"string","title":"Source"},"source_release":{"type":"string","format":"date","title":"Source Release"}},"type":"object","required":["postcode","longitude","latitude","introduced_on","terminated_on","country_code","region_code","local_authority_code","ward_code","positional_quality","source","source_release"],"title":"Postcode"}}}}