{ "openapi": "3.0.0", "info": { "title": "Geocoding_International_RetrieveNearestPlaces", "description": "Calculates the nearest places of interest of a given category to a given location.", "version": "1" }, "servers": [ { "url": "https://api.addressy.com" } ], "paths": { "/Geocoding/International/RetrieveNearestPlaces/v1.00/json6.ws": { "get": { "tags": [ "Geocoding_International_RetrieveNearestPlaces" ], "summary": "Geocoding_International_RetrieveNearestPlaces", "description": "Calculates the nearest places of interest of a given category to a given location.", "operationId": "Geocoding_International_RetrieveNearestPlaces", "parameters": [ { "name": "Key", "in": "query", "required": true, "description": "The key to use to authenticate to the service.", "schema": { "type": "string" }, "example": "AA11-AA11-AA11-AA11" }, { "name": "Country", "in": "query", "description": "The ISO3 character code for the country to search in. This parameter is optional, but if you wish to use a place for the centre point the country code must be provided.", "schema": { "type": "string" }, "example": "" }, { "name": "CentrePoint", "in": "query", "required": true, "description": "A postcode or coordinates (latitude, longitude) of the centre of the search. Can also be a place name (corresponding country code must be provided).", "schema": { "type": "string" }, "example": "-33.440113067627,149.578567504883" }, { "name": "MaximumItems", "in": "query", "description": "The maximum number of items to return. If 0, all items are returned.", "schema": { "type": "integer" }, "example": "5" }, { "name": "MaximumRadius", "in": "query", "description": "The maximum search distance in KM between the origin and a point of interest. If blank or 0, all items are returned.", "schema": { "type": "number" }, "example": "10" }, { "name": "FilterOptions", "in": "query", "description": "The type of filter to apply where the search returns a list of towns.", "schema": { "type": "string" }, "example": "HideVillages" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response" }, "examples": { "Success": { "summary": "Success", "value": { "Items": [ { "Location": "WR2 6NJ", "Distance": "92.7", "Latitude": "52.2327", "Longitude": "-2.2696" } ] } } } } } }, "400": { "description": "BadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "CentrePoint Required": { "summary": "CentrePoint Required", "value": { "Items": [ { "Error": "1001", "Description": "CentrePoint Required", "Cause": "The CentrePoint parameter was not supplied.", "Resolution": "Please ensure that you supply the CentrePoint parameter and try again." } ] } }, "CentrePoint Invalid": { "summary": "CentrePoint Invalid", "value": { "Items": [ { "Error": "1002", "Description": "CentrePoint Invalid", "Cause": "The CentrePoint parameter must contain a postcode or latitude, longitude coordinate pair separated by commas, or place (in combination with a country code).", "Resolution": "Check the coordinates and try again." } ] } }, "MaximumItems Invalid": { "summary": "MaximumItems Invalid", "value": { "Items": [ { "Error": "1003", "Description": "MaximumItems Invalid", "Cause": "The MaximumItems parameter should be a non-negative integer.", "Resolution": "Check the MaximumItems and try again." } ] } }, "MaximumRadius Invalid": { "summary": "MaximumRadius Invalid", "value": { "Items": [ { "Error": "1004", "Description": "MaximumRadius Invalid", "Cause": "The MaximumRadius parameter should be a non-negative floating point number.", "Resolution": "Check the MaximumRadius and try again." } ] } }, "MaximumTime Invalid": { "summary": "MaximumTime Invalid", "value": { "Items": [ { "Error": "1005", "Description": "MaximumTime Invalid", "Cause": "The MaximumTime parameter should be a non-negative integer.", "Resolution": "Check the MaximumTime and try again." } ] } }, "FilterOptions Invalid": { "summary": "FilterOptions Invalid", "value": { "Items": [ { "Error": "1006", "Description": "FilterOptions Invalid", "Cause": "The FilterOptions parameter should be None, HideVillages, HideSmallTowns or HideTowns.", "Resolution": "Check the FilterOptions parameter and try again." } ] } }, "Country Required": { "summary": "Country Required", "value": { "Items": [ { "Error": "1007", "Description": "Country Required", "Cause": "The Country parameter was not supplied.", "Resolution": "Please ensure that you supply the Country parameter and try again." } ] } }, "Country Unknown": { "summary": "Country Unknown", "value": { "Items": [ { "Error": "1008", "Description": "Country Unknown", "Cause": "The Country 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." } ] } }, "Country Required For Place": { "summary": "Country Required For Place", "value": { "Items": [ { "Error": "1009", "Description": "Country Required For Place", "Cause": "To use a place for the centre point a country must be provided.", "Resolution": "Enter the ISO3 country code corresponding to the place you wish to use for the centrepoint." } ] } }, "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": { "Location": { "type": "string", "description": "The postcode that is nearest to the given location." }, "Distance": { "type": "number", "description": "The distance in KM from the CentrePoint to this record." }, "Latitude": { "type": "number", "description": "The WGS84 latitude coordinate of the location." }, "Longitude": { "type": "number", "description": "The WGS84 longitude coordinate of the location." } } } } } }, "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": [] } ] }