openapi-directory
Version:
Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS
1 lines • 187 kB
JSON
{"openapi":"3.0.3","servers":[{"description":"API Server","url":"https://api.ideal-postcodes.co.uk/v1","variables":{}}],"info":{"contact":{"email":"support@ideal-postcodes.co.uk","name":"Support","url":"https://ideal-postcodes.co.uk/support"},"description":"# Getting Started\n\n## Overview\n\n### Access\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### 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### JSONP\n\n[JSONP](http://en.wikipedia.org/wiki/JSONP) requests are supported. Include a `callback=` in your request as a query parameter. Your results return wrapped in a function designated by your request.\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### Community Key\n\nOur documentation and demos make heavy use of our community key `iddqd`. This allows for convenient access for trialing the API.\n\nMany restrictions on this key are relaxed to allow developers make test requests. This key has a limit of 15 lookups per IP address per day as well as a daily usage cap. If you hit any limit restrictions, you can continue testing the API by creating a key of your own and using our free test methods.\n\nPlease be kind with the community key. We're trusting everyone to use it responsibly so that other developers may trial the API. Thank you!\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\nPlease use the glossary of code numbers and HTTP status codes below when debugging your requests.\n\n## 200 Request Success\n\n| HTTP Code | API Code | Description |\n| --------- | -------- | -------------------------------------------- |\n| 200 | 2000 | Success. Request was completed successfully. |\n\n## 400 Bad Request\n\nThe request could not be understood due to some input error.\n\n| HTTP Code | API Code | Description |\n| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| 400 | 4000 | Invalid syntax submitted. Some part of your request was malformed or did not match our specifications. |\n| 400 | 4001 | Validation failed on your submitted data. Some of the data you provided did not meet our validation requirements, e.g. string length. |\n| 400 | 4005 | Invalid start date. Please ensure start dates are provided as a UTC Timestamp in milliseconds. |\n| 400 | 4006 | Invalid end date. Please ensure end dates are provided as a UTC Timestamp in milliseconds. |\n| 400 | 4007 | Invalid date range. Check if your start and end dates are in the right order. |\n| 400 | 4008 | Invalid date range. Check that your date range is 90 days or less. |\n| 400 | 4009 | Too many tags. Please specify no more than 3 tags to query. |\n\n## 401 Unauthorised\n\nAuthorization credentials are not valid.\n\n| HTTP Code | API Code | Description |\n| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| 401 | 4010 | Invalid Key. The `api_key` you provided is not valid. |\n| 401 | 4011 | Requesting URL not on whitelist. The cross domain request is not coming from a whitelisted URL. You can update or disable your allowed URLs via your Key settings. |\n| 401 | 4012 | Failed user authentication. Invalid `user_token` presented. |\n| 401 | 4013 | Licensee Key is required. Sublicensed keys require you need to present licensee credentials via the `licensee` parameter. |\n\n## 402 Request Failed\n\nYour request is well-formed but are not able to complete your request for another reason.\n\n| HTTP Code | API Code | Description |\n| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| 402 | 4020 | Key balance depleted. You're out of lookups on your API Key. |\n| 402 | 4021 | Limit reached. One of your lookup limits has been breached for today. This could either be your total daily limit on your key or the individual IP limit. You can either wait for for the limit to reset (after a day) or manually disable or increase your limit. |\n\n## 404 Resource Not Found\n\nThe resource you requested does not exist.\n\n| HTTP Code | API Code | Description |\n| --------- | -------- | --------------------------------------------------------------------------------------------- |\n| 404 | 4040 | Postcode not found. The postcode you have submitted does not exist. |\n| 404 | 4041 | User not found. Your user could not be identified given the credentials you presented. |\n| 404 | 4042 | Key not found. Your key could not be identified given the credentials you presented. |\n| 404 | 4044 | No UDPRN found. No address is associated with the UDPRN queried |\n| 404 | 4045 | No licensee found. Your licensee could not be identified given the credentials you presented. |\n| 404 | 4046 | No UMPRN found. No Multiple Residence premise is associated with the UMPRN queried. |\n\n## 500 Server Error\n\nA error occurred on our server.\n\n| HTTP Code | API Code | Description |\n| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| 500 | 5000 | An error occurred on our end. These errors are logged and queued so we can understand what went wrong. However, if you need speedy resolution please email support |\n| 500 | 5001 | Akin to 5000. |\n| 500 | 5002 | The server took too long to process on our end, so we aborted the request. You may retry the request. |\n","license":{"name":"AGPLv3","url":"https://opensource.org/licenses/AGPL-3.0"},"termsOfService":"https://terms.ideal-postcodes.co.uk","title":"API Reference - Ideal Postcodes","version":"3.7.0","x-apisguru-categories":["location"],"x-logo":{"url":"https://ideal-postcodes.co.uk/apple-icon-57x57.png"},"x-origin":[{"format":"openapi","url":"https://openapi.ideal-postcodes.dev/openapi.json","version":"3.0"}],"x-providerName":"ideal-postcodes.co.uk"},"externalDocs":{"description":"More on our APIs, libraries with guides and examples","url":"https://docs.ideal-postcodes.co.uk"},"tags":[{"description":"Global address autocomplete, for search-as-you-type","name":"Address Search"},{"description":"Global places search to identify geographical names and places","name":"Place Search"},{"description":"UK Address and Postcode Search","name":"UK"},{"description":"Monitor and manage API Keys","name":"Keys"},{"description":"The Licensee resource represents an alternate legal End User of our data who may not be 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":"Licensees"},{"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":"Configs"},{"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":"suggestion","x-displayName":"Address Suggestion"},{"description":"Standard US Address format as reported by USPS.\n\n<SchemaDefinition schemaRef=\"#/components/schemas/UspsAddress\" />\n","name":"usps_address","x-displayName":"US 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":"uk_address","x-displayName":"UK Address"},{"description":"Standard Republic of Ireland Address format as reported by the Eircode ECAF file.\n\n<SchemaDefinition schemaRef=\"#/components/schemas/EcafAddress\" />\n","name":"ecaf_address","x-displayName":"IE Address"},{"description":"ECAF file including additional data for each address.\n\n<SchemaDefinition schemaRef=\"#/components/schemas/EcadAddress\" />\n","name":"ecad_address","x-displayName":"IE Address (ECAD)"},{"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":"ab_address","x-displayName":"AddressBase Core"},{"description":"GeoNames place record\n\n<SchemaDefinition schemaRef=\"#/components/schemas/GeonamesPlace\" />\n","name":"geonames_place","x-displayName":"GeoNames Place"}],"paths":{"/addresses":{"get":{"description":"Extract a list of complete addresses that match the query ordered by relevance score. This query accepts an optional limit and page query (defaults to 10 and 0 respectively).\n\nIf a valid postcode is passed as the query string, the entire address list for that postcode is passed as a result. Note, in these cases, limit and page parameters are ignored.\n\nThis API is designed as a multi-purpose tool for generating address lists, cleansing and wholesale data extraction according to specific parameters.\n\nFor address autocomplete, see our address finder API - which is designed for speed and address completion.\n\n## Reverse Geocoding\n\nReturn a list of addresses around a point using the lon= and lat= querystring arguments. Addresses will be sorted in order of distance to the point. The search radius is 100m.\n\n## Filters\n\nYou can strictly narrow your result by adding filters to your query string which correspond with an address attribute.\n\nFor instance, you can restrict to postcode `SW1A 2AA` by appending `postcode=sw1a2aa`.\n\nIf a filter term is invalid, e.g. `postcode=SW1A2AAA`, then an empty result set is returned and no lookup is incurred.\n\nYou can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: `postcode_outward=e1,e2,e3`. Multiple terms are `OR`'ed, i.e. the matching result sets are combined.\n\nAll filters can accept multiple terms unless stated otherwise below.\n\nMultiple filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: `su_organisation_indicator=Y&postcode_area=n`. Multiple filters are `AND`'ed, i.e. each additional filter narrows the result set.\n\nA combined maximum of 5 terms are allowed across all filters.\n\n## Biases\n\nYou can boost certain addresses results that correspond with a certain address attribute. All bias searches are prefixed with `bias_`.\n\nBiased searches, unlike filtered searches, also allow unmatched addresses to appear . These will rank lower.\n\nFor instance, you can boost addresses with postcode areas `SW` and `SE` by appending `bias_postcode_area=SW,SE`.\n\nIf a bias term is invalid, e.g. `bias_postcode=SW1A2AAA` no bias effect is applied.\n\nYou may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to `E1`, `E2` and `E3` outward codes: `bias_postcode_outward=e1,e2,e3`.\n\nAll biases can accept multiple terms unless stated otherwise below.\n\nA combined maximum of 5 terms are allowed across all biases.\n\n## Search by Postcode and Building Name or Number\n\nSearch by postcode and building attribute with the postcode filter and query argument. E.g. For \"SW1A 2AA Prime Minister\" `/v1/addresses?postcode=sw1a2aa&q=prime minister`.\n\nThe advantage of using filters is a postcode mismatch does not result in a lookup as no results are returned.\n\n#### Search By UPRN\n\nSearch by UPRN using the `uprn` filter and excluding the query argument. E.g. `/v1/addresses?uprn=100`.\n\n## Testing\n\n- **ID1 1QD** Returns a successful query response `2000`\n- **ID1 KFA** Returns an empty query response `2000`\n- **ID1 CLIP** Returns \"no lookups remaining\" error `4020`\n- **ID1 CHOP** 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","operationId":"Addresses","parameters":[{"explode":false,"in":"query","name":"api_key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"form"},{"description":"Specifies the address you wish to query. Query can be shortened to `q=`","explode":false,"in":"query","name":"query","schema":{"type":"string"},"style":"form"},{"explode":false,"in":"query","name":"limit","schema":{"$ref":"#/components/schemas/LimitParam"},"style":"form"},{"explode":false,"in":"query","name":"page","schema":{"$ref":"#/components/schemas/PageParam"},"style":"form"},{"explode":false,"in":"query","name":"filter","schema":{"$ref":"#/components/schemas/FilterParam"},"style":"form"},{"explode":false,"in":"query","name":"lon","schema":{"$ref":"#/components/schemas/AddressLongitudeParam"},"style":"form"},{"explode":false,"in":"query","name":"lat","schema":{"$ref":"#/components/schemas/AddressLatitudeParam"},"style":"form"},{"explode":false,"in":"query","name":"postcode_outward","schema":{"$ref":"#/components/schemas/PostcodeOutwardParam"},"style":"form"},{"explode":false,"in":"query","name":"postcode","schema":{"$ref":"#/components/schemas/PostcodeParam"},"style":"form"},{"explode":false,"in":"query","name":"postcode_area","schema":{"$ref":"#/components/schemas/PostcodeAreaParam"},"style":"form"},{"explode":false,"in":"query","name":"postcode_sector","schema":{"$ref":"#/components/schemas/PostcodeSectorParam"},"style":"form"},{"explode":false,"in":"query","name":"post_town","schema":{"$ref":"#/components/schemas/PostTownParam"},"style":"form"},{"explode":false,"in":"query","name":"uprn","schema":{"$ref":"#/components/schemas/UPRNParam"},"style":"form"},{"explode":false,"in":"query","name":"country","schema":{"$ref":"#/components/schemas/CountryParam"},"style":"form"},{"explode":false,"in":"query","name":"postcode_type","schema":{"$ref":"#/components/schemas/PostcodeTypeParam"},"style":"form"},{"explode":false,"in":"query","name":"su_organisation_indicator","schema":{"$ref":"#/components/schemas/SmallUserParam"},"style":"form"},{"explode":false,"in":"query","name":"box","schema":{"$ref":"#/components/schemas/BoxParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_postcode_outward","schema":{"$ref":"#/components/schemas/BiasPostcodeOutwardParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_postcode","schema":{"$ref":"#/components/schemas/BiasPostcodeParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_postcode_area","schema":{"$ref":"#/components/schemas/BiasPostcodeAreaParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_postcode_sector","schema":{"$ref":"#/components/schemas/BiasPostcodeSectorParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_post_town","schema":{"$ref":"#/components/schemas/BiasPosttownParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_thoroughfare","schema":{"$ref":"#/components/schemas/BiasThoroughfareParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_country","schema":{"$ref":"#/components/schemas/BiasCountryParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_lonlat","schema":{"$ref":"#/components/schemas/BiasLonLatParam"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressResponse"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostcodeNotFoundResponse"}}},"description":"Postcode Not Found"}},"summary":"Extract Addresses","tags":["UK"],"x-codeSamples":[{"label":"URL","lang":"http","source":"https://api.ideal-postcodes.co.uk/v1/addresses?api_key=iddqd&query=10%20downing%20street%20london\n"},{"label":"CLI","lang":"cURL","source":"curl -k -G 'https://api.ideal-postcodes.co.uk/v1/addresses' \\\n -d 'api_key=iddqd' \\\n --data-urlencode 'query=10 downing street london'\n"}]}},"/autocomplete/addresses":{"get":{"description":"The address autocomplete API returns a list of address suggestions that match the query ordered by relevance.\n\nThis API can be used to power realtime address finders, also known as address autofill or address autocomplete.\n\nConsider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments.\n\n## Implementing Address Autocomplete\n\nRapid address autocompletion using our Address Autocomplete API is a 2 step process.\n\n1. Retrieve partial address suggestions via `/autocomplete/addresses`\n2. Retrieve the entire address with the ID provided in the suggestion\n\nStep 2 will decrement your lookup balance.\n\nPlease note, this API is not intended to be a free standalone resource.\n\n## Filters\n\nYou can strictly narrow your result by adding filters to your querystring. For instance, you can restrict to postcode `SW1A 2AA` by appending `postcode=sw1a2aa`.\n\nIf a filter term is invalid, e.g. `postcode=SW1A2AAA`, then an empty result set is returned and no lookup is incurred.\n\nYou can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: `postcode_outward=e1,e2,e3`. Multiple terms are `OR`'ed, i.e. the matching result sets are combined.\n\nAll filters can accept multiple terms unless stated otherwise below.\n\nFilters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: `su_organisation_indicator=Y&postcode_area=n`. Multiple filters are `AND`'ed, i.e. each additional filter narrows the result set.\n\nA maximum of **10** terms are allowed across all filters.\n\n## Biases\n\nYou can boost certain addresses results that match specific address criteria. All bias searches are prefixed with `bias_`.\n\nBiasing (unlike filtering) also allow unmatched addresses to appear with lower precedence.\n\nFor instance, can boost addresses with postcode areas `SW` and `SE` by appending `bias_postcode_area=SW,SE`.\n\nNo bias effect applies to bias terms that are invalid. e.g. `bias_postcode=SW1A2AAA`\n\nYou may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to `E1`, `E2` and `E3` outward codes: <code>bias_postcode_outward=e1,e2,e3</code>.\n\nAll biases can accept multiple terms unless stated otherwise below.\n\nA combined maximum of **5** terms are allowed across all biases.\n\n## Suggestion Format\n\nThe suggestion format is prone to change over time. Attempts to parse the suggestion may result in your integration breaking. Instead use the suggestion as-is.\n\n## Rate Limiting\n\nYou can make up to 3000 requests to the autocomplete API within a 5 minute span. The HTTP Header contains information on your current rate limit.\n\n| Header | Description |\n| ----------------------- | -------------------------------------------------------------------------------------- |\n| `X-RateLimit-Limit` | The maximum number of requests that can be made in 5 minutes |\n| `X-RateLimit-Remaining` | The remaining requests within the current rate limit window |\n| `X-RateLimit-Reset` | The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds |\n\n## Pricing\n\nThis API currently does not affect your balance. However, resolving a suggestion into a full address requires a paid request.\n\nPlease note, this API is not intended as a standalone free resource. Integrations that consistently make autocomplete requests without a paid request to resolve an address may be disrupted via tightened rate limits. Continued misuse will result in account suspension.\n","operationId":"AddressAutocomplete","parameters":[{"explode":false,"in":"query","name":"api_key","schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"form"},{"description":"Specifies the address you wish to query. Query can be shortened to `q=`","explode":false,"in":"query","name":"query","schema":{"type":"string"},"style":"form"},{"explode":false,"in":"query","name":"context","schema":{"$ref":"#/components/schemas/Context"},"style":"form"},{"description":"Limits number of address suggestions unless a postcode is detected. In this instance entire list of addreses for that postcode is returned.\n","explode":false,"in":"query","name":"limit","schema":{"$ref":"#/components/schemas/LimitParam"},"style":"form"},{"explode":false,"in":"query","name":"postcode_outward","schema":{"$ref":"#/components/schemas/PostcodeOutwardParam"},"style":"form"},{"explode":false,"in":"query","name":"postcode","schema":{"$ref":"#/components/schemas/PostcodeParam"},"style":"form"},{"explode":false,"in":"query","name":"postcode_area","schema":{"$ref":"#/components/schemas/PostcodeAreaParam"},"style":"form"},{"explode":false,"in":"query","name":"postcode_sector","schema":{"$ref":"#/components/schemas/PostcodeSectorParam"},"style":"form"},{"explode":false,"in":"query","name":"post_town","schema":{"$ref":"#/components/schemas/PostTownParam"},"style":"form"},{"explode":false,"in":"query","name":"uprn","schema":{"$ref":"#/components/schemas/UPRNParam"},"style":"form"},{"explode":false,"in":"query","name":"country","schema":{"$ref":"#/components/schemas/CountryParam"},"style":"form"},{"explode":false,"in":"query","name":"postcode_type","schema":{"$ref":"#/components/schemas/PostcodeTypeParam"},"style":"form"},{"explode":false,"in":"query","name":"su_organisation_indicator","schema":{"$ref":"#/components/schemas/SmallUserParam"},"style":"form"},{"explode":false,"in":"query","name":"box","schema":{"$ref":"#/components/schemas/BoxParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_postcode_outward","schema":{"$ref":"#/components/schemas/BiasPostcodeOutwardParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_postcode","schema":{"$ref":"#/components/schemas/BiasPostcodeParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_postcode_area","schema":{"$ref":"#/components/schemas/BiasPostcodeAreaParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_postcode_sector","schema":{"$ref":"#/components/schemas/BiasPostcodeSectorParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_post_town","schema":{"$ref":"#/components/schemas/BiasPosttownParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_thoroughfare","schema":{"$ref":"#/components/schemas/BiasThoroughfareParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_country","schema":{"$ref":"#/components/schemas/BiasCountryParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_lonlat","schema":{"$ref":"#/components/schemas/BiasLonLatParam"},"style":"form"},{"explode":false,"in":"query","name":"bias_ip","schema":{"$ref":"#/components/schemas/BiasIpParam"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}},"description":"Success","headers":{"X-RateLimit-Limit":{"description":"The maximum number of requests that can be made in 5 minutes","schema":{"format":"int32","type":"number"}},"X-RateLimit-Remaining":{"description":"The remaining requests within the current rate limit window","schema":{"format":"int32","type":"number"}},"X-RateLimit-Reset":{"description":"The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds.\n","schema":{"format":"int32","type":"number"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"}},"summary":"Find Address","tags":["Address Search"],"x-codeSamples":[{"label":"URL","lang":"http","source":"https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&q=10%20downing\n"},{"label":"CLI","lang":"cURL","source":"curl -k -G 'https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses' \\\n -d 'api_key=iddqd' \\\n --data-urlencode 'query=10 downing'\n"}]}},"/autocomplete/addresses/{address}/gbr":{"get":{"description":"Resolves an address autocompletion by its address ID.\n\nResolved addresses (including global addresses) are returned in a UK format (up to 3 address lines) using UK nomenclature (like postcode and county).\n","operationId":"Resolve","parameters":[{"description":"ID of address suggestion","explode":false,"in":"path","name":"address","required":true,"schema":{"type":"string"},"style":"simple"},{"explode":false,"in":"query","name":"api_key","schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbrResolveAddressResponse"}}},"description":"Success","headers":{}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource not found"}},"summary":"Resolve Address (GBR)","tags":["Address Search"],"x-codeSamples":[{"label":"URL","lang":"http","source":"https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/paf_23747771/gbr?api_key=iddqd\n"},{"label":"CLI","lang":"cURL","source":"curl -k -G https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/paf_23747771/gbr?api_key=iddqd \\\n -d \"api_key=iddqd\"\n"}]}},"/autocomplete/addresses/{address}/usa":{"get":{"description":"Resolves an address autocompletion by its address ID.\n\nResolved addresses (including global addresses) are returned in a US format (up to 2 address lines) using US nomenclature (like zipcode, state and city).\n","operationId":"ResolveUsa","parameters":[{"description":"ID of address suggestion","explode":false,"in":"path","name":"address","required":true,"schema":{"type":"string"},"style":"simple"},{"explode":false,"in":"query","name":"api_key","schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsaResolveAddressResponse"}}},"description":"Success","headers":{}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource not found"}},"summary":"Resolve Address (USA)","tags":["Address Search"],"x-codeSamples":[{"label":"URL","lang":"http","source":"https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/usps_Z222446599|1||1101/usa?api_key=iddqd\n"},{"label":"CLI","lang":"cURL","source":"curl -k -G https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/usps_Z222446599|1||1101/usa?api_key=iddqd \\\n -d \"api_key=iddqd\"\n"}]}},"/cleanse/addresses":{"post":{"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 organistation 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 ambigious 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 throroughfare or building name only? Are accurate organisation names an important feature?\n","operationId":"AddressCleanse","parameters":[{"explode":false,"in":"query","name":"api_key","schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"form"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"query":{"description":"Freeform address input to cleanse\n","example":"10 Downing Street, London, SW2A 2BN","type":"string"}},"required":["query"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CleanseResponse"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedResponse"}}},"description":"Rate Limited"}},"summary":"Cleanse","tags":["UK"],"x-codeSamples":[{"label":"CLI","lang":"cURL","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"}]}},"/emails":{"get":{"description":"Query for and validate email addresses.\n","operationId":"EmailValidation","parameters":[{"explode":false,"in":"query","name":"api_key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"form"},{"description":"Specifies the email address to validate","explode":false,"in":"query","name":"query","required":true,"schema":{"type":"string"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailResponse"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"}},"summary":"Email Validation","tags":["Emails"],"x-codeSamples":[{"label":"URL","lang":"http","source":"https://api.ideal-postcodes.co.uk/v1/emails?api_key=ak_test&query=foo@domain.com\n"},{"label":"CLI","lang":"cURL","source":"curl -k -G 'https://api.ideal-postcodes.co.uk/v1/emails' \\\n -d 'api_key=iddqd' \\\n --data-urlencode 'query=foo@domain.com'\n"}]}},"/keys/{key}":{"get":{"description":"Returns public information on key. Currently only returns whether the key is currently useable via the `available` property. Use this to discover if the key is useable before making further requests.\n\nYou may pass both API Keys (beginning `ak_`) and Sub-licensed Keys (beginning `sl_`).\n## Testing\n\nTo test your implementation of our API, you may use the following test keys.\n\n- **iddqd** Availability will return as `true`\n- **idkfa** Availability will return as `false`\n\n","operationId":"KeyAvailability","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}},"description":"Success"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid Key"}},"summary":"Availability","tags":["Keys"]}},"/keys/{key}/configs":{"get":{"description":"Lists configurations associated with a key","operationId":"ListConfigs","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"explode":false,"in":"query","name":"user_token","schema":{"$ref":"#/components/schemas/UserTokenParam"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigsResponse"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}},"description":"Unauthorized Request"}},"summary":"List","tags":["Configs"]},"post":{"description":"Create a config","operationId":"CreateConfig","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"explode":false,"in":"query","name":"user_token","schema":{"$ref":"#/components/schemas/UserTokenParam"},"style":"form"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigNewParam"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigResponse"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}},"description":"Unauthorized Request"}},"summary":"Create","tags":["Configs"]}},"/keys/{key}/configs/{config}":{"delete":{"description":"Permanently deletes a configuration object.","operationId":"DeleteConfig","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"explode":false,"in":"path","name":"config","required":true,"schema":{"$ref":"#/components/schemas/ConfigParam"},"style":"simple"},{"explode":false,"in":"query","name":"user_token","schema":{"$ref":"#/components/schemas/UserTokenParam"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"code":{"enum":[2000],"format":"int32","type":"integer"},"message":{"enum":["Success"],"type":"string"},"result":{"properties":{"deleted":{"example":1,"format":"int32","minimum":0,"type":"number"}},"required":["deleted"],"type":"object"}},"required":["result","code","message"],"title":"Config Delete Response","type":"object"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}},"description":"Unauthorized Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}},"description":"Not Found"}},"summary":"Delete","tags":["Configs"]},"get":{"description":"Retrieve config object by name","operationId":"RetrieveConfig","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"explode":false,"in":"path","name":"config","required":true,"schema":{"$ref":"#/components/schemas/ConfigParam"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigResponse"}}},"description":"Success","headers":{}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}},"description":"Not Found"}},"summary":"Retrieve","tags":["Configs"]},"post":{"description":"Updates configuration object","operationId":"UpdateConfig","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"explode":false,"in":"path","name":"config","required":true,"schema":{"$ref":"#/components/schemas/ConfigParam"},"style":"simple"},{"explode":false,"in":"query","name":"user_token","schema":{"$ref":"#/components/schemas/UserTokenParam"},"style":"form"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigUpdateParam"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigResponse"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}},"description":"Unauthorized Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}},"description":"Not Found"}},"summary":"Update","tags":["Configs"]}},"/keys/{key}/details":{"get":{"deprecated":false,"description":"Returns private data on the key including remaining lookups, available datasets and usage limits.\n","operationId":"KeyDetails","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"explode":false,"in":"query","name":"user_token","schema":{"$ref":"#/components/schemas/UserTokenParam"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyDetailsResponse"}}},"description":"Success"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorised"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource not found"}},"summary":"Details","tags":["Keys"]}},"/keys/{key}/licensees":{"get":{"description":"Returns a list of licensees for a key.","operationId":"ListLicensees","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"description":"Specify ID of the licensee after which you would like to list results","explode":false,"in":"query","name":"starting_after","schema":{"format":"int32","type":"integer"},"style":"form"},{"explode":false,"in":"query","name":"user_token","schema":{"$ref":"#/components/schemas/UserTokenParam"},"style":"form"},{"description":"Specify the maximum number of results to return per page. Default and maximum is `100`.","explode":false,"in":"query","name":"limit","schema":{"$ref":"#/components/schemas/LimitParam"},"style":"form"},{"description":"Filter result by licensee name. Query can be shortened to `q=`","explode":false,"in":"query","name":"query","schema":{"type":"string"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseesResponse"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"}},"summary":"List","tags":["Licensees"]},"post":{"description":"Create a licensee for the specified API Key.","operationId":"CreateLicensee","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"explode":false,"in":"query","name":"user_token","schema":{"$ref":"#/components/schemas/UserTokenParam"},"style":"form"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseeEditable"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseeResponse"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"}},"summary":"Create","tags":["Licensees"]}},"/keys/{key}/licensees/{licensee}":{"delete":{"description":"Cancels a licensee key. This renders a licensee unusable. This action can be reversed if you get in contact with us.","operationId":"DeleteLicensee","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"explode":false,"in":"path","name":"licensee","required":true,"schema":{"$ref":"#/components/schemas/LicenseeParam"},"style":"simple"},{"explode":false,"in":"query","name":"user_token","schema":{"$ref":"#/components/schemas/UserTokenParam"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"code":{"enum":[2000],"format":"int32","type":"integer"},"message":{"enum":["Success"],"type":"string"},"result":{"properties":{"deleted":{"example":1,"format":"int32","minimum":0,"type":"number"}},"required":["deleted"],"type":"object"}},"required":["result","code","message"],"title":"Licensee Delete Response","type":"object"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"}},"summary":"Cancel","tags":["Licensees"]},"get":{"description":"Returns licensee information as identified by the licensee key.","operationId":"RetrieveLicensee","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"explode":false,"in":"path","name":"licensee","required":true,"schema":{"$ref":"#/components/schemas/LicenseeParam"},"style":"simple"},{"explode":false,"in":"query","name":"user_token","schema":{"$ref":"#/components/schemas/UserTokenParam"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseeResponse"}}},"description":"Success","headers":{}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"}},"summary":"Retrieve","tags":["Licensees"]},"put":{"description":"Update Licensee","operationId":"UpdateLicensee","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"explode":false,"in":"path","name":"licensee","required":true,"schema":{"$ref":"#/components/schemas/LicenseeParam"},"style":"simple"},{"explode":false,"in":"query","name":"user_token","schema":{"$ref":"#/components/schemas/UserTokenParam"},"style":"form"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseeEditable"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseeResponse"}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"}},"summary":"Update","tags":["Licensees"]}},"/keys/{key}/lookups":{"get":{"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","operationId":"KeyLogs","parameters":[{"explode":false,"in":"path","name":"key","required":true,"schema":{"$ref":"#/components/schemas/ApiKeyParam"},"style":"simple"},{"description":"An start date/time in the form of a UNIX Timestamp in millisec