General Info
Locations
General Information
- The Locator Centric API provides subscribers access to location based data via a simple RESTful web interface
- Access to the Locator Centric API requires an API key. Contact LocatorCentric@AccuWeather.com to receive an API key.
- A partner code will be provided to you by your Locator Centric representative.
- Data is available in more than 40 languages and dialects
- Use hostname: api.locatorcentric.com
- Data responses are returned in JSON
- SSL (Secure Sockets Layer) data encryption is also available for secure communication with your set up. This is done with the use of “https://” scheme in your URLs.
- JSONP is available. Please use “parse_response” as the callback parameter
Status Codes
- Requests will return an appropriate status code.
- It is possible to suppress the error codes by passing allowError=false in the query. In that case, the status will always be 200, barring a 500 error from the server itself.
- An error response will describe the specifics of any errors.
| Error Code | Error Name | Description |
| 200 | OK | Request was fulfilled |
| 400 | Bad Request | Request had bad syntax or the parameters supplied were invalid |
| 403 | Forbidden | Valid API Key was not supplied in the query |
| 404 | Not Found | Server has not found a route matching the given URI |
| 500 | Internal Error | Server encountered an unexpected condition which prevented it from fulfilling the request |
Resources
Locations
- Locations may be cities, points of interest, postal codes, countries, administrative areas (i.e. states and provinces) or regions.
Best Practices
- Use GZIP compression
- Randomize refresh rates
- Refresh data using the exipires header from the response
- IMPORTANT: Time zone offset changes due to Daylight Saving time
Use GZIP compression
- Reduces the size of data being transmitted to the device
- Increases the speed of the data requests
- GZIP compression is easily turned on by adding HTTP headers
Curl Example:
| curl -H “Accept-Encoding: gzip,deflate” “http://api.locatorcentric.com/locations/v1/search?q=san&apikey={your key}” |
- Without compression, size=17695 bytes
- With compression, size=2958 bytes
Java Example:
| HttpUriRequest=new HttpGet(http://api.locatorcentric.com/locations/v1/search?q=san&apikey={your key}); request.addHeader(“Accept-Encoding”, “gzip”); // … httpClient.execute(request); |
Randomize refresh rates
- Add some type of randomization to the individual device refresh time so that all devices don’t refresh at the same clock time.
- For example, do not request updates on all devices at :00 and :30 past the hour
Use Expires header
- Refresh information from the Locator Centric API for your device based upon the cache expires time in the response headers
Example:
| Response Headers Cache-Control: public Content-Encoding: gzip Content-Type: application/json; charset=utf-8 Date: Wed, 29 Aug 2012 14:55:33 GMT Expires: Thu, 30 Aug 2012 14:56:34 GMT Server: Microsoft-IIS/7.5 Server: Microsoft-IIS/7.0 Transfer-Encoding: chunked Vary: Accept-Encoding X-AspNet-Version: 4.0.30319 X-Powered-By: ASP.NET |
- In this example, do not refresh until: Thu, 30 Aug 2012 14:56:34 GMT
Timezone Offset Changes for Daylight Savings
- If you intend to use the GMTOffset from the Location Api response to calculate times local to the location, you MUST be careful to observe the NextOffsetChange property. The offset will change on the date and time specified.
- Using the expires header as described above will ensure that you have the most current GMTOffset for the location.
Languages
- Below are the available world languages and their corresponding language_code for use with the API. All of the language codes have been derived from the ISO 639-1 Alpha-2 codes. Languages that support additional localizations can be expanded to show a list of the localizations. All of the localization codes have been drived from the Microsoft Language Codes.
| Language | Language Code | Localizations |
| Arabic | ar |
| Bengali* (Coming Soon) | bn | |
| Bosnian* (Coming Soon) | bs | |
| Bulgarian* | bg | |
| Catalan | ca | |
| Croatian* | hr | |
| Czech | cs | |
| Chinese | zh |
| Danish | da | |
| Dutch | nl |
| English | en |
| Estonian* | et | |
| Farsi* | fa | |
| Filipino* | ph | |
| Finnish | fi | |
| French | fr |
| German | de |
| Greek | el | |
| Hebrew | he | |
| Hindi | hi | |
| Hungarian | hu | |
| Icelandic* (Coming Soon) | is | |
| Indonesian | id | |
| Italian | it |
| Japanese | ja | |
| Kazakh* | kk | |
| Korean | ko | |
| Latvian* | lv | |
| Lithuanian* | lt | |
| Macedonian* | mk | |
| Malaysian* | ms | |
| Montenegrin* (Coming Soon) | sr-me | |
| Norwegian | no | |
| Polish | pl | |
| Portuguese | pt |
| Romanian | ro |
| Russian | ru |
| Serbian* | sr | |
| Slovak | sk | |
| Slovenian | sl | |
| Spanish | es |
| Swahili* (Coming Soon) | sw |
| Swedish | sv |
| Thai* | th | |
| Turkish | tr | |
| Ukrainian | uk | |
| Urdu* (Coming Soon) | ur | |
| Vietnamese* | vi |
- * – Denotes a language that is only supported in the new API architecture. They will be available in future releases of the Mobile and Traditional websites.
Glossary
- alias: Alternate names that are used to account for common alternate spellings (Saint Louis, St. Louis, St Louis), historical names (Ho Chi Minh City, Saigon), and accepted alternate names (Derry, Londonderry). Inclusion of aliases in search results can be controlled by setting the Alias enumeration value. Enumeration values: Never, Always, NoOfficialMatchFound. Default value set to NoOfficialMatchFound.
- API key: Unique client code used for identification and authorization purposes. Gateway for access to the API. Contact Locator Centric to receive an API key.
- City ID: Unique ID that can be used to search for a specific location. This may also be referred to as the locationkey.
- Constituent Country: A country which makes up a part of a larger country, or federation. The United Kingdom is made of 4 constituent countries. They are England, Scotland, Wales and Northern Ireland.
- group: Integer indicates the number of cities to return with the request. Current supported values are 50, 100, and 150.
- IP address: Internet protocol address. A numeric code that identifies a device connected to the internet.
- language: String indicating the language in which to return the resource. Default value set to en-us. Click here to see a list of available language codes.
- limit: Integer indicates the number of resources to return with the request. Default value set to 25.
- Localization: The process of translating information into different languages or adapting a product for a specific country or region. Within the API setting, this term is used to represent languages, including the localized dialects.
- offset: Integer along with the limit determines the first resource to return. Default value set to 0.
- Poi type: Point of interest type. Available types: amusement park, aquarium, art, balloon, stadium, botanical, brewery, winery, vineyard, distillery, building, casino, driving range, embassy, observatory, performing arts, planetarium, resort, shopping, zoo, tennis, sports, racing, polo, ski, camp, county park, national park, nature preserve, state park, waterfall, bridge, historic, monument/ statue, museum, state capitol, random, airports, Olympics. Default is all poi types included.
- Rank: Number applied to locations set by factors such as population, political importance, and geographic size. Location search results are returned in rank order. A lower rank number represents a city of larger population, political importance, an important location of commerce or larger geographic size. A rank value of “10” would be considered the highest ranking location.
- Resolution: Measure of the sharpness of an image. This can be found as a parameter for the Imagery API.
- Verified Location: A term used to describe a location that has been verified by our primary location data provider. For searches that return multiple results, verified locations will always be returned at the top of the list. Only verified locations will be used in GeoLookup and AutoComplete searches. Also, only verified locations will be supported for localizations (translations). An unverified location can be added to the verified list, provided that there is credible information to confirm the latitude/longitude, name, country, and primary administrative code.
Locations
General Information
- The Locator Centric API provides subscribers access to location based data via a simple RESTful web interface.
- Subscribers may search for world wide regions, countries, administrative areas, and locations.
- There are three types of locations that can be queried: cities, points of interest, and postal codes.
- If the type is specified in the url, the result will only return that type.
- Locations of any type may be retrieved using the unique location key as provided by Locator Centric.
- A location key for a particular location can be obtained from the response of a text search, city search, geolookup search, postal code search, or point of interest search.
- Use GeoLookup searching in order to search for a location via latitude and longitude coordinates. GeoLookups should be performed using the WGS-84 coordinate system.
- Data is available in more than 100 languages and dialects.
Cities
- More than 2 million searchable locations, including 400,000 VerifiedLocations.
- Many cities have alternate names, or aliases, defined to provide flexibility when searching for a particular location. Aliases are used to account for common alternate spellings (Saint Louis, St. Louis, St Louis), historical names (Ho Chi Minh City, Saigon), and accepted alternate names (Derry, Londonderry).
- Only verified locations will be used in GeoLookup and AutoComplete searches.
- Only verified locations will be supported for localizations (translations).
- City searches will always be returned in order of rank, with the most important cities listed at the top.
- Please see the Locations API Guide for examples on how to search for cities.
Postal Codes
- Verified postal code searching is available for the following countries, with the root level of the code in red:
- Canada – Follows the format A0A 0A0. All lookups are based on the Forward Sortation Areas, or FSA, part of the postal code.
- Germany – Follows the format 00000. Many of the postal code names are available in German as well as English.
- United Kingdom – Follows the format A0 0AA, A00 0AA, AA0 0AA, AA00 0AA, A0A 0AA, or AA0A 0AA. All lookups are based on the Postcode Sector. The UK Postal Code system also includes support for the following areas: Guernsey, Isle of Man, and Jersey.
- United States – Follows the format 00000. The US Postal Code system also includes support for the following areas: American Samoa, Federated States of Micronesia, Guam, Marshall Islands, Northern Mariana Islands, Palau, Puerto Rico, and the US Virgin Islands.
- Unverified postal code searching is available for the following countries: Andorra,Argentina, Australia, Austria, Belgium, Brazil, Bulgaria, Croatia, Czech Republic, Denmark, Finland, France, Guatemala, Hungary, Italy, Luxembourg, Mexico, Moldova, Netherlands, New Zealand, Norway, Poland, Russia, Slovakia, Slovenia, Spain, Sweden, Switzerland.A list of the formats for each of these postal codes is available here.
- One postal code can point to many locations; Use Location Key to get back to a specific postal code.
- In many cases, the name for a particular postal code is derived from the location of the post office responsible for that postal code. These names often differ from the cities located in that same area.
- Since postal codes can cover a large area, derived data is mapped based on what best represents the whole area of the postal code.
Points of Interest
- Abbreviated as POI, a Point of Interest is frequently used to refer to business location, tourist location, or other well know site. Common examples of POIs available are Airports, Stadiums, and Parks.
- More than 50,000 searchable Points of Interest.
- More than 12,000 worldwide airports, including the ability to search by airport codes (FAA, ICAO, IATA codes supported).
- Primarily focused on the US, with plans to expand to other countries in the near future, including support for localized names
- A list of the supported POI types is available here.
Auto Complete
General Information
- Allows a user to perform a location lookup with a partial city name
- Search boxes can be automatically populated and refined as a user continues typing
- A full city name is not required
- Helps to suggest location name if a user is unsure of proper spelling
- Available for 400,000 verified locations
- Works for all supported language localizations, however best optimized for Latin based languages
- Top 10 location results are returned. Ordered by rank
- Global caching is implemented to ensure quick reponse times and optimized service for users all over the world
- Please see the Locations API Guide for examples on how to use Autocomplete for searches
- A truncated response is returned for Autocomplete searches. Parameters returned include: Version, Key, Type, Country, Administrative Area and Rank
- Only cities can be seached through Autocomplete. Not designed to work with postal codes.
Regions
- Below are the available regions and their corresponding region_code for use with the API. While each country will only have one primary region listed, any country that spans more than one region will be returned for every region the country falls within. For example, the country of Russia will be returned in both the Europe and Asia lists.
| Region Code | Region Name |
| AFR | Africa |
| ANT | Antarctica |
| ARC | Arctic |
| ASI | Asia |
| CAC | Central America |
| EUR | Europe |
| MEA | Middle East |
| NAM | North America |
| OCN | Oceania |
| SAM | South America |
Countries
- Below are the available countries, dependent territories, and special areas of geographical interest along with their corresponding country_code and region_code for use with the API. All of the country codes have been derived from the ISO 3166-1 Alpha-2 codes.
|
A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
Y
Z
|
Administrative Areas
Primary Administrative Areas
- Every location will have will have one primary administrative area assigned to it.
- The primary administrative area is designated by the Level: 1 code in the AdministrativeArea block of the response.
- Admin Codes have been derived from the ISO 3166-2 codes, where available, focusing on the principal subdivisions.
- If the principal subdivisions of a particular country are not available, the code “00” will be assigned to all locations in that country. The name of the country will be assigned as the administrative name for any “00” codes.
- In the event that a principal subdivision has not yet had an ISO 3166-2 code assigned to it, codes ranging from “X01” to “X99” will be assigned a place holder until the official code has been released.
- Each primary administrative area will also include the administrative classification, such as State, Province, etc.
Examples
| Country Code | Admin Code | Admin Name | Admin Type |
| US | NY | New York | State |
| CA | ON | Ontario | Province |
| FR | J | Île-De-France | Region |
| KR | 11 | Seoul | Special City |
| VA | 00 | Vatican City | |
| TH | X01 | Bueng Kan | Province |
Supplemental Administrative Areas
- Supplemental Administrative Areas can be used to help distinguish between locations that look similar.
- Each area is assigned a number to describe the scale of the administrative subdivisions for countries. As the Level number increases, the scale of the subdivision will decrease.
Political boundaries
- Internationally recognized areas focusing on the secondary subdivisions, where available.
- Level 0
- Used to categorize the Constituent Country, or subcountry, for locations that belong to a country that makes up a part of a larger entity.
- Currently used for locations in the UK to represent England, Scotland, Wales, and Northern Ireland.
- Primary use case – Replace Country Name with Constituent Country Name
- London, United Kingdom
- London, England
- Level 2
- Used to represent secondary subdivisions of the primary administrative areas.
- Primary use case – Include in parentheses after the primary adminstrative information.
- Miami, Florida, United States
- Miami, Florida (Miami-Dade), United States
Examples
| Country Code | Admin Code | City Name | Location Key | Admin Level | Admin Name |
| US | FL | Miami | 347936 | Level 2 | Miami-Dade |
| CA | BC | Vancouver | 53286 | Level 2 | Greater Vancouver |
| GB | ENG-MAN | Manchester | 329260 | Level 0 Level 2 |
England City Centre |
| IN | MH | Mumbai | 204842 | Level 2 | Mumbai Suburban |
| US | CA | Mountain View | 337169 | Level 2 | Santa Clara |
| US | CA | Mountain View | 2274601 | Level 2 | Contra Costa |
Locations API Guide
Types of Searches:
Location Key Searching
| http://api.locatorcentric.com/locations/{version}/{locationKey}{.{format}}?apikey={your key}{&language={language code}}{&details=true or false}} |
Example:
| http://api.locatorcentric.com/locations/v1/335315.json?apikey={your key} |
Text Searching
| http://api.locatorcentric.com/locations/{version}/{countryCode}/{adminCode}/search.{.{format}}?q={search text}&apiKey={your key}{&language={language code}}{&details={true or false}}{&offset={zero based page number}}{&alias={always or never}} |
Examples:
| http://api.locatorcentric.com/locations/v1/fr/search?q=paris&apikey={your key}&language=fr&details=true |
| http://api.locatorcentric.com/locations/v1/search?q=16801&apikey={your key} |
GeoPosition (Latitude and Longitude) Searching
| http://api.locatorcentric.com/locations/{version}/cities/geoposition/search{.{format}}?q={latitude, longitude}&apikey={your key}{&language={language code}}{&details={true or false}} |
Example:
| http://api.locatorcentric.com/locations/v1/cities/geoposition/search.json?q=40, -73&apikey={your key} |
City Searching
| http://{{api} or {{apidev}}.locatorcentric.com/locations/{version}/cities/{countryCode}/{adminCode}/search{.{format}}?q={city name}&apikey={your key}{&language={language code}}{&details={true or false}}{&offset={zero based page number}}{&alias={always or never}} |
Example:
| http://api.locatorcentric.com/locations/v1/cities/US/search.json?q=state college&apikey={your key}&alias=always |
Top City List
| http://api.locatorcentric.com/locations/{version}/topcities/{group}{.{format}}?apikey={your key}{&language={language code}}{&details={true or false}} |
Example:
| http://api.locatorcentric.com/locations/v1/topcities/50.json?apikey={your key} |
City Neighbors
| http://api.locatorcentric.com/locations/{version}/cities/neighbors/{cityID}{.{format}}?apikey={your key}{&language={language code}}{&details={true or false}} |
Example:
| http://api.locatorcentric.com/locations/v1/cities/neighbors/623.json?apikey={your key} |
Postal Code Searching
| http://{{api} or {{apidev}}.locatorcentric.com/locations/{version}/postalcodes/{countryCode}/search{.{format}}?q={postal code}{&language={language code}}{&details={true or false}}&apikey={your key} |
Example:
| http://api.locatorcentric.com/locations/v1/postalcodes/search.json?q=90210&apikey={your key} |
Points of Interest Searching
| http://api.locatorcentric.com/locations/{version}/poi/{countryCode}/{adminCode}/search{.{format}}?q={point of interest}&apikey={your key}{&type={poi type}}{&language={language code}}{&details={true or false}} |
Example:
| http://api.locatorcentric.com/locations/v1/poi/US/CA/search?q=Disney Studios&apikey={your key}&details=true |
IP Address Searching
| http://api.locatorcentric.com/locations/{version}/cities/ipaddress{.{format}}?q={ip address}{&apikey={your key}}{&language={language code}}{&details={true or false}} |
Example:
| http://api.locatorcentric.com/locations/v1/cities/ipaddress?q=38.103.173.150&apikey={your key} |
Regions List
| http://{{api} or {{apidev}}.locatorcentric.com/locations/{version}/regions/{regionCode}{.{format}}{?apikey={your key}}{&language={languageCode}} |
Example:
| http://api.locatorcentric.com/locations/v1/regions.json?apikey={your key} |
Countries List
| http://{{api} or {{apidev}}.locatorcentric.com/locations/{version}/countries/{regionCode}{.{format}}?{apikey={your key}}{&language={languageCode}} |
Example:
| http://api.locatorcentric.com/locations/v1/countries/nam?apikey={your key} |
Countries Search
| http://api.locatorcentric.com/locations/{version}/countries/search{.{format}}?q={search text}{&apikey={your key}}{&language={languageCode}} |
Example:
| http://api.locatorcentric.com/locations/v1/countries/search?q=España&language=es&apikey={your key} |
Administrative Areas List
| http://api.locatorcentric.com/locations/{version}/adminareas/{countryCode}{.{format}}{?apikey={your key}}{&language={languageCode}}{&offset={zero based page number}} |
Example:
| http://api.locatorcentric.com/locations/v1/adminareas/us?limit=10&offset=2&apikey={your key} |
Administrative Areas Search
| http://api.locatorcentric.com/locations/{version}/adminareas/{countryCode}/search{.{format}}?q={search text}{&apikey={your key}}{&language={languageCode}} |
Example:
| http://api.locatorcentric.com/locations/v1/adminareas/US/search?q=pennsylvania&apikey={your key} |
Autocomplete
| http://api.locatorcentric.com/locations/{version}/cities/autocomplete{.{format}}?q={location}{&apikey={your key}}{&language={language code}} |
Examples:
| http://api.locatorcentric.com/locations/v1/cities/autocomplete?q=new&apikey={your key} |
| http://api.locatorcentric.com/locations/v1/cities/autocomplete.json?q=nue&apikey={your key}&language=es |
Location API Parameters
Types of searches | Request parameters | Response parameters
Types of searches – Request URL formats
Location Key Searching
| http://api.locatorcentric.com/locations/{version}/{locationKey}{.{format}}?apikey={your key}{&language={language code}}{&details=true or false}} |
Text Searching
| http://api.locatorcentric.com/locations/{version}/{countryCode}/{adminCode}/search.{.{format}}?q={location name}&apiKey={your key}{&language={language code}}{&details={true or false}}{&limit={number of locations per page}}{&offset={zero based page number}}{&alias={always or never}} |
GeoPosition (Latitude and Longitude) Searching
| http://api.locatorcentric.com/locations/{version}/cities/geoposition/search{.{format}}?q={latitude, longitude}&apikey={your key}{&language={language code}}{&details={true or false}} |
City Searching
| http://api.locatorcentric.com/locations/{version}/cities/{countryCode}/{adminCode}/search{.{format}}?q={city name}&apikey={your key}{&language={language code}}{&details={true or false}}{&limit ={number of locations per page}}{&offset={zero based page number}}{&alias={always or never}} |
Top City List
| http://api.locatorcentric.com/locations/{version}/topcities/{group}{.{format}}?apikey={your key}{&language={language code}}{&details={true or false}} |
City Neighbors
| http://api.locatorcentric.com/locations/{version}/cities/neighbors/{cityID}{.{format}}?apikey={your key}{&language={language code}}{&details={true or false}} |
Postal Code Searching
| http://api.locatorcentric.com/locations/{version}/postalcodes/{countryCode}/search{.{format}}?q={postal code}&apikey={your key}{&language={language code}}{&details={true or false}} |
Points of Interest Searching
| http://api.locatorcentric.com/locations/{version}/poi/{countryCode}/{adminCode}/search{.{format}}?q={point of interest}&apikey={your key}{&type={poi type}}{&language={language code}}{&details={true or false}} |
IP Address Searching
| http://api.locatorcentric.com/locations/{version}/cities/ipaddress{.{format}}?q={ip address}&apikey={your key}{&language={language code}}{&details={true or false}} |
Regions List
| http://api.locatorcentric.com/locations/{version}/regions/{regionCode}{.{format}}?{language={languageCode}}&apikey={your key} |
Countries List
| http://api.locatorcentric.com/locations/{version}/countries/{regionCode}{.{format}}?{language={languageCode}}&apikey={your key} |
Administrative Areas List
| http://api.locatorcentric.com/locations/{version}/adminareas/{countryCode}{.{format}}?{language={languageCode}}{&limit={number of locations per page}}{&offset={zero based page number}}&apikey={your key} |
Administrative Areas Search
| http://api.locatorcentric.com/locations/{version}/adminareas/{countryCode}/search{.{format}}?q={search text}{&language={languageCode}}&apikey={your key} |
Autocomplete
| http://api.locatorcentric.com/locations/{version}/cities/autocomplete{.{format}}?q={location}&apikey={your key}{&language={language code}} |
Location API Query String Parameters
| Parameter | Description | Default value | |
| api | Hostname to be used only in production: api.locatorcentric.com | N/A | Required |
| apikey | Unique code used to access the API | N/A | Required |
| version | Current version of the API | v1 | Required |
| q | Text to match | N/A | Required |
| locationkey | Unique ID used to search for a specific location | N/A | Required |
| format | Format of the response | JSON | Optional |
| language | String indicating the language in which to return the resource | en-us | Optional |
| countryCode | Unique country code ID | No filter | Optional |
| adminCode | Unique administrative area ID | No filter | Optional |
| alias | Enumeration that specifies when the alias locations should be included in the results. By default, an alias will only be returned if no official match was found. Enumeration values: Never or Always | NoOfficialMatchFound | Optional |
| offset | Integer, along with the limit (25), that determines the first resource to return. If no offset is provided, max (100) number of results will be returned | 0 | Optional |
| group | Integer indicates the number of cities to return with the request. Current supported values are 50, 100, and 150. | N/A | Required |
| type | Specific type of point of interest (Only use for point of interest searches) | No filter | Optional |
| cityID | Unique ID used to search for a specific location. This may also be referred to as the locationkey. | N/A | Required |
Location API Response Parameters
| Parameter | Description | |
| Version | Current version of the API | |
| Key | Unique ID to search a location | |
| Type | Location type such as City, PostalCode, POI or LatLong | |
| Rank | Number appiled to locations set by factors such as population, political importance, and geographic size | |
| LocalizedName | Display name in local dialect set with language code in URL. Default is US English (us-en) | |
| EnglishName | Location name as displayed in English | |
| PrimaryPostalCode | Official postal code provided by our main location data provider for the requested location | |
| Region |
| Country |
| AdministrativeArea |
| TimeZone |
| GeoPosition |
| IsAlias | “True” or “false” verification of whether a location is an “alias” or an alternative name or spelling for a requested location |
| SupplementalAdminAreas |
