{ "openapi": "3.0.0", "info": { "title": "Capture_Interactive_Find", "description": "Uses a text search to find addresses and places. Note this does not return formatted addresses, and repeated calls to this service may be required to drill-down through results until an address ID is returned. The address ID should then be passed into the Retrieve service to obtain a fully formatted address.", "version": "1.2" }, "servers": [ { "url": "https://api.addressy.com" } ], "paths": { "/Capture/Interactive/Find/v1.20/json6.ws": { "get": { "tags": [ "Capture_Interactive_Find" ], "summary": "Capture_Interactive_Find", "description": "Uses a text search to find addresses and places. Note this does not return formatted addresses, and repeated calls to this service may be required to drill-down through results until an address ID is returned. The address ID should then be passed into the Retrieve service to obtain a fully formatted address.", "operationId": "Capture_Interactive_Find", "parameters": [ { "name": "Key", "in": "query", "required": true, "description": "The key used to authenticate with the service. For example: 'AA11-AA11-AA11-AA11'.", "schema": { "type": "string" }, "example": "AA11-AA11-AA11-AA11" }, { "name": "Text", "in": "query", "required": true, "description": "The search text to find. Ideally the start of the address, or in some countries a postal code.", "schema": { "type": "string" }, "example": "WR5 3DA" }, { "name": "Container", "in": "query", "description": "A container for the search. This should only be another Id previously returned from this service when the `Type` of the result was not 'Address'.", "schema": { "type": "string" }, "example": "gb-rm|5nDq7pgB1H6m_iwEA3F2" }, { "name": "IsMiddleware", "in": "query", "description": "Whether the API is being called from a middleware implementation (and therefore the calling IP address should not be used for biasing).", "schema": { "type": "boolean" }, "example": "True" }, { "name": "Origin", "in": "query", "description": "A starting location for the search. This can be the name or ISO 2 or 3 character code of a country, WGS84 coordinates (comma separated) or IP address to search from.", "schema": { "type": "string" }, "example": "53.16105,-2.90628" }, { "name": "Countries", "in": "query", "description": "A comma separated list of ISO 2 or 3 character country codes to limit the search within.", "schema": { "type": "string" }, "example": "GB,US,CA" }, { "name": "Limit", "in": "query", "description": "The maximum number of results to return. If left blank, this will default to 10.", "schema": { "type": "integer" }, "example": "10" }, { "name": "Language", "in": "query", "description": "The preferred language for results where the same address matches input in different languages. This parameter will also affect the label \"Addresses\" in the 'Description' field of the Container results, eg. where Language=es, the value will be \"direcciones\". The value should be a 2 or 3 character language code e.g. (en, fr, eng, fre).", "schema": { "type": "string" }, "example": "EN" }, { "name": "Bias", "in": "query", "description": "This setting will enable or disable biasing, which allows Capture to return results that are closer to the end user. See [here](/api-reference/address-capture/bias) for more details. This can also be controlled in the account portal.", "schema": { "type": "boolean" }, "example": "True" }, { "name": "Filters", "in": "query", "description": "This setting allows filtering of addresses returned by the Find method. Supported filters are described on the [Filters page](/api-reference/address-capture/filters).", "schema": { "type": "string" }, "example": "Locality:Worcester" }, { "name": "Type", "in": "query", "description": "This setting is only applicable if you have OS AddressBase Premium dataset enabled. For usage, check out [search type](/api-reference/address-capture/search-type) for more details.", "schema": { "type": "string" }, "example": "UPRN" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response" }, "examples": { "Success": { "summary": "Success", "value": { "Items": [ { "Id": "GB|RM|B|55605138|ENG", "Type": "Address", "Text": "G B G Evermore 128 Queen Victoria Street", "Highlight": "0-1,2-3,4-5", "Description": "London EC4V 4BJ" } ] } } } } } }, "400": { "description": "BadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Text or Container Required": { "summary": "Text or Container Required", "value": { "Items": [ { "Error": "1001", "Description": "Text or Container Required", "Cause": "The Text or Container parameters were not supplied.", "Resolution": "Check they were supplied and try again." } ] } }, "Text or Container Invalid": { "summary": "Text or Container Invalid", "value": { "Items": [ { "Error": "1002", "Description": "Text or Container Invalid", "Cause": "The Text or Container parameter was not recognised.", "Resolution": "Check the documentation for valid options." } ] } }, "Origin Invalid": { "summary": "Origin Invalid", "value": { "Items": [ { "Error": "1003", "Description": "Origin Invalid", "Cause": "The Origin parameter was not recognised. Check the spelling and, if in doubt, use a valid ISO 2 or 3 digit country code.", "Resolution": "Provide a valid ISO 2 or 3 digit country code or use a web service to convert country name to ISO code." } ] } }, "Language Invalid": { "summary": "Language Invalid", "value": { "Items": [ { "Error": "1004", "Description": "Language Invalid", "Cause": "The Language parameter was not recognised.", "Resolution": "Please check what you entered and try again." } ] } }, "No response": { "summary": "No response", "value": { "Items": [ { "Error": "1005", "Description": "No response", "Cause": "The query didn't respond fast enough, it may be too complex.", "Resolution": "Please check what you entered and try again with something more specific." } ] } }, "Invalid Input": { "summary": "Invalid Input", "value": { "Items": [ { "Error": "1006", "Description": "Invalid Input", "Cause": "Bad input detected.", "Resolution": "Please check what you entered and try again." } ] } }, "Invalid Country": { "summary": "Invalid Country", "value": { "Items": [ { "Error": "1007", "Description": "Invalid Country", "Cause": "Invalid input for the selected country detected.", "Resolution": "Please check what you entered and try again." } ] } }, "Unauthorised Dataset": { "summary": "Unauthorised Dataset", "value": { "Items": [ { "Error": "1008", "Description": "Unauthorised Dataset", "Cause": "A dataset was requested that is not authorised on this account.", "Resolution": "Please contact us to arrange authorisation of datasets." } ] } }, "Request not allowed from this IP": { "summary": "Request not allowed from this IP", "value": { "Items": [ { "Error": "4", "Description": "Request not allowed from this IP", "Cause": "The request was disallowed from the IP address.", "Resolution": "Check the security settings on the key first. If they look fine, please contact support as it may be from an IP address on our blacklist." } ] } }, "Request not allowed from this URL": { "summary": "Request not allowed from this URL", "value": { "Items": [ { "Error": "5", "Description": "Request not allowed from this URL", "Cause": "The request was disallowed from the URL.", "Resolution": "Check the security settings on the key first. If they look fine, please contact support as it may be from a URL on our blacklist." } ] } }, "Web service not available on this key": { "summary": "Web service not available on this key", "value": { "Items": [ { "Error": "6", "Description": "Web service not available on this key", "Cause": "The requested web service is disallowed on this key.", "Resolution": "Check the security settings on the key first. You can limit a key to certain web services." } ] } }, "Missing or invalid parameters": { "summary": "Missing or invalid parameters", "value": { "Items": [ { "Error": "18", "Description": "Missing or invalid parameters", "Cause": "A required parameter was not supplied of the value of a parameter cannnot be converted into the right type.", "Resolution": "Check the parameters passed and their values against the specification for this service." } ] } }, "Invalid JSON object": { "summary": "Invalid JSON object", "value": { "Items": [ { "Error": "19", "Description": "Invalid JSON object", "Cause": "The JSON object sent in your request is invalid.", "Resolution": "Please ensure your JSON object is syntactically correct and try again." } ] } }, "Endpoint not available": { "summary": "Endpoint not available", "value": { "Items": [ { "Error": "20", "Description": "Endpoint not available", "Cause": "The web service you are calling is not available on this endpoint", "Resolution": "Refer to our documentation pages to ensure you are calling a valid endpoint for the web service you are requesting." } ] } }, "Sandbox Mode is not available on this endpoint": { "summary": "Sandbox Mode is not available on this endpoint", "value": { "Items": [ { "Error": "21", "Description": "Sandbox Mode is not available on this endpoint", "Cause": "The License key used has Sandbox Mode enabled, but the testing functionality is not available on this endpoint.", "Resolution": "Disable the Sandbox Mode on the License key." } ] } }, "HTTPS requests only": { "summary": "HTTPS requests only", "value": { "Items": [ { "Error": "22", "Description": "HTTPS requests only", "Cause": "As of 3rd September 2018 all new accounts must use HTTPS.", "Resolution": "Ensure you consume all of our APIs over HTTPS and not HTTP." } ] } } } } } }, "500": { "description": "InternalServerError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Unknown error": { "summary": "Unknown error", "value": { "Items": [ { "Error": "-1", "Description": "Unknown error", "Cause": "The cause of the error is unknown but details have been passed to our support staff who will investigate.", "Resolution": "These problems are typically short lived and are often resolved by trying again in a few minutes." } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Unknown key": { "summary": "Unknown key", "value": { "Items": [ { "Error": "2", "Description": "Unknown key", "Cause": "The key you are using to access the service was not found.", "Resolution": "Please check that the key is correct. It should be in the form AA11-AA11-AA11-AA11." } ] } }, "Agreement Not Signed": { "summary": "Agreement Not Signed", "value": { "Items": [ { "Error": "23", "Description": "Agreement Not Signed", "Cause": "There are agreements associated with service which are not signed.", "Resolution": "Please go to your account and check your agreements." } ] } }, "Not enough credit for request": { "summary": "Not enough credit for request", "value": { "Items": [ { "Error": "24", "Description": "Not enough credit for request", "Cause": "There is not enough credit on the account to process the request.", "Resolution": "Please topup your account with credit." } ] } }, "Unexpected error, please contact the help desk for more information": { "summary": "Unexpected error, please contact the help desk for more information", "value": { "Items": [ { "Error": "25", "Description": "Unexpected error, please contact the help desk for more information", "Cause": "", "Resolution": "" } ] } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Account out of credit": { "summary": "Account out of credit", "value": { "Items": [ { "Error": "3", "Description": "Account out of credit", "Cause": "Your account is either out of credit or has insufficient credit to service this request.", "Resolution": "Please check your account balance and top it up if necessary." } ] } }, "Web service not available on your plan": { "summary": "Web service not available on your plan", "value": { "Items": [ { "Error": "7", "Description": "Web service not available on your plan", "Cause": "The requested web service is not currently available on your payment plan.", "Resolution": "Some services are only available in specific regions due to licensing restrictions. Please contact us for more information." } ] } }, "Key daily limit exceeded": { "summary": "Key daily limit exceeded", "value": { "Items": [ { "Error": "8", "Description": "Key daily limit exceeded", "Cause": "The daily limit on the key has been exceeded.", "Resolution": "Alter the daily limit on the key. Check the usage details first to see if usage is normal." } ] } }, "Your account has been suspended": { "summary": "Your account has been suspended", "value": { "Items": [ { "Error": "9", "Description": "Your account has been suspended", "Cause": "Your account has been suspended. This can be for a number of reasons including non-payment of an invoice.", "Resolution": "Please contact us in order to resolve this issue." } ] } }, "Surge protector triggered": { "summary": "Surge protector triggered", "value": { "Items": [ { "Error": "10", "Description": "Surge protector triggered", "Cause": "An unusually large number of requests have been processed for your account so the surge protector has been enabled.", "Resolution": "You can disable the surge protector at any time but this is only recommended if you are running through a batch of requests." } ] } }, "No valid license available": { "summary": "No valid license available", "value": { "Items": [ { "Error": "11", "Description": "No valid license available", "Cause": "The request requires a valid license but none were found.", "Resolution": "Please check your purchase history. You may be using a license that is no longer valid or of an incorrect type." } ] } }, "Management key required": { "summary": "Management key required", "value": { "Items": [ { "Error": "12", "Description": "Management key required", "Cause": "To use this web service you require a management key. Management can be enabled on any key, but we advise you to use management keys with care.", "Resolution": "Sign in to the website and create a new management key or change an existing key." } ] } }, "Demo limit exceeded": { "summary": "Demo limit exceeded", "value": { "Items": [ { "Error": "13", "Description": "Demo limit exceeded", "Cause": "The daily demonstration limit for this service or account has been exceeded.", "Resolution": "The limit will be reset at midnight tonight. If you would like the limit increased, please contact us." } ] } }, "Free service limit exceeded": { "summary": "Free service limit exceeded", "value": { "Items": [ { "Error": "14", "Description": "Free service limit exceeded", "Cause": "You have used too many free web services.", "Resolution": "Our web services are designed to operate in stages. The first is usually a Find service followed by a Retrieve. If you use too many Finds without the corresponding number of Retrieves you will receive this error. For more information, please contact us." } ] } }, "Wrong type of key": { "summary": "Wrong type of key", "value": { "Items": [ { "Error": "15", "Description": "Wrong type of key", "Cause": "The type of key you're using isn't supported by this web service.", "Resolution": "This usually happens if you're using a user or server license with a web service that only supports transactional keys. Please use another key and try again." } ] } }, "Key expired": { "summary": "Key expired", "value": { "Items": [ { "Error": "16", "Description": "Key expired", "Cause": "The key you are trying to use has expired.", "Resolution": "Please check that you are using the right key. A new one may have been issued if you recently renewed your key. Contact us if you have any questions." } ] } }, "Individual User exceeded Lookup Limit": { "summary": "Individual User exceeded Lookup Limit", "value": { "Items": [ { "Error": "17", "Description": "Individual User exceeded Lookup Limit", "Cause": "An Individual User has exceeded their daily lookup limit on the key and that user will be prevented from using your service until tomorrow (GMT)", "Resolution": "Check the usage details. If required, increase the Lookup Limit per Individual User or add the specific Individual User's IP to the Limiter Exclusions" } ] } }, "Additional account verification required to use this web service on a Trial account.": { "summary": "Additional account verification required to use this web service on a Trial account.", "value": { "Items": [ { "Error": "26", "Description": "Additional account verification required to use this web service on a Trial account.", "Cause": "The requested web service cannot be used on a Trial account without additional account verification.", "Resolution": "To use this web service, please add a payment card to your account or speak to your account manager." } ] } } } } } } } } } }, "components": { "schemas": { "response": { "properties": { "Items": { "type": "array", "items": { "properties": { "Id": { "type": "string", "description": "The unique Id of the returned address (or Container - for further results) as generated by Capture (note that this Id can change over time)." }, "Type": { "type": "string", "description": "The 'type' of the returned Id. The possible values are Address | Container | Postcode | Street | BuildingName | Building. If the `Type` is 'Address' then the Id can be passed to the Retrieve service. Any other Id should be passed as the Container to a further Find request to get more results." }, "Text": { "type": "string", "description": "The first half of the address that's displayed to the user. For example, if the returned address is '123 High Street Nairn IV12 4DB United Kingdom' then `Text` will display '123 High Street'." }, "Highlight": { "type": "string", "description": "A list of number ranges showing which characters in the `Text` and `Description` fields match the user's search term. This can be used to determine which characters should be highlighted in bold in the search field, to give the user a visual representation of what's being searched. If a Container Id is included in the Find request, `Highlight` will be empty. It will be populated for any other request. See [here](/api-reference/address-capture/highlight) for further details." }, "Description": { "type": "string", "description": "The second half of the address that's displayed to the user, including the number of addresses if the search returns a Container. For example, if a search for the postcode 'IV12 4DB' returns a Container of 125 addresses all on 'High Street', then `Description` would display 'Nairn IV12 4DB United Kingdom - 125 Addresses'." } } } } } }, "error": { "properties": { "Items": { "type": "array", "items": { "properties": { "Error": { "type": "string", "description": "The id of the error returned" }, "Description": { "type": "string", "description": "A description of the error" }, "Cause": { "type": "string", "description": "The cause of the error" }, "Resolution": { "type": "string", "description": "Actions to resolve the error" } } } } } } }, "securitySchemes": { "ApiKeyQuery": { "type": "apiKey", "name": "Key", "in": "query" } } }, "security": [ { "ApiKeyQuery": [] } ] }