Locator Centric is committed to guide and advocate for the use of Location-Based Services (LBS) as the cornerstone of innovation and growth. Our quest is to strengthen all phases of the location-based and location-aware innovation continuum, from discovery to ideation, enablement to empowerment.Subscribe Now

Locator Centric API

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 sales@LocatorCentric.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

  • 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);

Top of Page

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

Top of Page

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

Top of Page

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.

Top of Page


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

  • admin code: Administrative area code.  Default is no admin code filter.
  • 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 hostname: For production purposes only, use http://api.locatorcentric.com/…
  • 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.
  • country code: Two character country code.  Default is no country code filter.
  • end: Date indicating the end date of a range.
  • GMT Offset: The difference in hours from GMT.
  • 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.
  • JSON: JavaScript Object Notation
  • limit: Integer indicates the number of resources to return with the request.  Default value set to 25.
  • Location key: Unique ID that can be used to search for a specific location.
  • 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.
  • max: Integer specifies the total list size.  This cannot exceed 100.  Default value set to 100.
  • 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.
  • q: Input text to search.
  • 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.  
  • REST: Representational State Transfer
  • start: Date indicating the start date of a range.
  • 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
  • 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
  • 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

Country Name Country Code Region Code
Afghanistan AF ASI
Albania AL EUR
Algeria DZ AFR
American Samoa AS OCN
Andorra AD EUR
Angola AO AFR
Anguilla AI CAC
Antarctica AQ ANT
Antigua and Barbuda AG CAC
Argentina AR SAM
Armenia AM ASI
Aruba AW CAC
Australia AU OCN
Austria AT EUR
Azerbaijan AZ ASI

Top of Page

B

Country Name Country Code Region Code
Bahamas, The BS CAC
Bahrain BH MEA
Bangladesh BD ASI
Barbados BB CAC
Belarus BY EUR
Belgium BE EUR
Belize BZ CAC
Benin BJ AFR
Bermuda BM NAM
Bhutan BT ASI
Bolivia BO SAM
Bonaire BQ CAC
Bosnia and Herzegovina BA EUR
Botswana BW AFR
Bouvet Island BV ANT
Brazil BR SAM
British Indian Ocean Territory IO ASI
British Virgin Islands VG CAC
Brunei BN ASI
Bulgaria BG EUR
Burkina Faso BF AFR
Burundi BI AFR

Top of Page

C

Country Name Country Code Region Code
Cambodia KH ASI
Cameroon CM AFR
Canada CA NAM
Cape Verde CV AFR
Cayman Islands KY CAC
Central African Republic CF AFR
Chad TD AFR
Chile CL SAM
China CN ASI
Christmas Island CX ASI
Cocos (Keeling) Islands CC ASI
Colombia CO SAM
Comoros KM AFR
Cook Islands CK OCN
Costa Rica CR CAC
Cote D’Ivoire CI AFR
Croatia HR EUR
Cuba CU CAC
Curacao CW CAC
Cyprus CY EUR
Czech Republic CZ EUR

Top of Page

D

Country Name Country Code Region Code
Democratic Republic of the Congo CD AFR
Denmark DK EUR
Djibouti DJ AFR
Dominica DM CAC
Dominican Republic DO CAC

Top of Page

E

Country Name Country Code Region Code
Ecuador EC SAM
Egypt EG AFR
El Salvador SV CAC
Equatorial Guinea GQ AFR
Eritrea ER AFR
Estonia EE EUR
Ethiopia ET AFR

Top of Page

F

Country Name Country Code Region Code
Falkland Islands FK SAM
Faroe Islands FO EUR
Federated States of Micronesia FM OCN
Fiji FJ OCN
Finland FI EUR
France FR EUR
French Guiana GF SAM
French Polynesia PF OCN
French Southern Territories TF OCN

Top of Page

G

Country Name Country Code Region Code
Gabon GA AFR
Gambia, The GM AFR
Georgia GE ASI
Germany DE EUR
Ghana GH AFR
Gibraltar GI EUR
Greece GR EUR
Greenland GL ARC
Grenada GD CAC
Guadeloupe GP CAC
Guam GU OCN
Guatemala GT CAC
Guernsey GG EUR
Guinea GN AFR
Guinea-Bissau GW AFR
Guyana GY SAM

Top of Page

H

Country Name Country Code Region Code
Haiti HT CAC
Heard Island and McDonald Islands HM ANT
Honduras HN CAC
Hong Kong HK ASI
Hungary HU EUR

Top of Page

I

Country Name Country Code Region Code
Iceland IS ARC
India IN ASI
Indonesia ID ASI
Iran IR MEA
Iraq IQ MEA
Ireland IE EUR
Isle of Man IM EUR
Israel IL MEA
Italy IT EUR

Top of Page

J

Country Name Country Code Region Code
Jamaica JM CAC
Japan JP ASI
Jersey JE EUR
Jordan JO MEA

Top of Page

K

Country Name Country Code Region Code
Kazakhstan KZ ASI
Kenya KE AFR
Kiribati KI OCN
Kosovo XK EUR
Kuwait KW MEA
Kyrgyzstan KG ASI

Top of Page

L

Country Name Country Code Region Code
Laos LA ASI
Latvia LV EUR
Lebanon LB MEA
Lesotho LS AFR
Liberia LR AFR
Libya LY AFR
Liechtenstein LI EUR
Lithuania LT EUR
Luxembourg LU EUR

Top of Page

M

Country Name Country Code Region Code
Macau MO ASI
Macedonia MK EUR
Madagascar MG AFR
Malawi MW AFR
Malaysia MY ASI
Maldives MV ASI
Mali ML AFR
Malta MT EUR
Marshall Islands MH OCN
Martinique MQ CAC
Mauritania MR AFR
Mauritius MU AFR
Mayotte YT AFR
Mexico MX NAM
Moldova MD EUR
Monaco MC EUR
Mongolia MN ASI
Montenegro ME EUR
Montserrat MS CAC
Morocco MA AFR
Mozambique MZ AFR
Myanmar MM ASI

Top of Page

N

Country Name Country Code Region Code
Namibia NA AFR
Nauru NR OCN
Nepal NP ASI
Netherlands NL EUR
New Caledonia NC OCN
New Zealand NZ OCN
Nicaragua NI CAC
Niger NE AFR
Nigeria NG AFR
Niue NU OCN
Norfolk Island NF OCN
North Korea KP ASI
Northern Mariana Islands MP OCN
Norway NO EUR

Top of Page

O

Country Name Country Code Region Code
Oman OM MEA

Top of Page

P

Country Name Country Code Region Code
Pakistan PK ASI
Palau PW OCN
Palestine PS MEA
Panama PA CAC
Papua New Guinea PG OCN
Paraguay PY SAM
Peru PE SAM
Philippines PH ASI
Pitcairn Islands PN OCN
Poland PL EUR
Portugal PT EUR
Puerto Rico PR CAC

Top of Page

Q

Country Name Country Code Region Code
Qatar QA MEA

Top of Page

R

Country Name Country Code Region Code
Republic of the Congo CG AFR
Reunion RE AFR
Romania RO EUR
Russia RU ASI
Rwanda RW AFR

Top of Page

S

Country Name Country Code Region Code
Saint Barthelemy BL CAC
Saint Helena SH AFR
Saint Kitts and Nevis KN CAC
Saint Lucia LC CAC
Saint Martin MF CAC
Saint Pierre and Miquelon PM NAM
Saint Vincent and the Grenadines VC CAC
Samoa WS OCN
San Marino SM EUR
Sao Tome and Principe ST AFR
Saudi Arabia SA MEA
Senegal SN AFR
Serbia RS EUR
Seychelles SC AFR
Sierra Leone SL AFR
Singapore SG ASI
Sint Maarten SX CAC
Slovakia SK EUR
Slovenia SI EUR
Solomon Islands SB OCN
Somalia SO AFR
South Africa ZA AFR
South Georgia and South Sandwich Islands GS SAM
South Korea KR ASI
South Sudan SS AFR
Spain ES EUR
Spratly Islands SP ASI
Sri Lanka LK ASI
Sudan SD AFR
Suriname SR SAM
Svalbard And Jan Mayen SJ EUR
Swaziland SZ AFR
Sweden SE EUR
Switzerland CH EUR
Syria SY MEA

Top of Page

T

Country Name Country Code Region Code
Taiwan TW ASI
Tajikistan TJ ASI
Tanzania TZ AFR
Thailand TH ASI
Timor-Leste TL ASI
Togo TG AFR
Tokelau TK OCN
Tonga TO OCN
Trinidad and Tobago TT CAC
Tunisia TN AFR
Turkey TR MEA
Turkmenistan TM ASI
Turks and Caicos Islands TC CAC
Tuvalu TV OCN

Top of Page

U

Country Name Country Code Region Code
Uganda UG AFR
Ukraine UA EUR
United Arab Emirates AE MEA
United Kingdom GB EUR
United States US NAM
United States Minor Outlying Islands UM OCN
Uruguay UY SAM
US Virgin Islands VI CAC
Uzbekistan UZ ASI

Top of Page

V

Country Name Country Code Region Code
Vanuatu VU OCN
Vatican City VA EUR
Venezuela VE SAM
Vietnam VN ASI

Top of Page

W

Country Name Country Code Region Code
Wallis and Futuna WF OCN
Western Sahara EH AFR

Top of Page

Y

Country Name Country Code Region Code
Yemen YE MEA

Top of Page

Z

Country Name Country Code Region Code
Zambia ZM AFR
Zimbabwe ZW AFR

Top of Page


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}

Top of Page

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}

Top of Page

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}

Top of Page

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 of Page

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}

Top of Page

 

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}

Top of Page

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}

Top of Page

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

Top of Page

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}

Top of Page

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}

Top of Page

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}

Top of Page

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}

Top of Page

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}

Top of Page

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}

Top of Page

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

Top of Page


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}}

Top of Page

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

Top of Page

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

Top of Page


Location API Code Samples

JavaScript: