Validates a city/town against our database, returns a unique LocationCode for the exact city/town.
The LocationCode this method returns is required by (CreatePDF & CreateXML)
Simple HTML form to test method available here: CheckLocation Test Form
| Request Parameters | ||
|---|---|---|
| APIKey | Required | A valid API Key for your user account. Provided in setup email |
| CityTown | Required | City or town to validate |
| CountryISO | Required | Country ISO 3166 Code OR USA State ISO 3166 Code, To search the U.S.A you need to provide a valid US. State Code(Download CSV Country & US State List) |
| OutputFormat | Optional | Default response format is set to XML, select JSON by adding outputformat=JSON to any request. |
| Responses | ||
|---|---|---|
| ResponseStatus | ||
| Code | Code representing errors see result codes to determine the error. | |
| Message | Description of the error | |
| ResponseData | ||
| LocationCode | Unique location code for this City/Town | |
| NameWithRegion | City/Town name with region added, use if you need to prompt user to pick a single city/town from a list of duplicates | |
CheckLocation Result codes
Positive result code indicates success, negative shows a failure.
Success Codes
1 OK – Single city/town found
2 OK – Multiple cities found, prompt user to select correct one. (use NameWithRegion list to prompt user)
Input Errors
-11 Error – City or town not provided
-12 Error – Country or USA state not provided
-13 Error – Country or USA state not a valid ISO 3166-1-alpha-2 code
Action Errors
-31 Error – City or town not found, enter the next nearest large town/city
API Key Errors
-41 Error – Missing API Key
-42 Error – Invalid or expired API Key
System Errors
-91 Error – System error – retry later.
Example Request
Checking City/Town of Penzance in the United Kingdom (CountryISO = GB)
/v2/atlas/CheckLocation/?citytown=Penzance&CountryISO=GB&APIKEY=YOURAPIKEY
Checking City/Town of Orlando, Florida, United States (CountryISO = US-FL)
/v2/atlas/CheckLocation/?citytown=Orlando&CountryISO=US-FL&APIKEY=YOURAPIKEY
Example Response
<CheckLocationResponse> <ResponseData> <CityTown> <LocationCode>8340254</LocationCode> <NameWithRegion>Penzance (Cornwall, England)</NameWithRegion> </CityTown> </ResponseData> <ResponseStatus> <Code>1</Code> <Message>OK - Single city/town found</Message> </ResponseStatus></CheckLocationResponse>