{"openapi":"3.1.0","info":{"title":"UK Grounding Postcode API","version":"1.0.0","description":"Postcode lookup grounded in ONS Postcode Directory, February 2025. Northern Ireland postcode data is not available.","license":{"name":"Open Government Licence v3.0; Northern Ireland BT records are excluded from this published dataset.","url":"https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"}},"servers":[{"url":"https://uk.grounding.360o.media"}],"paths":{"/api/v1/geography/postcodes/properties/list/{format}":{"get":{"operationId":"listPostcodeProperties","summary":"List postcode detail fields and their descriptions","responses":{"200":{"description":"Property catalogue","content":{"application/json":{"schema":{"type":"object","required":["tool","source","properties"],"properties":{"tool":{"const":"postcode_list_properties"},"source":{"$ref":"#/components/schemas/PropertySource"},"properties":{"type":"array","items":{"$ref":"#/components/schemas/PostcodeProperty"}}}}},"text/toon":{"schema":{"type":"string","description":"Lossless TOON encoding of the JSON response."}}}},"429":{"description":"Request limit reached"}},"parameters":[{"name":"format","in":"path","required":true,"schema":{"type":"string","enum":["json","toon"]}}]}},"/api/v1/geography/postcodes/properties/describe/{field}/{format}":{"get":{"operationId":"describePostcodeProperty","summary":"Describe a postcode detail field","parameters":[{"name":"field","in":"path","required":true,"schema":{"type":"string"},"example":"country_code"},{"name":"format","in":"path","required":true,"schema":{"type":"string","enum":["json","toon"]}}],"responses":{"200":{"description":"Property description","content":{"application/json":{"schema":{"type":"object","required":["tool","source","property"],"properties":{"tool":{"const":"postcode_describe_property"},"source":{"$ref":"#/components/schemas/PropertySource"},"property":{"$ref":"#/components/schemas/PostcodeProperty"}}}},"text/toon":{"schema":{"type":"string","description":"Lossless TOON encoding of the JSON response."}}}},"404":{"description":"Unknown property"},"429":{"description":"Request limit reached"}}}},"/api/v1/geography/postcodes/{postcode}.json":{"get":{"operationId":"getUkPostcode","summary":"Look up a UK postcode using the legacy .json route","deprecated":true,"description":"Returns the matching normalized source record and its termination status. Raw source rows are not included. A postcode with a termination date is returned as terminated; a record without one is returned as current.","parameters":[{"name":"postcode","in":"path","required":true,"schema":{"type":"string","minLength":5,"maxLength":9},"description":"Postcode with or without its separating space."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","toon"],"default":"json"},"description":"Response encoding. TOON is intended for LLM input; field names remain present."}],"responses":{"200":{"description":"Current or terminated postcode record returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResult"}},"text/toon":{"schema":{"type":"string"}}}},"400":{"description":"Invalid postcode format or response format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}},"404":{"description":"No record found in source release ONSPD_FEB_2025","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}},"422":{"description":"Outside supported coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}},"429":{"description":"Request limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}},"503":{"description":"Postcode data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}}}}},"/api/v1/geography/postcodes/details/{postcode}/{format}":{"get":{"operationId":"getUkPostcodeByFormat","summary":"Look up a UK postcode as JSON or TOON","description":"Returns the normalized source record and its termination status. Select json or toon in the final path segment.","parameters":[{"name":"postcode","in":"path","required":true,"schema":{"type":"string","minLength":5,"maxLength":9},"description":"Postcode with or without its separating space; URL-encode the space when present."},{"name":"format","in":"path","required":true,"schema":{"type":"string","enum":["json","toon"]},"description":"Response encoding. TOON is intended for LLM input; field names remain present."}],"responses":{"200":{"description":"Current or terminated postcode record returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResult"}},"text/toon":{"schema":{"type":"string"}}}},"400":{"description":"Invalid postcode format or response format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}},"404":{"description":"No record found in source release ONSPD_FEB_2025","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}},"422":{"description":"Outside supported coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}},"429":{"description":"Request limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}},"503":{"description":"Postcode data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}}}}},"/api/v1/geography/postcodes/validate/{postcode}/{format}":{"get":{"operationId":"validateUkPostcode","summary":"Validate a UK postcode and return JSON or TOON","description":"Returns a compact postcode status relative to the identified source release, with its message and termination month; it does not verify present-day status. Use the GET endpoint to retrieve geography fields.","parameters":[{"name":"postcode","in":"path","required":true,"schema":{"type":"string","minLength":5,"maxLength":9},"description":"Postcode with or without its separating space; URL-encode the space when present."},{"name":"format","in":"path","required":true,"schema":{"type":"string","enum":["json","toon"]},"description":"Response encoding. TOON is intended for LLM input; field names remain present."}],"responses":{"200":{"description":"Current or terminated postcode status returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}},"text/toon":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request, response format or postcode","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiError"},{"$ref":"#/components/schemas/ValidationResult"}]}},"text/toon":{"schema":{"type":"string"}}}},"404":{"description":"No record found in source release ONSPD_FEB_2025","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}},"text/toon":{"schema":{"type":"string"}}}},"422":{"description":"Outside supported coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}},"text/toon":{"schema":{"type":"string"}}}},"429":{"description":"Request limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}},"503":{"description":"Postcode data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}},"text/toon":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"LookupTiming":{"type":["number","null"],"minimum":0,"description":"Measured server postcode lookup duration in milliseconds, including database access and record projection; excludes authentication, usage recording and network time. This is processing duration, not a measure of data freshness. Null when no postcode lookup was performed."},"PostcodeProperty":{"type":"object","required":["name","description","type","sourceField","dataCategory","exposedTo","location"],"properties":{"dataCategory":{"type":"string","enum":["sourceSpecific","toolInfo","generic"]},"exposedTo":{"type":"array","items":{"type":"string","enum":["astro.api","astro.mcp","astro.webmcp"]}},"location":{"type":"string","enum":["response","data"]},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["string","number","object"]},"sourceField":{"type":["string","null"],"description":"Source column used by the local import mapping; null for locally derived fields. Legacy source columns may not exist in the selected source release."}}},"PropertySource":{"type":"object","required":["datasetKey","dataset","publisher","release","releaseLabel","releaseMonth","licence","attributions","batchKey","provenanceStatus","notices"],"properties":{"datasetKey":{"type":"string"},"dataset":{"type":"string"},"publisher":{"type":"string"},"release":{"type":"string","example":"ONSPD_FEB_2025"},"releaseLabel":{"type":"string","example":"February 2025"},"releaseMonth":{"type":["string","null"],"example":"2025-02","description":"Publisher release month when known; not a real-time verification date."},"licence":{"type":"string"},"licenceUrl":{"type":["string","null"],"format":"uri"},"attributions":{"type":"array","items":{"type":"string"}},"batchKey":{"type":"string","format":"uuid"},"provenanceStatus":{"type":"string","description":"Recorded import provenance state; historical does not assert a verified successful original import."},"guide":{"type":["string","null"],"format":"uri"},"mappingNote":{"type":["string","null"]},"notices":{"type":"array","items":{"type":"string"}}}},"ApiError":{"type":"object","required":["tool","status","lookupTimeMs","message"],"properties":{"tool":{"type":"string","enum":["postcode_details","postcode_validate"]},"status":{"const":"error"},"lookupTimeMs":{"$ref":"#/components/schemas/LookupTiming"},"message":{"type":"string"}}},"LookupResult":{"type":"object","required":["tool","status","lookupTimeMs","data","source"],"properties":{"tool":{"const":"postcode_details"},"lookupTimeMs":{"$ref":"#/components/schemas/LookupTiming"},"status":{"type":"string","enum":["current","terminated","not_found","outside_coverage","invalid_input"],"description":"Source-relative status: current means no termination date is recorded for the postcode in the specified source release, not confirmed as current today; terminated means a termination date is recorded in that release."},"data":{"type":["object","null"],"additionalProperties":true,"description":"All fields from the source normalized postcode record."},"message":{"type":"string","description":"Explains the postcode status when relevant."},"source":{"type":"object","required":["datasetKey","dataset","publisher","release","releaseLabel","releaseMonth","licence","attributions","batchKey","provenanceStatus","notices"],"properties":{"datasetKey":{"type":"string"},"dataset":{"type":"string"},"publisher":{"type":"string"},"release":{"type":"string","example":"ONSPD_FEB_2025"},"releaseLabel":{"type":"string","example":"February 2025"},"releaseMonth":{"type":["string","null"],"example":"2025-02","description":"Publisher release month when known; not a real-time verification date."},"licence":{"type":"string"},"licenceUrl":{"type":["string","null"],"format":"uri"},"attributions":{"type":"array","items":{"type":"string"}},"batchKey":{"type":"string","format":"uuid"},"provenanceStatus":{"type":"string","description":"Recorded import provenance state; historical does not assert a verified successful original import."},"guide":{"type":["string","null"],"format":"uri"},"mappingNote":{"type":["string","null"]},"notices":{"type":"array","items":{"type":"string"}}}}}},"ValidationResult":{"type":"object","required":["tool","status","terminationDate","lookupTimeMs","message","source"],"properties":{"tool":{"const":"postcode_validate"},"lookupTimeMs":{"$ref":"#/components/schemas/LookupTiming"},"status":{"type":"string","enum":["current","terminated","not_found","outside_coverage","invalid_input"]},"terminationDate":{"type":["string","null"],"description":"Termination month as YYYY-MM when recorded in the identified release. Null may mean no date was recorded, or no matching record was assessed; it does not establish current-day status."},"message":{"type":"string","description":"Explains the postcode status."},"source":{"type":"object","required":["datasetKey","dataset","publisher","release","releaseLabel","releaseMonth","licence","attributions","batchKey","provenanceStatus","notices"],"properties":{"datasetKey":{"type":"string"},"dataset":{"type":"string"},"publisher":{"type":"string"},"release":{"type":"string","example":"ONSPD_FEB_2025"},"releaseLabel":{"type":"string","example":"February 2025"},"releaseMonth":{"type":["string","null"],"example":"2025-02","description":"Publisher release month when known; not a real-time verification date."},"licence":{"type":"string"},"licenceUrl":{"type":["string","null"],"format":"uri"},"attributions":{"type":"array","items":{"type":"string"}},"batchKey":{"type":"string","format":"uuid"},"provenanceStatus":{"type":"string","description":"Recorded import provenance state; historical does not assert a verified successful original import."},"guide":{"type":["string","null"],"format":"uri"},"mappingNote":{"type":["string","null"]},"notices":{"type":"array","items":{"type":"string"}}}}}}}}}