diff --git a/openapi/components/schemas/Place.yaml b/openapi/components/schemas/Place.yaml index 51b2c930..9c9343e4 100644 --- a/openapi/components/schemas/Place.yaml +++ b/openapi/components/schemas/Place.yaml @@ -109,13 +109,15 @@ properties: example: "Wales" longitude: title: Longitude - type: double float + type: number + format: double description: >- The WGS84 longitude given the Place's national grid reference. example: "-3.14971194307843" latitude: title: Latitude - type: double float + type: number + format: double description: >- The WGS84 latitude given the Place's national grid reference. example: "52.6606391732959" diff --git a/openapi/paths/outcodes@{outcode}.yaml b/openapi/paths/outcodes@{outcode}.yaml index c0e4c435..e4f55258 100644 --- a/openapi/paths/outcodes@{outcode}.yaml +++ b/openapi/paths/outcodes@{outcode}.yaml @@ -4,9 +4,9 @@ get: summary: "Outcode Lookup" description: $ref: ../md/outcode.md - operationId: FindPlace + operationId: FindOutcode parameters: - - name: Outcode + - name: outcode in: path description: Specifies the outward code you wish to query. required: true diff --git a/openapi/paths/places@{code}.yaml b/openapi/paths/places@{code}.yaml index b17f942c..d75a2532 100644 --- a/openapi/paths/places@{code}.yaml +++ b/openapi/paths/places@{code}.yaml @@ -6,11 +6,11 @@ get: $ref: ../md/places.md operationId: FindPlace parameters: - - name: query - in: query + - name: code + in: path description: Specifies the place you wish to query required: true - style: form + style: simple explode: false schema: type: string diff --git a/openapi/paths/postcodes.yaml b/openapi/paths/postcodes.yaml index 1610319d..fa51894b 100644 --- a/openapi/paths/postcodes.yaml +++ b/openapi/paths/postcodes.yaml @@ -47,18 +47,6 @@ get: example: 51.50354 maximum: 90 minimum: -90 - - name: limit - in: query - style: form - explode: false - schema: - title: Limit - type: integer - description: Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100. - example: 20 - maximum: 100 - default: 10 - minimum: 1 - name: radius in: query style: form diff --git a/openapi/paths/scotland@postcodes@{postcode}.yaml b/openapi/paths/scotland@postcodes@{postcode}.yaml index c4d16354..cd73046e 100644 --- a/openapi/paths/scotland@postcodes@{postcode}.yaml +++ b/openapi/paths/scotland@postcodes@{postcode}.yaml @@ -6,7 +6,7 @@ get: $ref: ../md/scottish-postcodes.md operationId: Scottish Postcodes parameters: - - name: Scottish Postcode + - name: postcode in: path description: Specifies the postcode you wish to query required: true diff --git a/openapi/paths/terminated_postcodes@{postcode}.yaml b/openapi/paths/terminated_postcodes@{postcode}.yaml index 67b8179a..7b3d610d 100644 --- a/openapi/paths/terminated_postcodes@{postcode}.yaml +++ b/openapi/paths/terminated_postcodes@{postcode}.yaml @@ -6,7 +6,7 @@ get: $ref: ../md/terminated-postcodes.md operationId: TerminatedPostcodes parameters: - - name: Terminated Postcode + - name: postcode in: path description: Postcode to query required: true diff --git a/public/openapi.json b/public/openapi.json index 2f87eb57..63e9e392 100644 --- a/public/openapi.json +++ b/public/openapi.json @@ -3,12 +3,12 @@ "info": { "version": "3.5.1", "license": { - "name": "AGPLv3", - "url": "https://opensource.org/licenses/AGPL-3.0" + "name": "MIT", + "url": "https://opensource.org/licenses/MIT" }, "title": "API Reference - Postcodes.io", "termsOfService": "https://postcodes.io/about", - "description": "# Overview\n\nPostcodes.io is a free postcode lookup API and geocoder for the UK\n\n## Endpoint\nAll services can be accessed from the following HTTP[S] endpoint\n\n`https://api.postcodes.io`\nThe API accepts GET and POST requests. POST methods use content type application/json\n\n## Responses\nJSON(P) only. CORS is enabled.\n\nEach response comes with an appropriate HTTP Status code (except for JSONP requests). These include 200 for success, 400 for a bad request, 404 for not found and 500 for server error. The HTTP Status code is also included in the response body.\n\n## Authentication\nPostcodes.io does not require any authentication.\n\n## Versioning\nThe API currently does not use any form of versioning. Any changes to the API will be backwards-compatible, this includes: adding new properties to responses, adding new endpoints, adding new optional request parameters and changing the order of properties.\n\nIf we make backwards-incompatible changes in the future, this will be released under a versioned endpoint.", + "description": "# Overview\n\nPostcodes.io is a free postcode lookup API and geocoder for the UK.\n\n## Endpoint\n\nAll services can be accessed from the following endpoint.\n\n```\nhttps://api.postcodes.io\n```\n\nThe API accepts GET and POST requests. POST methods use content type `application/json`.\n\n## Responses\n\nJSON(P) only. CORS is enabled.\n\nEach response comes with an appropriate HTTP Status code (except for JSONP requests). These include 200 for success, 400 for a bad request, 404 for not found and 500 for server error. The HTTP Status code is also included in the response body.\n\n## Authentication\n\nPostcodes.io does not require authentication.\n", "contact": { "email": "support@ideal-postcodes.co.uk", "name": "Support", @@ -28,16 +28,34 @@ ], "tags": [ { - "name": "Postcode Lookup", - "description": "Search for UK postcodes" + "name": "Postcode Lookup" }, { - "name": "Outward Postcodes", - "description": "Search by UK outward codes" + "name": "Postcode Query" }, { - "name": "Places Search", - "description": "Search UK places" + "name": "Nearest Postcode" + }, + { + "name": "Random Postcode" + }, + { + "name": "Terminated Postcodes" + }, + { + "name": "Scottish Postcode Search" + }, + { + "name": "Outward Postcodes" + }, + { + "name": "Place Search" + }, + { + "name": "Place Query" + }, + { + "name": "Random Place" } ], "x-tagGroups": [ @@ -45,10 +63,15 @@ "name": "API", "tags": [ "Postcode Lookup", - "Place Search", + "Postcode Query", + "Nearest Postcode", + "Random Postcode", "Terminated Postcodes", "Scottish Postcodes", - "Outward Code Lookup" + "Outward Code Lookup", + "Place Search", + "Place Query", + "Random Place" ] } ], @@ -102,24 +125,257 @@ ] } }, - "/places": { + "/postcodes": { "get": { "tags": [ - "Place Search" + "Postcode Query" ], - "summary": "Find Place", - "description": "### Places Data (Ordnance Survey Open Names Dataset)\n\nSubmit a place query and receive a complete list of places matches and associated data.ind a place by OSGB code (e.g. \"osgb4000000074564391\"). Returns all available data if found. Returns 404 if place does not exist.\n", - "operationId": "FindPlace", + "summary": "Postcode Query", + "operationId": "Postcode Query", + "description": "Query for a postcode either by:\n\n- The postcode itself (with `postcode=`) or by,\n- A geolocation (`lat=` and `lon=`).\n\n## Query with Postcode\n\nSubmit a postcode query and receive a complete list of postcode matches and all associated postcode data. This is triggered when `query=` is supplied.\n\nThis is essentially a postcode search which prefix matches and returns postcodes in sorted order (case insensitive)\n\nThis method is space sensitive, i.e. it detects for spaces between outward and inward parts of the postcode (some examples detailed in this [issue](https://github.com/ideal-postcodes/postcodes.io/issues/44))\n\nThe result set can either be empty or populated with up to 100 postcode entities. Either way it will always return a 200 response code\n\n## Query with Geolocation\n\nReturns nearest postcodes for a given longitude and latitude. This is triggered when `lat=` and `lon=` is supplied.\n", "parameters": [ { "name": "query", "in": "query", - "description": "Specifies the place you wish to query", + "style": "form", + "explode": false, + "schema": { + "description": "Postcode to query. Aliases to `q=`", + "example": "SW1A 2AA" + } + }, + { + "name": "limit", + "in": "query", + "style": "form", + "explode": false, + "schema": { + "default": 10, + "maximum": 100, + "minimum": 1, + "description": "PLimits number of postcodes matches to return. Defaults to 10. Needs to be less than 100.", + "example": 3 + } + }, + { + "name": "longitude", + "in": "query", + "style": "form", + "explode": false, + "schema": { + "title": "Longitude", + "type": "number", + "format": "double", + "description": "Geographic coordinate that specifies the east-west position of a point", + "example": -0.127695, + "maximum": 180, + "minimum": -180 + } + }, + { + "name": "latitude", + "in": "query", + "style": "form", + "explode": false, + "schema": { + "title": "Latitude", + "type": "number", + "format": "double", + "description": "Geographic coordinate that specifies the north-south position of a point", + "example": 51.50354, + "maximum": 90, + "minimum": -90 + } + }, + { + "name": "radius", + "in": "query", + "style": "form", + "explode": false, + "schema": { + "title": "Radius", + "type": "integer", + "description": "Limits number of postcodes matches to return. Defaults to 100m. Needs to be less than 2,000m.", + "example": 500, + "default": 100, + "maximum": 2000, + "minimum": 1 + } + }, + { + "name": "widesearch", + "in": "query", + "style": "form", + "explode": false, + "schema": { + "title": "Widesearch", + "type": "boolean", + "description": "Search up to 20km radius, but subject to a maximum of 10 results. Since lookups over a wide area can be very expensive, we've created this method to allow you choose to make the trade off between search radius and number of results. Defaults to false. When enabled, radius and limits over 10 are ignored.", + "example": "true", + "default": "false" + } + }, + { + "name": "filter", + "in": "query", + "style": "form", + "explode": false, + "schema": { + "title": "Filter", + "type": "string", + "description": "A comma separated whitelist of attributes to be returned in the result object(s), e.g. filter=postcode,longitude,latitude. null responses will continue to return null. If no attributes match the result object, an empty object is returned", + "example": "postcode" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostcodeResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "http", + "label": "Query URL", + "source": "https://api.postcodes.io/postcodes/SW1A2AA\n" + }, + { + "lang": "cURL", + "label": "Query CLI", + "source": "curl -G -k \\\n--url 'https://api.postcodes.io/postcodes/SW1A2AA'\n" + }, + { + "lang": "http", + "label": "Nearest URL", + "source": "https://api.postcodes.io/postcodes?lon=-0.127695&lat=51.50354\n" + }, + { + "lang": "cURL", + "label": "Nearest CLI", + "source": "curl -G -k \\\n--url 'https://api.postcodes.io/postcodes?lon=-0.127695&lat=51.50354'\n" + } + ] + }, + "post": { + "tags": [ + "Postcode Query" + ], + "summary": "Bulk Postcode Lookup", + "operationId": "Bulk Postcode Lookup", + "description": "Accepts a JSON object containing an array of postcodes. Returns a list of matching postcodes and respective available data.\n\nBe sure to submit JSON requests setting `Content-Type` to `application/json`\n\nAccepts up to 100 postcodes.\n\n### Post Data\n\nThis method requires a JSON object containing an array of postcodes to be posted, e.g.\n\n```json\n{\n \"postcodes\": [\"PR3 0SG\", \"M45 6GN\", \"EX165BL\"]\n}\n```\n\n## Bulk Reverse Geocoding\n\nBulk translates geolocations into Postcodes. Accepts up to 100 geolocations.\n", + "parameters": [], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostcodeResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "http", + "label": "Query URL", + "source": "https://api.postcodes.io/postcodes/\n" + }, + { + "lang": "cURL", + "label": "Query CLI", + "source": "curl -G -k \\\n--url 'https://api.postcodes.io/postcodes/'\n" + }, + { + "lang": "http", + "label": "Nearest URL", + "source": "https://api.postcodes.io/postcodes?\n" + }, + { + "lang": "cURL", + "label": "Nearest CLI", + "source": "curl -G -k \\\n--url 'https://api.postcodes.io/postcodes?'\n" + } + ] + } + }, + "/postcodes/{postcode}/nearest": { + "get": { + "tags": [ + "Nearest Postcode" + ], + "summary": "Lookup Nearest Postcodes", + "operationId": "Nearest Postcode", + "description": "Returns nearest postcodes for a given postcode.", + "parameters": [ + { + "name": "postcode", + "in": "path", + "description": "Postcode to retrieve", "required": true, + "style": "simple", + "explode": false, + "schema": { + "title": "Postcode", + "description": "Postcode to query", + "example": "SW1A 2AA" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostcodeResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "http", + "label": "URL", + "source": "https://api.postcodes.io/postcodes/SW1A2AA\n" + }, + { + "lang": "cURL", + "label": "CLI", + "source": "curl -G -k \\\n--url 'https://api.postcodes.io/postcodes/SW1A2AA'\n" + } + ] + } + }, + "/random/postcodes": { + "get": { + "tags": [ + "Random Postcode" + ], + "summary": "Random Postcode", + "operationId": "Random Postcode", + "description": "Returns a random postcode and all available data for that postcode.", + "parameters": [ + { + "name": "outcode", + "in": "query", + "description": "Filters random postcodes by outcode. Returns null if invalid outcode.", "style": "form", "explode": false, "schema": { - "type": "string" + "title": "Outward code", + "description": "Restrict results to a specific outward code", + "type": "string", + "example": "SW1A" } } ], @@ -129,7 +385,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaceResponse" + "$ref": "#/components/schemas/PostcodeResponse" } } } @@ -139,31 +395,31 @@ { "lang": "http", "label": "URL", - "source": "https://api.postcodes.io/places?query=welshpool\n" + "source": "https://api.postcodes.io/random/postcodes\n" }, { "lang": "cURL", "label": "CLI", - "source": "curl -k -G 'https://api.postcodes.io/places' \\\n --data-urlencode 'query=welshpool'\n" + "source": "curl -G -k \\\n--url 'https://api.postcodes.io/random/postcodes'\n" } ] } }, - "/terminated-postcodes": { + "/terminated_postcodes/{postcode}": { "get": { "tags": [ "Terminated Postcodes" ], "summary": "Terminated Postcodes", - "description": "### Terminated Postcode Data (Ordnance Survey Postcode Directory Dataset)\n\nLookup a terminated postcode. Returns the postcode, year and month of termination. Returns 404 if postcode does not exist in our database of terminated postcodes or not valid.\n", + "description": "Lookup a terminated postcode. \n\nIf the terminated postcode exists, this API returns the date of termination and last known geospatial coordinates. \n\nReturns `404` if postcode does not exist in our database of terminated postcodes or not valid.\n\nSource: Ordnance Survey Postcode Directory Dataset\n", "operationId": "TerminatedPostcodes", "parameters": [ { - "name": "query", - "in": "query", - "description": "Specifies the postcode you wish to query", + "name": "postcode", + "in": "path", + "description": "Postcode to query", "required": true, - "style": "form", + "style": "simple", "explode": false, "schema": { "type": "string" @@ -191,26 +447,26 @@ { "lang": "cURL", "label": "CLI", - "source": "curl -G -k \\\n--url 'https://api.postcodes.io/postcodes/E1W1UU'\n" + "source": "curl -G -k \\\n--url 'https://api.postcodes.io/terminated_postcodes/E1W1UU'\n" } ] } }, - "/scottish-postcodes": { + "/scotland/postcodes/{postcode}": { "get": { "tags": [ "Scottish Postcodes" ], "summary": "Scottish Postcodes", - "description": "Lookup a Scottish postcode. Returns SPD data associated with postcode. At the moment this is just Scottish Parliamentary Constituency.\n\nReturns 404 if postcode does not exist in SPD or is not valid. For postcodes not in SPD but in ONSPD, 404 is returned with error message Postcode exists in ONSPD but not in SPD.\n", + "description": "Lookup a Scottish postcode. \n\nReturns Scottish Postcode Directory (SPD) data associated with postcode. At the moment this is just Scottish Parliamentary Constituency.\n\nReturns `404` if postcode does not exist in SPD or is not valid.\n\nFor postcodes not in SPD but in ONSPD, 404 is returned with error message Postcode exists in ONSPD but not in SPD.\n\nSource: Scottish Postcode Directory\n", "operationId": "Scottish Postcodes", "parameters": [ { - "name": "query", - "in": "query", + "name": "postcode", + "in": "path", "description": "Specifies the postcode you wish to query", "required": true, - "style": "form", + "style": "simple", "explode": false, "schema": { "type": "string" @@ -243,21 +499,21 @@ ] } }, - "/outcodes": { + "/outcodes/{outcode}": { "get": { "tags": [ "Outward Code Lookup" ], - "summary": "Find Outcode", - "description": "### Outcode Data (Ordnance Survey Postcode Directory Dataset)\n\nGeolocation data for the centroid of the outward code specified. The outward code represents the first half of any postcode (separated by a space).\n", - "operationId": "FindPlace", + "summary": "Outcode Lookup", + "description": "Returns aggregated information for postcodes grouped by their shared outward code.\n\nThe outward code is the first half of any postcode (3-4 characters and preceded by a space).\n", + "operationId": "FindOutcode", "parameters": [ { - "name": "query", - "in": "query", + "name": "outcode", + "in": "path", "description": "Specifies the outward code you wish to query.", "required": true, - "style": "form", + "style": "simple", "explode": false, "schema": { "type": "string" @@ -286,30 +542,38 @@ "lang": "cURL", "label": "CLI", "source": "curl -G -k \\\n --url 'https://api.postcodes.io/outcodes/sw1a'\n" + }, + { + "lang": "http", + "label": "Nearest URL", + "source": "https://api.postcodes.io/outcodes?lon=-0.127695&lat=51.50354\n" + }, + { + "lang": "cURL", + "label": "Nearest CLI", + "source": "curl -G -k \\\n--url 'https://api.postcodes.io/outcodes?lon=-0.127695&lat=51.50354'\n" } ] } }, - "/reverse-geocoding": { + "/places/{code}": { "get": { "tags": [ - "Reverse Geocoding" + "Place Search" ], - "summary": "Reverse Geocoding", - "operationId": "Reverse", - "description": "Returns nearest postcodes for a given longitude and latitude.\n", + "summary": "Find Place", + "description": "Submit a place query and receive a complete list of places matches and associated data.\n\nThis API uses the Ordnance Survey Open Names Dataset. Places not available for Northern Ireland.\n", + "operationId": "FindPlace", "parameters": [ { - "name": "longitude", + "name": "code", "in": "path", - "description": "Geographic coordinate that specifies the east–west position of a point", + "description": "Specifies the place you wish to query", "required": true, "style": "simple", "explode": false, "schema": { - "title": "Postcode", - "description": "Postcode to query", - "example": "SW1A 2AA" + "type": "string" } } ], @@ -319,7 +583,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PostcodeResponse" + "$ref": "#/components/schemas/PlaceResponse" } } } @@ -329,45 +593,113 @@ { "lang": "http", "label": "URL", - "source": "https://api.postcodes.io/postcodes/SW1A2AA\n" + "source": "https://api.postcodes.io/places/osgb4000000074813508\n" }, { "lang": "cURL", "label": "CLI", - "source": "curl -G -k \\\n--url 'https://api.postcodes.io/postcodes/SW1A2AA'\n" + "source": "curl -k -G 'https://api.postcodes.io/places/osgb4000000074813508' \n" } ] } - } - }, - "components": { - "schemas": { - "Postcode": { - "required": [ - "postcode", - "outcode", - "incode", - "quality", - "eastings", - "northings", - "country", - "nhs_ha", - "admin_county", - "admin_district", - "admin_ward", - "longitude", - "latitude", - "parliamentary_constituency", - "european_electoral_region", - "primary_care_trust", - "region", - "parish", - "lsoa", - "msoa", - "ced", - "ccg", - "nuts", - "codes" + }, + "/places": { + "get": { + "tags": [ + "Place Query" + ], + "summary": "Place Query", + "description": "Submit a place query and receive a complete list of places matches and associated data.", + "operationId": "Place Query", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PlaceResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "http", + "label": "URL", + "source": "https://api.postcodes.io/places?query=welshpool\n" + }, + { + "lang": "cURL", + "label": "CLI", + "source": "curl -k -G 'https://api.postcodes.io/places' \\\n --data-urlencode 'query=welshpool'\n" + } + ] + } + }, + "/random/places": { + "get": { + "tags": [ + "Random Place" + ], + "summary": "Random Place", + "description": "Returns a random place and all associated data", + "operationId": "Random Place", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PlaceResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "http", + "label": "URL", + "source": "https://api.postcodes.io/random/places\n" + }, + { + "lang": "cURL", + "label": "CLI", + "source": "curl -k -G 'https://api.postcodes.io/random/places/' \n" + } + ] + } + } + }, + "components": { + "schemas": { + "Postcode": { + "required": [ + "postcode", + "outcode", + "incode", + "quality", + "eastings", + "northings", + "country", + "nhs_ha", + "admin_county", + "admin_district", + "admin_ward", + "longitude", + "latitude", + "parliamentary_constituency", + "european_electoral_region", + "primary_care_trust", + "region", + "parish", + "lsoa", + "msoa", + "ced", + "ccg", + "nuts", + "codes" ], "properties": { "postcode": { @@ -391,22 +723,24 @@ "quality": { "title": "Positional Quality", "type": "integer", - "description": "Shows the status of the assigned grid reference.\n1 = within the building of the matched address closest to the postcode mean\n2 = as for status value 1, except by visual inspection of Landline maps (Scotland only)\n3 = approximate to within 50m\n4 = postcode unit mean (mean of matched addresses with the same postcode, but not snapped to a building)\n5 = imputed by ONS, by reference to surrounding postcode grid references\n6 = postcode sector mean, (mainly | PO Boxes)\n8 = postcode terminated prior to Gridlink® initiative, last known ONS postcode grid reference1\n9 = no grid reference available", + "description": "Shows the status of the assigned grid reference.\n\n1 = within the building of the matched address closest to the postcode mean\n\n2 = as for status value 1, except by visual inspection of Landline maps (Scotland only)\n\n3 = approximate to within 50m\n\n4 = postcode unit mean (mean of matched addresses with the same postcode, but not snapped to a building)\n\n5 = imputed by ONS, by reference to surrounding postcode grid references\n\n6 = postcode sector mean, (mainly | PO Boxes)\n\n8 = postcode terminated prior to Gridlink® initiative, last known ONS postcode grid reference1\n\n9 = no grid reference available\n", "example": "1" }, "eastings": { "title": "Eastings", "type": "integer", + "format": "int32", "x-nullable": true, "description": "The Ordnance Survey postcode grid reference Easting to 1 metre resolution. Grid references for postcodes in Northern Ireland relate to the Irish Grid system. May be null if geolocation not available.", - "example": "530047" + "example": 530047 }, "northings": { "title": "Northings", "type": "integer", + "format": "int32", "x-nullable": true, "description": "The Ordnance Survey postcode grid reference Northing to 1 metre resolution. Grid references for postcodes in Northern Ireland relate to the Irish Grid system. May be null if geolocation not available.", - "example": "179951" + "example": 179951 }, "country": { "title": "Country", @@ -414,7 +748,7 @@ "description": "The country (i.e. one of the four constituent countries of the United Kingdom or the Channel Islands or the Isle of Man) to which each postcode is assigned.", "example": "England" }, - "nha_ha": { + "nhs_ha": { "title": "Strategic Health Authority", "type": "string", "x-nullable": true, @@ -444,17 +778,19 @@ }, "longitude": { "title": "Longitude", - "type": "double float", + "type": "number", + "format": "double", "x-nullable": true, "description": "The WGS84 longitude given the Postcode's national grid reference. May be null if geolocation not available.", - "example": "-0.12767" + "example": -0.12767 }, "latitude": { "title": "Latitude", - "type": "double float", + "type": "number", + "format": "double", "x-nullable": true, "description": "The WGS84 latitude given the Postcode's national grid reference. May be null if geolocation not available.", - "example": "51.503541" + "example": 51.503541 }, "parliamentary_constituency": { "title": "Westminster Parliamentary Constituency", @@ -510,7 +846,7 @@ "type": "string", "x-nullable": true, "description": "The county electoral division code for each English postcode. Pseudo codes are included for the remainder of the UK. The field will be null for English postcodes with no grid reference. English county councils use county electoral divisions (CED) to elect councillors. These CEDs must be confined within district boundaries, but need not be based on whole electoral wards. The only exceptions are the Isles of Scilly and the Greater London Authority (GLA). CEDs do not exist within UAs.", - "example": "" + "example": null }, "ccg": { "title": "Clinical Commissioning Group", @@ -612,6 +948,30 @@ } } }, + "NearestPostcode": { + "title": "Geolocated Postcode", + "description": "Standard postcode object extended with a distance attribute, indicating how far the postcode is from a supplied geolocation.", + "allOf": [ + { + "$ref": "#/components/schemas/Postcode" + }, + { + "type": "object", + "required": [ + "display" + ], + "properties": { + "distance": { + "title": "Distance from supplied geolocation", + "type": "number", + "format": "double", + "description": "Distance in metres from specified postcode", + "example": 0 + } + } + } + ] + }, "PostcodeResponse": { "title": "Postcode Response", "type": "object", @@ -633,199 +993,13 @@ "oneOf": [ { "$ref": "#/components/schemas/Postcode" - } - ] - }, - "description": "Data for a given postcode" - } - } - }, - "Place": { - "title": "Place", - "description": "Represents a geographical place", - "required": [ - "code", - "name_1", - "name_1_lang", - "name_2", - "name_2_lang", - "local_type", - "outcode", - "county_unitary", - "county_unitary_type", - "district_borough", - "region", - "country", - "longitude", - "latitude", - "eastings", - "northings", - "min_eastings", - "min_northings", - "max_eastings", - "max_northings" - ], - "properties": { - "code": { - "title": "Code", - "type": "string", - "description": "A unique identifier that enables records to be identified easily. The identifier will be persistent for all LocalTypes except Section of Named Road and Section of Numbered Road.", - "example": "osgb4000000074559833" - }, - "name_1": { - "title": "Name", - "type": "string", - "description": "The proper noun that applies to the real world entity. Names that are prefixed by the definite article are not formatted for alphabetical sorting, that is, 'The Pennines' not 'Pennines, The'.", - "example": "Y Trallwng" - }, - "name_1_lang": { - "title": "Language of Name", - "type": "string", - "x-nullable": true, - "description": "The language type is only set where more than one name exists, e.g. cym (Welsh), eng (English), gla (Scottish Gaelic).", - "example": "cym" - }, - "name_2": { - "title": "Name (in case of multiple languages)", - "type": "string", - "x-nullable": true, - "description": "The proper noun that applies to the real world entity. Names that are prefixed by the definite article are not formatted for alphabetical sorting, that is, 'The Pennines' not 'Pennines, The'.", - "example": "Welshpool" - }, - "name_2_lang": { - "title": "Language of Name", - "type": "string", - "x-nullable": true, - "description": "The language type is only set where more than one name exists, e.g. cym (Welsh), eng (English), gla (Scottish Gaelic).", - "example": "eng" - }, - "local_type": { - "title": "Local Type", - "type": "string", - "description": "The Ordnance Survey classification for the named place being represented by the specific feature, e.g. City, Town, Village, Hamlet, Other Settlement, Suburban Area.", - "example": "Hamlet" - }, - "outcode": { - "title": "Outcode", - "type": "string", - "description": "The postcode district.", - "example": "BH24" - }, - "county_unitary": { - "title": "Administrative Area", - "type": "string", - "x-nullable": true, - "description": "The name of the County (non-metropolitan or Metropolitan), Unitary Authority or Greater London Authority administrative area that the point geometry for feature is within or nearest to.", - "example": "Powys - Powys" - }, - "county_unitary_type": { - "title": "Administrative Area Type", - "type": "string", - "x-nullable": true, - "description": "Classifies the type of administrative unit.", - "example": "UnitaryAuthority" - }, - "district_borough": { - "title": "District or Borough", - "type": "string", - "x-nullable": true, - "description": "The name of the District, Metropolitan District or London Borough administrative unit that the point geometry for the feature is within.", - "example": "null" - }, - "district_borough_type": { - "title": "Borough Type", - "type": "string", - "x-nullable": true, - "description": "Classifies the type of administrative unit.", - "example": "null" - }, - "region": { - "title": "Region", - "type": "string", - "description": "The name of the European Region (was Government O ice Region) that the point geometry for the feature is within or nearest to.", - "example": "Wales" - }, - "country": { - "title": "Country", - "type": "string", - "description": "OS Places relates to Great Britain only. i.e. England, Scotland, Wales.", - "example": "Wales" - }, - "longitude": { - "title": "Longitude", - "type": "double float", - "description": "The WGS84 longitude given the Place's national grid reference.", - "example": "-3.14971194307843" - }, - "latitude": { - "title": "Latitude", - "type": "double float", - "description": "The WGS84 latitude given the Place's national grid reference.", - "example": "52.6606391732959" - }, - "eastings": { - "title": "Eastings", - "type": "integer", - "description": "The Ordnance Survey postcode grid reference Easting to 1 metre resolution; blank for postcodes in the Channel Islands and the Isle of Man.", - "example": "322335" - }, - "northings": { - "title": "Northings", - "type": "integer", - "description": "The Ordnance Survey postcode grid reference Northing to 1 metre resolution; blank for postcodes in the Channel Islands and the Isle of Man.", - "example": "307611" - }, - "min_eastings": { - "title": "Minimum Eastings", - "type": "integer", - "description": "Bounding box or Minimum Bounding Rectangle (MBR) for roads and settlements. For Settlements and Sections of Named and Numbered Roads, the MBR gives a representation of the extent of these features and is not snapped to the real world extent.", - "example": "321623" - }, - "min_northings": { - "title": "Minimum Northings", - "type": "integer", - "description": "Bounding box or Minimum Bounding Rectangle (MBR) for roads and settlements. For Settlements and Sections of Named and Numbered Roads, the MBR gives a representation of the extent of these features and is not snapped to the real world extent.", - "example": "306458" - }, - "max_eastings": { - "title": "Maximum Eastings", - "type": "integer", - "description": "Bounding box or Minimum Bounding Rectangle (MBR) for roads and settlements. For Settlements and Sections of Named and Numbered Roads, the MBR gives a representation of the extent of these features and is not snapped to the real world extent.", - "example": "323592" - }, - "max_northings": { - "title": "Maximum Northings", - "type": "integer", - "description": "Bounding box or Minimum Bounding Rectangle (MBR) for roads and settlements. For Settlements and Sections of Named and Numbered Roads, the MBR gives a representation of the extent of these features and is not snapped to the real world extent.", - "example": "308740" - } - } - }, - "PlaceResponse": { - "title": "Places Response", - "type": "object", - "required": [ - "status", - "result" - ], - "properties": { - "status": { - "type": "integer", - "format": "int32", - "enum": [ - 200 - ] - }, - "result": { - "type": "array", - "items": { - "oneOf": [ + }, { - "$ref": "#/components/schemas/Place" + "$ref": "#/components/schemas/NearestPostcode" } ] }, - "description": "Data for a given place" + "description": "Data for a given postcode" } } }, @@ -846,27 +1020,31 @@ }, "year_terminated": { "title": "Termination year", - "type": "integer", + "type": "number", + "format": "int32", "description": "Termination year.", - "example": "2019" + "example": 2019 }, "month_terminated": { "title": "Termination month", - "type": "integer", + "type": "number", + "format": "int32", "description": "Month of termination of a postcode. 1-January, 2-February ... 12-December.", - "example": "1" + "example": 1 }, "longitude": { "title": "Longitude", - "type": "double float", + "type": "number", + "format": "double", "description": "The WGS84 longitude given the Postcode's national grid reference.", - "example": "-2.49690382054704" + "example": -2.496903 }, "latitude": { "title": "Latitude", - "type": "double float", + "type": "number", + "format": "double", "description": "The WGS84 latitude given the Postcode's national grid reference.", - "example": "53.5351312861402" + "example": 53.53513 } } }, @@ -982,61 +1160,278 @@ }, "eastings": { "title": "Eastings", - "type": "integer|null", + "type": "number", + "format": "int32", + "x-nullable": true, "description": "The Ordnance Survey postcode grid reference Easting to 1 metre resolution; blank for postcodes in the Channel Islands and the Isle of Man. Grid references for postcodes in Northern Ireland relate to the Irish Grid system. Computed as the arithmetic mean of the input coordinates. Returns 0 if geolocation is not available.", - "example": "529740" + "example": 529740 }, "northings": { "title": "Northings", - "type": "integer|null", + "type": "number", + "format": "int32", "description": "The Ordnance Survey postcode grid reference Northing to 1 metre resolution; blank for postcodes in the Channel Islands and the Isle of Man. Grid references for postcodes in Northern Ireland relate to the Irish Grid system. Computed as the arithmetic mean of the input coordinates. Returns 0 if geolocation is not available.", - "example": "180066" + "example": 180066 }, "admin_county": { "title": "County", - "type": "string[]", + "type": "array", + "items": { + "type": "string" + }, "description": "The current counties under the outcode.", - "example": "" + "example": [] }, "admin_district": { "title": "District", - "type": "string[]", + "type": "array", + "items": { + "type": "string" + }, "description": "The current district/unitary authorites under the outcode.", - "example": "[\n \"Westminster\",\n \"Wandsworth\"\n]" + "example": [ + "Westminster", + "Wandsworth" + ] }, "admin_ward": { "title": "Ward", - "type": "string[]", + "type": "array", + "items": { + "type": "string" + }, "description": "The current administrative/electoral areas under the outcode.", - "example": "[\n \"Nine Elms\",\n \"St. James's\"\n]" + "example": [ + "Nine Elms", + "St. James's" + ] }, "longitude": { "title": "Longitude", - "type": "double float | null", + "type": "number", + "format": "double", "description": "The WGS84 longitude given the Postcode's national grid reference. Computed as the arithmetic mean of input coordinates. May be null if geolocation not available.", - "example": "-0.132066678082192" + "example": -0.132066 }, "latitude": { "title": "Latitude", - "type": "double float | null", + "type": "number", + "format": "double", "description": "The WGS84 latitude given the Postcode's national grid reference. Computed as the arithmetic mean of input coordinates. May be null if geolocation not available.", - "example": "51.5046429726028" + "example": 51.50464 }, "country": { "title": "Country", - "type": "string[]", + "type": "array", + "items": { + "type": "string" + }, "description": "The countries included in the outcode.", "example": "England" }, "parish": { "title": "Parish (England)/community (Wales)", - "type": "string[]", + "type": "array", + "items": { + "type": "string" + }, "description": "The parishes included in the outcode.", - "example": "[\n \"Wandsworth, unparished area\",\n \"Westminster, unparished area\"\n]," + "example": [ + "Wandsworth, unparished area", + "Westminster, unparished area" + ] } } }, "OutcodeResponse": { + "title": "Places Response", + "type": "object", + "required": [ + "status", + "result" + ], + "properties": { + "status": { + "type": "integer", + "format": "int32", + "enum": [ + 200 + ] + }, + "result": { + "oneOf": [ + { + "$ref": "#/components/schemas/Outcode" + } + ], + "description": "Data for a given place" + } + } + }, + "Place": { + "title": "Place", + "description": "Represents a geographical place", + "required": [ + "code", + "name_1", + "name_1_lang", + "name_2", + "name_2_lang", + "local_type", + "outcode", + "county_unitary", + "county_unitary_type", + "district_borough", + "region", + "country", + "longitude", + "latitude", + "eastings", + "northings", + "min_eastings", + "min_northings", + "max_eastings", + "max_northings" + ], + "properties": { + "code": { + "title": "Code", + "type": "string", + "description": "A unique identifier that enables records to be identified easily. The identifier will be persistent for all LocalTypes except Section of Named Road and Section of Numbered Road.", + "example": "osgb4000000074559833" + }, + "name_1": { + "title": "Name", + "type": "string", + "description": "The proper noun that applies to the real world entity. Names that are prefixed by the definite article are not formatted for alphabetical sorting, that is, 'The Pennines' not 'Pennines, The'.", + "example": "Y Trallwng" + }, + "name_1_lang": { + "title": "Language of Name", + "type": "string", + "x-nullable": true, + "description": "The language type is only set where more than one name exists, e.g. cym (Welsh), eng (English), gla (Scottish Gaelic).", + "example": "cym" + }, + "name_2": { + "title": "Name (in case of multiple languages)", + "type": "string", + "x-nullable": true, + "description": "The proper noun that applies to the real world entity. Names that are prefixed by the definite article are not formatted for alphabetical sorting, that is, 'The Pennines' not 'Pennines, The'.", + "example": "Welshpool" + }, + "name_2_lang": { + "title": "Language of Name", + "type": "string", + "x-nullable": true, + "description": "The language type is only set where more than one name exists, e.g. cym (Welsh), eng (English), gla (Scottish Gaelic).", + "example": "eng" + }, + "local_type": { + "title": "Local Type", + "type": "string", + "description": "The Ordnance Survey classification for the named place being represented by the specific feature, e.g. City, Town, Village, Hamlet, Other Settlement, Suburban Area.", + "example": "Hamlet" + }, + "outcode": { + "title": "Outcode", + "type": "string", + "description": "The postcode district.", + "example": "BH24" + }, + "county_unitary": { + "title": "Administrative Area", + "type": "string", + "x-nullable": true, + "description": "The name of the County (non-metropolitan or Metropolitan), Unitary Authority or Greater London Authority administrative area that the point geometry for feature is within or nearest to.", + "example": "Powys - Powys" + }, + "county_unitary_type": { + "title": "Administrative Area Type", + "type": "string", + "x-nullable": true, + "description": "Classifies the type of administrative unit.", + "example": "UnitaryAuthority" + }, + "district_borough": { + "title": "District or Borough", + "type": "string", + "x-nullable": true, + "description": "The name of the District, Metropolitan District or London Borough administrative unit that the point geometry for the feature is within.", + "example": "null" + }, + "district_borough_type": { + "title": "Borough Type", + "type": "string", + "x-nullable": true, + "description": "Classifies the type of administrative unit.", + "example": "null" + }, + "region": { + "title": "Region", + "type": "string", + "description": "The name of the European Region (was Government O ice Region) that the point geometry for the feature is within or nearest to.", + "example": "Wales" + }, + "country": { + "title": "Country", + "type": "string", + "description": "OS Places relates to Great Britain only. i.e. England, Scotland, Wales.", + "example": "Wales" + }, + "longitude": { + "title": "Longitude", + "type": "number", + "format": "double", + "description": "The WGS84 longitude given the Place's national grid reference.", + "example": "-3.14971194307843" + }, + "latitude": { + "title": "Latitude", + "type": "number", + "format": "double", + "description": "The WGS84 latitude given the Place's national grid reference.", + "example": "52.6606391732959" + }, + "eastings": { + "title": "Eastings", + "type": "integer", + "description": "The Ordnance Survey postcode grid reference Easting to 1 metre resolution; blank for postcodes in the Channel Islands and the Isle of Man.", + "example": "322335" + }, + "northings": { + "title": "Northings", + "type": "integer", + "description": "The Ordnance Survey postcode grid reference Northing to 1 metre resolution; blank for postcodes in the Channel Islands and the Isle of Man.", + "example": "307611" + }, + "min_eastings": { + "title": "Minimum Eastings", + "type": "integer", + "description": "Bounding box or Minimum Bounding Rectangle (MBR) for roads and settlements. For Settlements and Sections of Named and Numbered Roads, the MBR gives a representation of the extent of these features and is not snapped to the real world extent.", + "example": "321623" + }, + "min_northings": { + "title": "Minimum Northings", + "type": "integer", + "description": "Bounding box or Minimum Bounding Rectangle (MBR) for roads and settlements. For Settlements and Sections of Named and Numbered Roads, the MBR gives a representation of the extent of these features and is not snapped to the real world extent.", + "example": "306458" + }, + "max_eastings": { + "title": "Maximum Eastings", + "type": "integer", + "description": "Bounding box or Minimum Bounding Rectangle (MBR) for roads and settlements. For Settlements and Sections of Named and Numbered Roads, the MBR gives a representation of the extent of these features and is not snapped to the real world extent.", + "example": "323592" + }, + "max_northings": { + "title": "Maximum Northings", + "type": "integer", + "description": "Bounding box or Minimum Bounding Rectangle (MBR) for roads and settlements. For Settlements and Sections of Named and Numbered Roads, the MBR gives a representation of the extent of these features and is not snapped to the real world extent.", + "example": "308740" + } + } + }, + "PlaceResponse": { "title": "Places Response", "type": "object", "required": [ @@ -1056,7 +1451,7 @@ "items": { "oneOf": [ { - "$ref": "#/components/schemas/Outcode" + "$ref": "#/components/schemas/Place" } ] }, diff --git a/public/openapi.yaml b/public/openapi.yaml index 42fadb1f..aa794c09 100644 --- a/public/openapi.yaml +++ b/public/openapi.yaml @@ -2,30 +2,37 @@ openapi: 3.0.3 info: version: 3.5.1 license: - name: AGPLv3 - url: https://opensource.org/licenses/AGPL-3.0 + name: MIT + url: https://opensource.org/licenses/MIT title: API Reference - Postcodes.io termsOfService: https://postcodes.io/about - description: >- + description: > # Overview - Postcodes.io is a free postcode lookup API and geocoder for the UK + Postcodes.io is a free postcode lookup API and geocoder for the UK. ## Endpoint - All services can be accessed from the following HTTP[S] endpoint + All services can be accessed from the following endpoint. + + + ``` + + https://api.postcodes.io + + ``` - `https://api.postcodes.io` The API accepts GET and POST requests. POST methods use content type - application/json + `application/json`. ## Responses + JSON(P) only. CORS is enabled. @@ -37,19 +44,8 @@ info: ## Authentication - Postcodes.io does not require any authentication. - - - ## Versioning - - The API currently does not use any form of versioning. Any changes to the - API will be backwards-compatible, this includes: adding new properties to - responses, adding new endpoints, adding new optional request parameters and - changing the order of properties. - - If we make backwards-incompatible changes in the future, this will be - released under a versioned endpoint. + Postcodes.io does not require authentication. contact: email: support@ideal-postcodes.co.uk name: Support @@ -63,19 +59,28 @@ servers: variables: {} tags: - name: Postcode Lookup - description: Search for UK postcodes + - name: Postcode Query + - name: Nearest Postcode + - name: Random Postcode + - name: Terminated Postcodes + - name: Scottish Postcode Search - name: Outward Postcodes - description: Search by UK outward codes - - name: Places Search - description: Search UK places + - name: Place Search + - name: Place Query + - name: Random Place x-tagGroups: - name: API tags: - Postcode Lookup - - Place Search + - Postcode Query + - Nearest Postcode + - Random Postcode - Terminated Postcodes - Scottish Postcodes - Outward Code Lookup + - Place Search + - Place Query + - Random Place paths: /postcodes/{postcode}: get: @@ -120,66 +125,327 @@ paths: source: | curl -G -k \ --url 'https://api.postcodes.io/postcodes/SW1A2AA' - /places: + /postcodes: get: tags: - - Place Search - summary: Find Place + - Postcode Query + summary: Postcode Query + operationId: Postcode Query description: > - ### Places Data (Ordnance Survey Open Names Dataset) + Query for a postcode either by: - Submit a place query and receive a complete list of places matches and - associated data.ind a place by OSGB code (e.g. "osgb4000000074564391"). - Returns all available data if found. Returns 404 if place does not - exist. - operationId: FindPlace + - The postcode itself (with `postcode=`) or by, + + - A geolocation (`lat=` and `lon=`). + + + ## Query with Postcode + + + Submit a postcode query and receive a complete list of postcode matches + and all associated postcode data. This is triggered when `query=` is + supplied. + + + This is essentially a postcode search which prefix matches and returns + postcodes in sorted order (case insensitive) + + + This method is space sensitive, i.e. it detects for spaces between + outward and inward parts of the postcode (some examples detailed in this + [issue](https://github.com/ideal-postcodes/postcodes.io/issues/44)) + + + The result set can either be empty or populated with up to 100 postcode + entities. Either way it will always return a 200 response code + + + ## Query with Geolocation + + + Returns nearest postcodes for a given longitude and latitude. This is + triggered when `lat=` and `lon=` is supplied. parameters: - name: query in: query - description: Specifies the place you wish to query + style: form + explode: false + schema: + description: Postcode to query. Aliases to `q=` + example: SW1A 2AA + - name: limit + in: query + style: form + explode: false + schema: + default: 10 + maximum: 100 + minimum: 1 + description: >- + PLimits number of postcodes matches to return. Defaults to 10. + Needs to be less than 100. + example: 3 + - name: longitude + in: query + style: form + explode: false + schema: + title: Longitude + type: number + format: double + description: >- + Geographic coordinate that specifies the east-west position of a + point + example: -0.127695 + maximum: 180 + minimum: -180 + - name: latitude + in: query + style: form + explode: false + schema: + title: Latitude + type: number + format: double + description: >- + Geographic coordinate that specifies the north-south position of a + point + example: 51.50354 + maximum: 90 + minimum: -90 + - name: radius + in: query + style: form + explode: false + schema: + title: Radius + type: integer + description: >- + Limits number of postcodes matches to return. Defaults to 100m. + Needs to be less than 2,000m. + example: 500 + default: 100 + maximum: 2000 + minimum: 1 + - name: widesearch + in: query + style: form + explode: false + schema: + title: Widesearch + type: boolean + description: >- + Search up to 20km radius, but subject to a maximum of 10 results. + Since lookups over a wide area can be very expensive, we've + created this method to allow you choose to make the trade off + between search radius and number of results. Defaults to false. + When enabled, radius and limits over 10 are ignored. + example: 'true' + default: 'false' + - name: filter + in: query + style: form + explode: false + schema: + title: Filter + type: string + description: >- + A comma separated whitelist of attributes to be returned in the + result object(s), e.g. filter=postcode,longitude,latitude. null + responses will continue to return null. If no attributes match the + result object, an empty object is returned + example: postcode + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/PostcodeResponse' + x-codeSamples: + - lang: http + label: Query URL + source: | + https://api.postcodes.io/postcodes/SW1A2AA + - lang: cURL + label: Query CLI + source: | + curl -G -k \ + --url 'https://api.postcodes.io/postcodes/SW1A2AA' + - lang: http + label: Nearest URL + source: | + https://api.postcodes.io/postcodes?lon=-0.127695&lat=51.50354 + - lang: cURL + label: Nearest CLI + source: > + curl -G -k \ + + --url + 'https://api.postcodes.io/postcodes?lon=-0.127695&lat=51.50354' + post: + tags: + - Postcode Query + summary: Bulk Postcode Lookup + operationId: Bulk Postcode Lookup + description: > + Accepts a JSON object containing an array of postcodes. Returns a list + of matching postcodes and respective available data. + + + Be sure to submit JSON requests setting `Content-Type` to + `application/json` + + + Accepts up to 100 postcodes. + + + ### Post Data + + + This method requires a JSON object containing an array of postcodes to + be posted, e.g. + + + ```json + + { + "postcodes": ["PR3 0SG", "M45 6GN", "EX165BL"] + } + + ``` + + + ## Bulk Reverse Geocoding + + + Bulk translates geolocations into Postcodes. Accepts up to 100 + geolocations. + parameters: [] + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/PostcodeResponse' + x-codeSamples: + - lang: http + label: Query URL + source: | + https://api.postcodes.io/postcodes/ + - lang: cURL + label: Query CLI + source: | + curl -G -k \ + --url 'https://api.postcodes.io/postcodes/' + - lang: http + label: Nearest URL + source: | + https://api.postcodes.io/postcodes? + - lang: cURL + label: Nearest CLI + source: | + curl -G -k \ + --url 'https://api.postcodes.io/postcodes?' + /postcodes/{postcode}/nearest: + get: + tags: + - Nearest Postcode + summary: Lookup Nearest Postcodes + operationId: Nearest Postcode + description: Returns nearest postcodes for a given postcode. + parameters: + - name: postcode + in: path + description: Postcode to retrieve required: true + style: simple + explode: false + schema: + title: Postcode + description: Postcode to query + example: SW1A 2AA + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/PostcodeResponse' + x-codeSamples: + - lang: http + label: URL + source: | + https://api.postcodes.io/postcodes/SW1A2AA + - lang: cURL + label: CLI + source: | + curl -G -k \ + --url 'https://api.postcodes.io/postcodes/SW1A2AA' + /random/postcodes: + get: + tags: + - Random Postcode + summary: Random Postcode + operationId: Random Postcode + description: Returns a random postcode and all available data for that postcode. + parameters: + - name: outcode + in: query + description: >- + Filters random postcodes by outcode. Returns null if invalid + outcode. style: form explode: false schema: + title: Outward code + description: Restrict results to a specific outward code type: string + example: SW1A responses: '200': description: Success content: application/json: schema: - $ref: '#/components/schemas/PlaceResponse' + $ref: '#/components/schemas/PostcodeResponse' x-codeSamples: - lang: http label: URL source: | - https://api.postcodes.io/places?query=welshpool + https://api.postcodes.io/random/postcodes - lang: cURL label: CLI source: | - curl -k -G 'https://api.postcodes.io/places' \ - --data-urlencode 'query=welshpool' - /terminated-postcodes: + curl -G -k \ + --url 'https://api.postcodes.io/random/postcodes' + /terminated_postcodes/{postcode}: get: tags: - Terminated Postcodes summary: Terminated Postcodes description: > - ### Terminated Postcode Data (Ordnance Survey Postcode Directory - Dataset) + Lookup a terminated postcode. + + + If the terminated postcode exists, this API returns the date of + termination and last known geospatial coordinates. - Lookup a terminated postcode. Returns the postcode, year and month of - termination. Returns 404 if postcode does not exist in our database of - terminated postcodes or not valid. + Returns `404` if postcode does not exist in our database of terminated + postcodes or not valid. + + + Source: Ordnance Survey Postcode Directory Dataset operationId: TerminatedPostcodes parameters: - - name: query - in: query - description: Specifies the postcode you wish to query + - name: postcode + in: path + description: Postcode to query required: true - style: form + style: simple explode: false schema: type: string @@ -199,27 +465,35 @@ paths: label: CLI source: | curl -G -k \ - --url 'https://api.postcodes.io/postcodes/E1W1UU' - /scottish-postcodes: + --url 'https://api.postcodes.io/terminated_postcodes/E1W1UU' + /scotland/postcodes/{postcode}: get: tags: - Scottish Postcodes summary: Scottish Postcodes description: > - Lookup a Scottish postcode. Returns SPD data associated with postcode. + Lookup a Scottish postcode. + + + Returns Scottish Postcode Directory (SPD) data associated with postcode. At the moment this is just Scottish Parliamentary Constituency. - Returns 404 if postcode does not exist in SPD or is not valid. For - postcodes not in SPD but in ONSPD, 404 is returned with error message - Postcode exists in ONSPD but not in SPD. + Returns `404` if postcode does not exist in SPD or is not valid. + + + For postcodes not in SPD but in ONSPD, 404 is returned with error + message Postcode exists in ONSPD but not in SPD. + + + Source: Scottish Postcode Directory operationId: Scottish Postcodes parameters: - - name: query - in: query + - name: postcode + in: path description: Specifies the postcode you wish to query required: true - style: form + style: simple explode: false schema: type: string @@ -240,25 +514,25 @@ paths: source: | curl -G -k \ --url 'https://api.postcodes.io/scotland/postcodes/IV27JB' - /outcodes: + /outcodes/{outcode}: get: tags: - Outward Code Lookup - summary: Find Outcode + summary: Outcode Lookup description: > - ### Outcode Data (Ordnance Survey Postcode Directory Dataset) + Returns aggregated information for postcodes grouped by their shared + outward code. - Geolocation data for the centroid of the outward code specified. The - outward code represents the first half of any postcode (separated by a - space). - operationId: FindPlace + The outward code is the first half of any postcode (3-4 characters and + preceded by a space). + operationId: FindOutcode parameters: - - name: query - in: query + - name: outcode + in: path description: Specifies the outward code you wish to query. required: true - style: form + style: simple explode: false schema: type: string @@ -279,44 +553,102 @@ paths: source: | curl -G -k \ --url 'https://api.postcodes.io/outcodes/sw1a' - /reverse-geocoding: + - lang: http + label: Nearest URL + source: | + https://api.postcodes.io/outcodes?lon=-0.127695&lat=51.50354 + - lang: cURL + label: Nearest CLI + source: | + curl -G -k \ + --url 'https://api.postcodes.io/outcodes?lon=-0.127695&lat=51.50354' + /places/{code}: get: tags: - - Reverse Geocoding - summary: Reverse Geocoding - operationId: Reverse - description: | - Returns nearest postcodes for a given longitude and latitude. + - Place Search + summary: Find Place + description: > + Submit a place query and receive a complete list of places matches and + associated data. + + + This API uses the Ordnance Survey Open Names Dataset. Places not + available for Northern Ireland. + operationId: FindPlace parameters: - - name: longitude + - name: code in: path - description: >- - Geographic coordinate that specifies the east–west position of a - point + description: Specifies the place you wish to query required: true style: simple explode: false schema: - title: Postcode - description: Postcode to query - example: SW1A 2AA + type: string responses: '200': description: Success content: application/json: schema: - $ref: '#/components/schemas/PostcodeResponse' + $ref: '#/components/schemas/PlaceResponse' x-codeSamples: - lang: http label: URL source: | - https://api.postcodes.io/postcodes/SW1A2AA + https://api.postcodes.io/places/osgb4000000074813508 - lang: cURL label: CLI source: | - curl -G -k \ - --url 'https://api.postcodes.io/postcodes/SW1A2AA' + curl -k -G 'https://api.postcodes.io/places/osgb4000000074813508' + /places: + get: + tags: + - Place Query + summary: Place Query + description: >- + Submit a place query and receive a complete list of places matches and + associated data. + operationId: Place Query + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/PlaceResponse' + x-codeSamples: + - lang: http + label: URL + source: | + https://api.postcodes.io/places?query=welshpool + - lang: cURL + label: CLI + source: | + curl -k -G 'https://api.postcodes.io/places' \ + --data-urlencode 'query=welshpool' + /random/places: + get: + tags: + - Random Place + summary: Random Place + description: Returns a random place and all associated data + operationId: Random Place + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/PlaceResponse' + x-codeSamples: + - lang: http + label: URL + source: | + https://api.postcodes.io/random/places + - lang: cURL + label: CLI + source: | + curl -k -G 'https://api.postcodes.io/random/places/' components: schemas: Postcode: @@ -375,48 +707,58 @@ components: quality: title: Positional Quality type: integer - description: >- + description: > Shows the status of the assigned grid reference. + 1 = within the building of the matched address closest to the postcode mean + 2 = as for status value 1, except by visual inspection of Landline maps (Scotland only) + 3 = approximate to within 50m + 4 = postcode unit mean (mean of matched addresses with the same postcode, but not snapped to a building) + 5 = imputed by ONS, by reference to surrounding postcode grid references + 6 = postcode sector mean, (mainly | PO Boxes) + 8 = postcode terminated prior to Gridlink® initiative, last known ONS postcode grid reference1 + 9 = no grid reference available example: '1' eastings: title: Eastings type: integer + format: int32 x-nullable: true description: >- The Ordnance Survey postcode grid reference Easting to 1 metre resolution. Grid references for postcodes in Northern Ireland relate to the Irish Grid system. May be null if geolocation not available. - example: '530047' + example: 530047 northings: title: Northings type: integer + format: int32 x-nullable: true description: >- The Ordnance Survey postcode grid reference Northing to 1 metre resolution. Grid references for postcodes in Northern Ireland relate to the Irish Grid system. May be null if geolocation not available. - example: '179951' + example: 179951 country: title: Country type: string @@ -425,7 +767,7 @@ components: United Kingdom or the Channel Islands or the Isle of Man) to which each postcode is assigned. example: England - nha_ha: + nhs_ha: title: Strategic Health Authority type: string x-nullable: true @@ -455,20 +797,22 @@ components: example: St. James's longitude: title: Longitude - type: double float + type: number + format: double x-nullable: true description: >- The WGS84 longitude given the Postcode's national grid reference. May be null if geolocation not available. - example: '-0.12767' + example: -0.12767 latitude: title: Latitude - type: double float + type: number + format: double x-nullable: true description: >- The WGS84 latitude given the Postcode's national grid reference. May be null if geolocation not available. - example: '51.503541' + example: 51.503541 parliamentary_constituency: title: Westminster Parliamentary Constituency type: string @@ -542,7 +886,7 @@ components: be based on whole electoral wards. The only exceptions are the Isles of Scilly and the Greater London Authority (GLA). CEDs do not exist within UAs. - example: '' + example: null ccg: title: Clinical Commissioning Group type: string @@ -667,6 +1011,23 @@ components: x-nullable: true description: See description of msoa field. example: E02000977 + NearestPostcode: + title: Geolocated Postcode + description: >- + Standard postcode object extended with a distance attribute, indicating + how far the postcode is from a supplied geolocation. + allOf: + - $ref: '#/components/schemas/Postcode' + - type: object + required: + - display + properties: + distance: + title: Distance from supplied geolocation + type: number + format: double + description: Distance in metres from specified postcode + example: 0 PostcodeResponse: title: Postcode Response type: object @@ -684,7 +1045,238 @@ components: items: oneOf: - $ref: '#/components/schemas/Postcode' + - $ref: '#/components/schemas/NearestPostcode' + description: Data for a given postcode + TerminatedPostcode: + required: + - postcode + - year_terminated + - month_terminated + - longitude + - latitude + properties: + postcode: + title: Postcode + type: string + description: >- + All currently terminated postcodes within the United Kingdom, the + Channel Islands and the Isle of Man, received every 3 months from + Royal Mail. 2, 3 or 4-character outward code, single space and + 3-character inward code. + example: SW1A 2AA + year_terminated: + title: Termination year + type: number + format: int32 + description: Termination year. + example: 2019 + month_terminated: + title: Termination month + type: number + format: int32 + description: >- + Month of termination of a postcode. 1-January, 2-February ... + 12-December. + example: 1 + longitude: + title: Longitude + type: number + format: double + description: The WGS84 longitude given the Postcode's national grid reference. + example: -2.496903 + latitude: + title: Latitude + type: number + format: double + description: The WGS84 latitude given the Postcode's national grid reference. + example: 53.53513 + TerminatedPostcodes: + title: Postcode Response + type: object + required: + - status + - result + properties: + status: + type: integer + format: int32 + enum: + - 200 + result: + type: array + items: + oneOf: + - $ref: '#/components/schemas/TerminatedPostcode' + description: Data for a given postcode + ScottishPostcodes: + required: + - postcode + - scottish_parliamentary_constituency + - codes + properties: + postcode: + title: Postcode + type: string + description: Royal Mail postcode + example: IV2 7JB + scottish_parliamentary_constituency: + title: Scottish Parliamentary Constituency + type: string + description: 2014 Scottish Parliamentary Constituency. + example: Inverness and Nairn + codes: + title: Returns an ID or Code associated with the postcode + description: >- + Typically, these are a 9 character code known as an ONS Code or GSS + Code. + type: object + properties: + scottish_parliamentary_constituency: + title: Scottish Parliamentary Constituency GSS Code + type: string + description: >- + A code that identifies a 2014 Scottish Parliamentary + Constituency. + example: S16000125 + ScottishPostcodes-2: + title: Scottish Postcodes Response + type: object + required: + - status + - result + properties: + status: + type: integer + format: int32 + enum: + - 200 + result: + type: array + items: + oneOf: + - $ref: '#/components/schemas/ScottishPostcodes' description: Data for a given postcode + Outcode: + required: + - outcode + - eastings + - northings + - admin_county + - admin_district + - admin_ward + - longitude + - latitude + - country + - parish + properties: + outcode: + title: Outcode + type: string + description: >- + The outcode or outward code is the part of the postcode before the + single space in the middle. It is between two and four characters + long. Examples of outward codes include "L1", "W1A", "RH1", "RH10" + or "SE1P". A few outward codes are non-geographic, not divulging + where mail is to be sent. + example: SW1A + eastings: + title: Eastings + type: number + format: int32 + x-nullable: true + description: >- + The Ordnance Survey postcode grid reference Easting to 1 metre + resolution; blank for postcodes in the Channel Islands and the Isle + of Man. Grid references for postcodes in Northern Ireland relate to + the Irish Grid system. Computed as the arithmetic mean of the input + coordinates. Returns 0 if geolocation is not available. + example: 529740 + northings: + title: Northings + type: number + format: int32 + description: >- + The Ordnance Survey postcode grid reference Northing to 1 metre + resolution; blank for postcodes in the Channel Islands and the Isle + of Man. Grid references for postcodes in Northern Ireland relate to + the Irish Grid system. Computed as the arithmetic mean of the input + coordinates. Returns 0 if geolocation is not available. + example: 180066 + admin_county: + title: County + type: array + items: + type: string + description: The current counties under the outcode. + example: [] + admin_district: + title: District + type: array + items: + type: string + description: The current district/unitary authorites under the outcode. + example: + - Westminster + - Wandsworth + admin_ward: + title: Ward + type: array + items: + type: string + description: The current administrative/electoral areas under the outcode. + example: + - Nine Elms + - St. James's + longitude: + title: Longitude + type: number + format: double + description: >- + The WGS84 longitude given the Postcode's national grid reference. + Computed as the arithmetic mean of input coordinates. May be null if + geolocation not available. + example: -0.132066 + latitude: + title: Latitude + type: number + format: double + description: >- + The WGS84 latitude given the Postcode's national grid reference. + Computed as the arithmetic mean of input coordinates. May be null if + geolocation not available. + example: 51.50464 + country: + title: Country + type: array + items: + type: string + description: The countries included in the outcode. + example: England + parish: + title: Parish (England)/community (Wales) + type: array + items: + type: string + description: The parishes included in the outcode. + example: + - Wandsworth, unparished area + - Westminster, unparished area + OutcodeResponse: + title: Places Response + type: object + required: + - status + - result + properties: + status: + type: integer + format: int32 + enum: + - 200 + result: + oneOf: + - $ref: '#/components/schemas/Outcode' + description: Data for a given place Place: title: Place description: Represents a geographical place @@ -810,12 +1402,14 @@ components: example: Wales longitude: title: Longitude - type: double float + type: number + format: double description: The WGS84 longitude given the Place's national grid reference. example: '-3.14971194307843' latitude: title: Latitude - type: double float + type: number + format: double description: The WGS84 latitude given the Place's national grid reference. example: '52.6606391732959' eastings: @@ -888,222 +1482,3 @@ components: oneOf: - $ref: '#/components/schemas/Place' description: Data for a given place - TerminatedPostcode: - required: - - postcode - - year_terminated - - month_terminated - - longitude - - latitude - properties: - postcode: - title: Postcode - type: string - description: >- - All currently terminated postcodes within the United Kingdom, the - Channel Islands and the Isle of Man, received every 3 months from - Royal Mail. 2, 3 or 4-character outward code, single space and - 3-character inward code. - example: SW1A 2AA - year_terminated: - title: Termination year - type: integer - description: Termination year. - example: '2019' - month_terminated: - title: Termination month - type: integer - description: >- - Month of termination of a postcode. 1-January, 2-February ... - 12-December. - example: '1' - longitude: - title: Longitude - type: double float - description: The WGS84 longitude given the Postcode's national grid reference. - example: '-2.49690382054704' - latitude: - title: Latitude - type: double float - description: The WGS84 latitude given the Postcode's national grid reference. - example: '53.5351312861402' - TerminatedPostcodes: - title: Postcode Response - type: object - required: - - status - - result - properties: - status: - type: integer - format: int32 - enum: - - 200 - result: - type: array - items: - oneOf: - - $ref: '#/components/schemas/TerminatedPostcode' - description: Data for a given postcode - ScottishPostcodes: - required: - - postcode - - scottish_parliamentary_constituency - - codes - properties: - postcode: - title: Postcode - type: string - description: Royal Mail postcode - example: IV2 7JB - scottish_parliamentary_constituency: - title: Scottish Parliamentary Constituency - type: string - description: 2014 Scottish Parliamentary Constituency. - example: Inverness and Nairn - codes: - title: Returns an ID or Code associated with the postcode - description: >- - Typically, these are a 9 character code known as an ONS Code or GSS - Code. - type: object - properties: - scottish_parliamentary_constituency: - title: Scottish Parliamentary Constituency GSS Code - type: string - description: >- - A code that identifies a 2014 Scottish Parliamentary - Constituency. - example: S16000125 - ScottishPostcodes-2: - title: Scottish Postcodes Response - type: object - required: - - status - - result - properties: - status: - type: integer - format: int32 - enum: - - 200 - result: - type: array - items: - oneOf: - - $ref: '#/components/schemas/ScottishPostcodes' - description: Data for a given postcode - Outcode: - required: - - outcode - - eastings - - northings - - admin_county - - admin_district - - admin_ward - - longitude - - latitude - - country - - parish - properties: - outcode: - title: Outcode - type: string - description: >- - The outcode or outward code is the part of the postcode before the - single space in the middle. It is between two and four characters - long. Examples of outward codes include "L1", "W1A", "RH1", "RH10" - or "SE1P". A few outward codes are non-geographic, not divulging - where mail is to be sent. - example: SW1A - eastings: - title: Eastings - type: integer|null - description: >- - The Ordnance Survey postcode grid reference Easting to 1 metre - resolution; blank for postcodes in the Channel Islands and the Isle - of Man. Grid references for postcodes in Northern Ireland relate to - the Irish Grid system. Computed as the arithmetic mean of the input - coordinates. Returns 0 if geolocation is not available. - example: '529740' - northings: - title: Northings - type: integer|null - description: >- - The Ordnance Survey postcode grid reference Northing to 1 metre - resolution; blank for postcodes in the Channel Islands and the Isle - of Man. Grid references for postcodes in Northern Ireland relate to - the Irish Grid system. Computed as the arithmetic mean of the input - coordinates. Returns 0 if geolocation is not available. - example: '180066' - admin_county: - title: County - type: string[] - description: The current counties under the outcode. - example: '' - admin_district: - title: District - type: string[] - description: The current district/unitary authorites under the outcode. - example: |- - [ - "Westminster", - "Wandsworth" - ] - admin_ward: - title: Ward - type: string[] - description: The current administrative/electoral areas under the outcode. - example: |- - [ - "Nine Elms", - "St. James's" - ] - longitude: - title: Longitude - type: double float | null - description: >- - The WGS84 longitude given the Postcode's national grid reference. - Computed as the arithmetic mean of input coordinates. May be null if - geolocation not available. - example: '-0.132066678082192' - latitude: - title: Latitude - type: double float | null - description: >- - The WGS84 latitude given the Postcode's national grid reference. - Computed as the arithmetic mean of input coordinates. May be null if - geolocation not available. - example: '51.5046429726028' - country: - title: Country - type: string[] - description: The countries included in the outcode. - example: England - parish: - title: Parish (England)/community (Wales) - type: string[] - description: The parishes included in the outcode. - example: |- - [ - "Wandsworth, unparished area", - "Westminster, unparished area" - ], - OutcodeResponse: - title: Places Response - type: object - required: - - status - - result - properties: - status: - type: integer - format: int32 - enum: - - 200 - result: - type: array - items: - oneOf: - - $ref: '#/components/schemas/Outcode' - description: Data for a given place