@ideal-postcodes/openapi

{ "openapi": "3.0.3", "info": { "version": "4.11.0", "license": { "name": "AGPLv3", "url": "https://opensource.org/licenses/AGPL-3.0" }, "title": "API Reference", "termsOfService": "https://terms.ideal-postcodes.co.uk", "description": "## Getting Started\n\nAll API methods are either a `GET`, `POST` or `OPTIONS` request.\n\nThe API communicates over both HTTPS and plain HTTP using IPv4 and IPv6.\n\nWe recommend using HTTPS only although HTTP is available.\n\nWe use appropriate HTTP status codes where possible to indicate the request status.\n\n## OpenAPI Spec\n\nOur OpenAPI specification is available at:\n\n- [Github Repository](https://github.com/ideal-postcodes/openapi)\n- [API Reference](https://openapi.ideal-postcodes.co.uk)\n- [OpenAPI v3 JSON File](https://openapi.ideal-postcodes.co.uk/openapi.json)\n- [OpenAPI v3 YAML File](https://openapi.ideal-postcodes.co.uk/openapi.yaml)\n- [NPM Package](https://www.npmjs.com/package/@ideal-postcodes/openapi)\n\n## Rate Limiting\n\nEach IP address is rate limited at 30 requests per second. Tripping the rate limit will result in a 503 response.\n\nThe autocomplete API also has an additional rate limit.\n\nIf you expect to breach the limit please contact us and we can move you to an endpoint with a higher limit.\n\n## Authentication\n\nMost requests require an **API key** for authentication. Authenticate by passing an `api_key` as part of the query string. For example:\n\n```\napi.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&q=parkside\n```\n\nAlternatively, authentication can be transmitted via the `Authorization` header using the following scheme:\n\n```\nAuthorization: api_key=\"iddqd\" [other_key=\"foo\"]\n```\n\n## Versioning\n\nThis API is versioned with a simple prefix in the URL. The current version is `/v1/`. We will maintain backwards-compatibility by releasing breaking changes under a new version.\n\nPlease note that the following changes are backwards-compatible:\n\n- Adding new properties to existing API responses\n- Adding new API endpoints\n- Adding new optional request parameters to existing API endpoints\n- Changing the order of properties in existing API responses\n- Changing the autocomplete address suggestion format\n\n## Error Handling\n\nA successful lookup is accompanied with a HTTP status code of 200 and a response code of 2000 (found in the body).\n\nAn error has occurred if the HTTP status code is not 200. Errors can range from a benign 404 (resource not found) to more urgent errors (your API Key ran out of credit, failed authentication, etc).\n\n## Testing\n\nEach new account comes with a free test balance. Contact us if you need more for testing and integration.\n\n## Metadata\n\nRequests that affect your balance may be annotated with arbitrary metadata. This data is stored along with your lookup history and can be queried at a later date via the API or the dashboard. We call the ability to label your requests [tagging](https://docs.ideal-postcodes.co.uk/docs/guides/tags).\n\n## Response Codes\n\nThe API returns two indicators to help you to determine the status of each HTTP request.\n\nThe first is the **HTTP Status**, which is found in the status-line of all HTTP requests. The API will return status codes that adhere to HTTP /1.1 Specifications wherever possible.\n\n`2XX` status codes indicates success while `4XX` and `5XX` indicate client and server errors respectively.\n\nThe second is the **API response code**, which can be found in the `code` property of the response body. This code will provide a more specific reason if a failure has occurred and can point you in the right direction when debugging.\n", "contact": { "email": "support@ideal-postcodes.co.uk", "name": "Support", "url": "https://ideal-postcodes.co.uk/support" } }, "servers": [ { "url": "https://api.ideal-postcodes.co.uk/v1", "description": "API Server", "variables": {} } ], "tags": [ { "name": "Address Search", "description": "Global address autocomplete, for search-as-you-type" }, { "name": "Place Search", "description": "Global places search to identify geographical names and places" }, { "name": "UK", "description": "UK Address and Postcode Search" }, { "name": "Keys", "description": "Monitor and manage API Keys" }, { "name": "Licensees", "description": "The Licensee resource represents an alternate legal End User of our data who may not be the same entity as the owners of the account.\n\nThe concept of Licensees underpins our sublicensing platform, which allows users to license multiple external organisations or individuals to access data under the same account.\n\nSublicensing is ideal for platform vendors, who provide services to multiple clients who in turn each have their own users.\n" }, { "name": "Configs", "description": "The Config resource allows users to assign serialised configuration data to API Keys. The payloads assigned to a Config object can later be retrieved to dynamically configure your integration.\n\nUseful if you need to configure your integration remotely rather than editing code in situ.\n" }, { "name": "suggestion", "x-displayName": "Address Suggestion", "description": "Address Suggestions are simple, human readable representations of an address. This format is sufficient tfor a user to determine an address match in an address autocomplete interface. A second request must be made to the API to gather fully validated address.\n\nSee our Address Search APIs for more information on address autocompletion.\n\n<SchemaDefinition schemaRef=\"#/components/schemas/AddressSuggestion\" />\n" }, { "name": "usps_address", "x-displayName": "US Address", "description": "Standard US Address format as reported by USPS.\n\n<SchemaDefinition schemaRef=\"#/components/schemas/UspsAddress\" />\n" }, { "name": "uk_address", "x-displayName": "UK Address", "description": "Standard UK Address format as reported by Royal Mail's Postcode Address File (PAF). PAF is the most complete and up-to-date address database in the UK.\n\n<SchemaDefinition schemaRef=\"#/components/schemas/PafAddress\" />\n" }, { "name": "ecaf_address", "x-displayName": "IE Address", "description": "Standard Republic of Ireland Address format as reported by the Eircode ECAF file.\n\n<SchemaDefinition schemaRef=\"#/components/schemas/EcafAddress\" />\n" }, { "name": "ecad_address", "x-displayName": "IE Address (ECAD)", "description": "ECAF file including additional data for each address.\n\n<SchemaDefinition schemaRef=\"#/components/schemas/EcadAddress\" />\n" }, { "name": "ab_address", "x-displayName": "AddressBase Core", "description": "AddressBase Core Address. An alternative to UK PAF dataset from Ordnance Survey.\n\nPlease contact us to have this enabled on your account.\n\n<SchemaDefinition schemaRef=\"#/components/schemas/AddressBaseCore\" />\n" }, { "name": "geonames_place", "x-displayName": "GeoNames Place", "description": "GeoNames place record\n\n<SchemaDefinition schemaRef=\"#/components/schemas/GeonamesPlace\" />\n" } ], "externalDocs": { "description": "More on our APIs, libraries with guides and examples", "url": "https://docs.ideal-postcodes.co.uk" }, "paths": { "/postcodes/{postcode}": { "get": { "tags": [ "UK" ], "summary": "Lookup Postcode", "operationId": "Postcodes", "description": "Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive.\n\nThe Postcode Lookup API provides a JSON interface to search UK addresses from a postcode. It can be used to power Postcode Lookup driven address searches, like [Postcode Lookup](/postcode-lookup).\n\n## Postcode Not Found\n\nLookup balance is unaffected by invalid postcodes. The API returns a `404` response with response body:\n\n```json\n{\n \"code\": 4040,\n \"message\": \"Postcode not found\",\n \"suggestions\": [\"SW1A 0AA\"]\n}\n```\n\n### Suggestions\n\nIf a postcode cannot be found, the API will provide up to 5 closest matching postcodes. Common errors will be corrected first (e.g. mixing up `O` and `0` or `I` and `1`).\n\nIf the suggestion list is small (fewer than 3), there is a high probability the correct postcode is there. You may notify the user or immediately trigger new searches.\n\nThe suggestion list will be empty if the postcode has deviated too far from a valid postcode format.\n\n## Multiple Residence\n\nA small number of postcodes will return more than 100 premises. These may require pagination. Use `page` to paginate the result set.\n", "parameters": [ { "name": "postcode", "in": "path", "description": "Postcode to retrieve", "required": true, "style": "simple", "explode": false, "example": "SW1A 2AA", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/FilterParam" }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/TagsParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostcodeResponse" }, "examples": { "Postcode Found": { "value": { "result": [ { "postcode": "SW1A 2AA", "postcode_inward": "2AA", "postcode_outward": "SW1A", "post_town": "London", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Downing Street", "dependant_thoroughfare": "", "building_number": "10", "building_name": "", "sub_building_name": "", "po_box": "", "department_name": "", "organisation_name": "Prime Minister & First Lord Of The Treasury", "udprn": 23747771, "postcode_type": "L", "su_organisation_indicator": "", "delivery_point_suffix": "1A", "line_1": "Prime Minister & First Lord Of The Treasury", "line_2": "10 Downing Street", "line_3": "", "premise": "10", "longitude": -0.12767, "latitude": 51.503541, "eastings": 530047, "northings": 179951, "country": "England", "traditional_county": "Greater London", "administrative_county": "", "postal_county": "London", "county": "London", "district": "Westminster", "ward": "St. James's", "uprn": "100023336956", "id": "paf_23747771", "country_iso": "GBR", "country_iso_2": "GB", "county_code": "", "language": "en", "umprn": "", "dataset": "paf" } ], "code": 2000, "message": "Success", "limit": 100, "page": 0, "total": 1 } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponse" } } } }, "404": { "description": "Postcode Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostcodeNotFoundResponse" } } } } }, "x-codeSamples": [ { "lang": "http", "label": "URL", "source": "https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A2AA?api_key=iddqd\n" }, { "lang": "cURL", "label": "CLI", "source": "curl -G -k \\\n--url 'https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A2AA' \\\n--d \"api_key=iddqd\"\n" } ] } }, "/udprn/{udprn}": { "get": { "tags": [ "UK" ], "summary": "Retrieve by UDPRN", "operationId": "UDPRN", "description": "Returns an address as identified by its Unique Delivery Point Reference Number (UDPRN).\n\nYou may find it useful to store UDPRN information as it can be used to retrieve the most recent information for an address. It can also be used to test for a deleted address.\n\nUDPRNs are an eight digit unique numeric code (e.g. `25962203`) for any premise on the Postcode Address File. It's essentially a unique identifier for every address in the UK that Royal Mail has in its database.\n\n## Testing\n\nTo test your implementation of our API we have a range of test UDPRNs that yield both successful and unsuccessful responses to your request.\n\nThey are the following:\n\n- `0` Returns a successful UDPRN lookup response\n `2000`\n- `-1` Returns \"UDPRN not found\", error `4044`\n- `-2` Returns \"no lookups remaining\", error `4020`\n- `-3` Returns \"daily (or individual) lookup limit breached\",\n error `4021`\n\nTest request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.\n", "parameters": [ { "name": "udprn", "in": "path", "description": "UDPRN to be retrieved", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/FilterParam" } ], "responses": { "200": { "description": "Success", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UDPRNResponse" }, "examples": { "Valid UDPRN": { "value": { "result": { "postcode": "SW1A 2AA", "postcode_inward": "2AA", "postcode_outward": "SW1A", "post_town": "London", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Downing Street", "dependant_thoroughfare": "", "building_number": "10", "building_name": "", "sub_building_name": "", "po_box": "", "department_name": "", "organisation_name": "Prime Minister & First Lord Of The Treasury", "udprn": 23747771, "postcode_type": "L", "su_organisation_indicator": "", "delivery_point_suffix": "1A", "line_1": "Prime Minister & First Lord Of The Treasury", "line_2": "10 Downing Street", "line_3": "", "premise": "10", "longitude": -0.12767, "latitude": 51.503541, "eastings": 530047, "northings": 179951, "country": "England", "traditional_county": "Greater London", "administrative_county": "", "postal_county": "London", "county": "London", "district": "Westminster", "ward": "St. James's", "uprn": "100023336956", "id": "paf_23747771", "country_iso": "GBR", "country_iso_2": "GB", "county_code": "", "language": "en", "umprn": "", "dataset": "paf" }, "code": 2000, "message": "Success" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "http", "label": "URL", "source": "https://api.ideal-postcodes.co.uk/v1/udprn/0?api_key=iddqd\n" }, { "lang": "cURL", "label": "CLI", "source": "curl -k -G https://api.ideal-postcodes.co.uk/v1/udprn/0 \\\n -d \"api_key=iddqd\"\n" } ] } }, "/umprn/{umprn}": { "get": { "tags": [ "UK" ], "summary": "Retrieve by UMPRN", "operationId": "UMPRN", "description": "Returns a multiple occupancy address identified via its UMPRN (Multiple Residence Unique ID).\n\nUMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset.\n\n## Testing\n\nTo test your implementation of our API we have a range of test UMPRNs that yield both successful and unsuccessful responses to your request. They are the following\n\n- `0` Returns a successful UMPRN lookup response `2000`\n- `-1` Returns \"UMPRN not found\", error `4044`\n- `-2` Returns \"no lookups remaining\", error `4020`\n- `-3` Returns \"daily (or individual) lookup limit breached\", error `4021`\n\nTest request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.\n\n### Pricing\n\nPer lookup charges apply. Empty responses are not charged.\n", "parameters": [ { "name": "umprn", "in": "path", "description": "UMPRN to be retrieved", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/FilterParam" } ], "responses": { "200": { "description": "Success", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UMPRNResponse" }, "examples": { "Valid UMPRN": { "value": { "result": { "postcode": "CV4 7AL", "postcode_inward": "7AL", "postcode_outward": "CV4", "post_town": "Coventry", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Gibbet Hill Road", "dependant_thoroughfare": "", "building_number": "", "building_name": "Block 1 Arthur Vick", "sub_building_name": "Room 249a", "po_box": "", "department_name": "", "organisation_name": "", "udprn": 5770157, "postcode_type": "S", "su_organisation_indicator": "", "delivery_point_suffix": "1A", "line_1": "Room 249a, Block 1 Arthur Vick", "line_2": "Gibbet Hill Road", "line_3": "", "premise": "Room 249a, Block 1 Arthur Vick", "longitude": -1.5648072, "latitude": 52.3858227, "eastings": 429716, "northings": 276509, "country": "England", "traditional_county": "Warwickshire", "administrative_county": "", "postal_county": "West Midlands", "county": "West Midlands", "district": "Coventry", "ward": "Wainbody", "uprn": "200001572050", "id": "mr_50906058", "country_iso": "GBR", "country_iso_2": "GB", "county_code": "", "language": "en", "umprn": 50906058, "dataset": "mr" }, "code": 2000, "message": "Success" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "http", "label": "URL", "source": "https://api.ideal-postcodes.co.uk/v1/umprn/0?api_key=iddqdmr\n" }, { "lang": "cURL", "label": "CLI", "source": "curl -k -G https://api.ideal-postcodes.co.uk/v1/umprn/0 \\\n -d \"api_key=iddqdmr\"\n" } ] } }, "/keys/{key}": { "get": { "tags": [ "Keys" ], "summary": "Availability", "operationId": "KeyAvailability", "description": "Returns public information on your API Key.\n\nThis endpoint can be used for the following:\n - Determine if the key is currently usable via the `available` property\n - Determine available contexts for an API Key\n- Identify the currently likely context of a user given their location\n\nYou may pass both API Keys (beginning `ak_`) and Sub-licensed Keys (beginning `sl_`).\n", "parameters": [ { "$ref": "#/components/parameters/ApiKeyPathParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "404": { "description": "Invalid Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/keys/{key}/details": { "get": { "tags": [ "Keys" ], "summary": "Details", "operationId": "KeyDetails", "description": "Returns private data on the key including remaining lookups, available datasets and usage limits.\n", "parameters": [ { "$ref": "#/components/parameters/ApiKeyPathParam" }, { "$ref": "#/components/parameters/UserTokenParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyDetailsResponse" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "deprecated": false }, "put": { "tags": [ "Keys" ], "summary": "Update Details", "description": "Update API Key Details", "operationId": "UpdateKeyDetails", "parameters": [ { "$ref": "#/components/parameters/ApiKeyPathParam" }, { "$ref": "#/components/parameters/UserTokenParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyDetailsEditable" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyDetailsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponse" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/keys/{key}/usage": { "get": { "tags": [ "Keys" ], "summary": "Usage Stats", "operationId": "KeyUsage", "description": "Reports the number of lookups consumed on a key for a range of days.\n\nA maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval.\n\nIf no `start` time is provided, the start time will be set to 21 days prior to the current time.\n\nIf no `end` time is provided, the current time will be used.\n\nAppend `tags` to scope the number of lookups to those with matching tag values. E.g. `tags=foo,bar` will only count transactions that match `foo` and `bar`.\n", "parameters": [ { "$ref": "#/components/parameters/ApiKeyPathParam" }, { "$ref": "#/components/parameters/UserTokenParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/TagsParam" }, { "$ref": "#/components/parameters/LicenseeParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyUsageResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponse" } } } } }, "x-codeSamples": [ { "lang": "http", "label": "URL", "source": "https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage?user_token=my_secret_token\n" }, { "lang": "cURL", "label": "CLI", "source": "curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage \\\n -d \"user_token=my_secret_token\"\n" } ] } }, "/keys/{key}/lookups": { "get": { "tags": [ "Keys" ], "summary": "Logs (CSV)", "operationId": "KeyLogs", "description": "Reports lookup information on a key for paid lookups.\n\nThis method requires a `user_token`, which can be found on your [accounts page](https://ideal-postcodes.co.uk/account).\n\nA maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval.\n\n## Download Usage History (CSV)\n\n`GET /keys/:key/lookups`\n\nReturns a CSV download of lookups performed and associated information.\n\nNote that the Content-Type returned will be CSV (text/csv). For a non 200 response, the `Content-Type` will revert to JSON with the error code and message embedded.\n\n## Data Redaction\n\nPersonally Identifiable Data (PII) caught in this your usage log (including IP, search term and URL data) will be redacted on a weekly basis.\n\nBy default, PII will be redacted if it is older than 21 days. This timeframe can be configured from your dashboard.\n\nYou may prevent PII collection altogether by setting the interval to `0` days.\n", "parameters": [ { "$ref": "#/components/parameters/ApiKeyPathParam" }, { "$ref": "#/components/parameters/UserTokenParam" }, { "$ref": "#/components/parameters/StartParam" }, { "$ref": "#/components/parameters/EndParam" }, { "$ref": "#/components/parameters/LicenseeParam" } ], "responses": { "200": { "description": "Success", "content": { "text/csv": { "example": "2015-02-21T16:05:22.991Z,82.85.128.18,SW12AA,https://www.example.com/,Postcode Lookup,\n2015-02-21T16:05:38.298Z,82.85.128.18,10 Downing Street London,https://www.example.com/,Address Lookup,CRM\n2015-02-21T16:06:49.227Z,82.85.128.18,OX44PP,https://www.example.com/,Postcode Lookup,\"Website,Live\"\n2015-02-21T16:07:02.706Z,82.85.128.18,PL9 9HE,https://www.example.com/,Postcode Lookup,\n", "schema": { "type": "string", "description": "Success" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponse" } } } } }, "x-codeSamples": [ { "lang": "http", "label": "URL", "source": "https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups?user_token=my_secret_token\n" }, { "lang": "cURL", "label": "CLI", "source": "curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups \\\n -d \"user_token=my_secret_token\"\n" } ] } }, "/cleanse/addresses": { "post": { "tags": [ "UK" ], "summary": "Cleanse Address", "description": "The address cleanse API attempts to return the closest matching address for any given address inputs. We also return a number of Match Level indicators that describe the degree to which the suggested address matches the input address. The more impaired the input address, the harder it is to cleanse.\n\n## Confidence Score\n\nThe confidence score is a number ranging between 0 and 1. Where 1 implies a full match and 0 implies no major elements completely match. Each incorrect, missing or misspelled element will subtract from the overall confidence score.\n\n### Deciding on an Acceptable Confidence Score Threshold\n\nDifferent address cleanse projects can have radically different inputs. However, within each project, the inputs tend to repeat the same errors. For instance, some input datasets may be exclusively inputted manually and be prone to typos. Others may have a persistently missing datapoint such as organisation name or postcode. For this reason, it is important to understand that there is no absolute Confidence Score threshold. Instead, the acceptable confidence score must be determined on a project by project basis based on systematic errors present in the data and business goals.\n\nWhen determining an acceptable Confidence Score threshold you should load a subset of the dataset into a spreadsheet application like Excel and sort on the score. Scrolling from top-to-bottom you will be able to observe matches from best to worst. As you start to hit the lower quality searches, you will be able to roughly determine:\n - Which confidence scores indicate ambiguous matches (i.e. up to building level only)\n- Which confidence scores indicate a poor or no match (i.e. the nearest matching address is too far from the input address)\n\nDepending on your business goals, you can also use the Match Levels to determine an acceptable match. For instance, do you need to match up to the thoroughfare or building name only? Are accurate organisation names an important feature?\n", "operationId": "AddressCleanse", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/TagsParam" }, { "name": "context", "in": "query", "schema": { "type": "string" }, "description": "Identify the country of the address to cleanse. Defaults to UK (GBR)\n", "example": "usa" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Freeform address input to cleanse\n", "example": "10 Downing Street, London, SW2A 2BN" }, "postcode": { "type": "string", "description": "Optionally specify postal code for the address.\n", "example": "SW1A 2BN" }, "post_town": { "type": "string", "description": "Optionally specify the city or town of the address.\n\nFor UK verifications, this should be the \"post town\" of the address.\n\nFor USA verifications, this should be the city of the address.\n", "example": "London" }, "county": { "type": "string", "description": "Optionally specify the county or state of the address.\n\nFor UK verifications, we recommend omitting this field as county data is unreliable.\n\nFor USA verifications, this should be the state of the address.\n", "example": "Kent" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CleanseResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "429": { "description": "Rate Limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedResponse" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -k -G 'https://api.ideal-postcodes.co.uk/v1/cleanse/addresses' \\\n -H 'Authorization: api_key=\"ak_test\"'\n -H 'Content-Type: application/json'\n -d '{\"query\": \"10 downing street sw1a\"}'\n" } ] } }, "/verify/addresses": { "post": { "tags": [ "US" ], "summary": "Verify Address", "description": "The address verify API validates, corrects, and standardizes individual addresses based on USPS's Coding Accuracy Support System (CASS).\n\nThe address verify API accepts the 3 combination of inputs:\n\n- Free-form address submitted as a single string in `query`\n - Example: \"123 Main St, Springfield, CO 81073-1119\"\n- Only free-form and zip code address components submitted as separate parameters:\n - `query` for the first address line\n - `zip_code` for the ZIP code\n - Example:\n - `query`: \"123 Main St, Springfield CO\"\n - `zip_code`: \"81073-1119\"\n- Only free-form, city and state address components submitted as separate parameters:\n - `query` for the first address line\n - `city` for the city\n - `state` for the state\n - Example:\n - `query`: \"123 Main St\"\n - `city`: \"Springfield\"\n - `state`: \"CO\"\n", "operationId": "AddressVerify", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "$ref": "#/components/parameters/TagsParam" }, { "name": "context", "in": "query", "schema": { "type": "string" }, "description": "Identify the country of the address to verify. Defaults to United States (USA)\n", "example": "usa" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Address input to verify.\n\nIf submitting a freeform address verification query, enter the full address. E.g. `query=123 Main St, Springfield, CO, 81073`\n\nOtherwise, query can be accompanied with the following address components:\n- `zip_code`\n- `city` and `state`\n\nIf zip_code or `city` and `state` or supplied, please omit this information from query by using it purely for the first address line. E.g. `query=123 Main St`\n", "example": "123 Main St, Springfield, CO 81073" }, "zip_code": { "type": "string", "description": "Specify the zip code of an address. The following formats are accepted: `81073-1119`, `810731119`, `81073`.\n", "example": "81073-1119" }, "city": { "type": "string", "description": "City of an address. For the US, this should be the city name.\n", "example": "Springfield" }, "state": { "type": "string", "description": "State of an address. For the US, this should be in the 2 letter state abbreviation format.\n", "example": "CO" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "429": { "description": "Rate Limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedResponse" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl -k -G 'https://api.ideal-postcodes.co.uk/v1/verify/addresses' \\\n -H 'Authorization: api_key=\"ak_test\"'\n -H 'Content-Type: application/json'\n -d '{\"query\": \"123 Main St, Springfield, IL 62701\" }'\n" } ] } }, "/autocomplete/addresses": { "get": { "tags": [ "Address Search" ], "summary": "Find Address", "description": "The Address Autocomplete API delivers address suggestions in order of relevance based on a provided query. It aids real-time address autofill implementations.\n\nConsider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments rather than interacting with this API directly.\n\n## API Usage\n\nImplementing our Address Autocomplete API involves:\n\n1. Fetch address suggestions with `/autocomplete/addresses`\n2. Acquire the complete address using the ID from the suggestion\n\nStep 2 will decrement your lookup balance.\n\nNote that step 1 is not a free standalone resource. Integrations that consistently make autocomplete requests without a paid Step 2 request will be rate limited and then suspended.\n\n## Query Filters\n\nRefine results by appending filters to your querystring, e.g., `postcode=sw1a2aa` for postcode `SW1A 2AA`. Invalid filters return an empty set without affecting your lookup count.\n\nTo apply multiple filter terms, use a comma-separated list, e.g., `postcode_outward=e1,e2,e3` combines result sets for E1, E2, and E3. Unless otherwise specified, all filters support multiple terms.\n\nCombine filters by `AND` logic, for instance, `su_organisation_indicator=Y&postcode_area=n`. The maximum allowed filter terms is **10**.\n\n## Address Bias\n\nPreface bias searches with `bias_` to boost certain address results. Unlike filters, biasing allows unmatched addresses to appear with lower priority.\n\nFor example, use `bias_postcode_area=SW,SE` to favor addresses in the `SW` and `SE` postcode areas. Invalid bias terms have no effect.\n\nMultiple bias terms are allowed unless stated otherwise, with a combined maximum of **5**.\n\n## Suggestion Format\n\nThe suggestion format is subject to change. We recommend using the suggestion as-is to prevent potential integration issues.\n\n## Rate Limiting and Cost\n\nThe rate limit for the Autocomplete API is 3000 requests per 5 minutes. HTTP Headers inform about the current rate limit.\n\nAutocomplete API usage does not impact your balance, but resolving a suggestion to a full address requires a paid request. Autocomplete requests without subsequent paid requests may result in rate limitation or suspension.\n", "operationId": "FindAddress", "parameters": [ { "$ref": "#/components/parameters/ApiKeyParam" }, { "name": "query", "description": "**Address Query**\n\nThe partial address string entered by the user to autocomplete.\n", "example": "10 downing street lo", "explode": false, "in": "query", "schema": { "type": "string", "maxLength": 150 }, "style": "form" }, { "$ref": "#/components/parameters/DatasetParam" }, { "$ref": "#/components/parameters/ContextParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/BiasLonLatParam" }, { "$ref": "#/components/parameters/BiasIpParam" }, { "$ref": "#/components/parameters/BoxParam" }, { "$ref": "#/components/parameters/PostcodeOutwardParam" }, { "$ref": "#/components/parameters/PostcodeParam" }, { "$ref": "#/components/parameters/PostcodeAreaParam" }, { "$ref": "#/components/parameters/PostcodeSectorParam" }, { "$ref": "#/components/parameters/PostTownParam" }, { "$ref": "#/components/parameters/UPRNParam" }, { "$ref": "#/components/parameters/CountryParam" }, { "$ref": "#/components/parameters/PostcodeTypeParam" }, { "$ref": "#/components/parameters/SmallUserParam" }, { "$ref": "#/components/parameters/BiasPostcodeOutwardParam" }, { "$ref": "#/components/parameters/BiasPostcodeParam" }, { "$ref": "#/components/parameters/BiasPostcodeAreaParam" }, { "$ref": "#/components/parameters/BiasPostcodeSectorParam" }, { "$ref": "#/components/parameters/BiasPosttownParam" }, { "$ref": "#/components/parameters/BiasThoroughfareParam" }, { "$ref": "#/components/parameters/BiasCountryParam" } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests that can be made in 5 minutes", "schema": { "type": "number", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The remaining requests within the current rate limit window", "schema": { "type": "number", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds.\n", "schema": { "type": "number", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompleteResponse" }, "ex