CheckLocation

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
APIKeyRequiredA valid API Key for your user account. Provided in setup email
CityTownRequiredCity or town to validate
CountryISORequiredCountry 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)
OutputFormatOptionalDefault response format is set to XML, select JSON by adding outputformat=JSON to any request.
Responses
ResponseStatus
CodeCode representing errors see result codes to determine the error.
MessageDescription of the error
ResponseData
LocationCodeUnique location code for this City/Town
NameWithRegionCity/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
      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>