{ "openapi": "3.0.0", "info": { "title": "Capture_Interactive_GeoLocation", "description": "A valuable optional add-on for Capture customers, this Reverse GeoLocationservice takes a latitude longitude point and returns addresses that are within a specified radius. This must be followed by a Retrieve to obtain a fully formatted address.", "version": "1" }, "servers": [ { "url": "https://api.addressy.com" } ], "paths": { "/Capture/Interactive/GeoLocation/v1.00/json6.ws": { "get": { "tags": [ "Capture_Interactive_GeoLocation" ], "summary": "Capture_Interactive_GeoLocation", "description": "A valuable optional add-on for Capture customers, this Reverse GeoLocationservice takes a latitude longitude point and returns addresses that are within a specified radius. This must be followed by a Retrieve to obtain a fully formatted address.", "operationId": "Capture_Interactive_GeoLocation", "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": "Latitude", "in": "query", "required": true, "description": "The latitude of the location you want to return an address for. We recommend using coordinates with up to six decimal degrees for as much granularity as possible.", "schema": { "type": "string" }, "example": "52.182728" }, { "name": "Longitude", "in": "query", "required": true, "description": "The longitude of the location you want to return an address for. We recommend using coordinates with up to six decimal degrees for as much granularity as possible.", "schema": { "type": "string" }, "example": "-2.2221217" }, { "name": "Items", "in": "query", "description": "The maximum number of items to return. This can be set to a maximum of 50.", "schema": { "type": "integer" }, "example": "10" }, { "name": "Radius", "in": "query", "description": "The maximum radius of the geo-location search in metres. This can be set to a maximum of 200 metres.", "schema": { "type": "integer" }, "example": "50" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response" }, "examples": { "Success": { "summary": "Success", "value": { "Items": [ { "Id": "RG|131147105004049155081056163145037055217164007108", "Type": "Address", "Text": "Loqate", "Description": "Worcester, WR5 3DA", "Latitude": "52.182728", "Longitude": "-2.2221217" } ] } } } } } }, "400": { "description": "BadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "Country Unavailable": { "summary": "Country Unavailable", "value": { "Items": [ { "Error": "1001", "Description": "Country Unavailable", "Cause": "The country is not available for reverse geocoding.", "Resolution": "Please ensure that you only attempt to reverse geocode from supported countries." } ] } }, "Unrecognised Input": { "summary": "Unrecognised Input", "value": { "Items": [ { "Error": "1002", "Description": "Unrecognised Input", "Cause": "The input was not in the expected format.", "Resolution": "Make sure to pass valid formatted Latitude and Longitude values." } ] } }, "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": "An address id to pass to the Retrieve endpoint." }, "Type": { "type": "string", "description": "This will always be Address." }, "Text": { "type": "string", "description": "The highest level address details for the returned address; usually either an organisation name/description if available (i.e. the contents of the Company field), otherwise the first line of an address (i.e. Line1)." }, "Description": { "type": "string", "description": "Additional details for the returned address, comprised of the contents of the City and Postcode fields." }, "Latitude": { "type": "string", "description": "The latitude of the returned address." }, "Longitude": { "type": "string", "description": "The longitude of the returned address." } } } } } }, "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": [] } ] }