This is the places API by QWeb Ltd. Use this API to get information for countries and regions of the world, including ISO 3166-1 Alpha 2 two letter country codes, administrative regions (states, counties, cities, etc), and latitude/longitude global positions.
We built this API for populating drop-down billing and delivery address fields on website registration forms and checkout systems, replacing our old databases which were compiled by hand in 2013 and only comprised country and top level region information. This newer dataset is built from Geonames data, automatically updated on a monthly basis, and comprises up to 5 levels of administrative regions complete with longitude and latitude data.
This API currently hosts over 300,000 world regions. You can use this places API to pull a list of currently recognised countries, or regions of a given country, or sub-regions of a given region up to 5 levels deep, via simple countries API and regions API endpoints. We automatically refresh our data on a monthly basis to keep up with global political updates, and our endpoints return straight-forward, JSON objects containing ISO-3166-1 alpha 2 country codes, country names, country latitudes and longitudes, region names, region codes, and region latitudes and longitudes.
To use this API, first create a free API Console account and then log in to the API Console to generate an access key.
Once you have an access key, simply send a GET request to https://apis.qweb.co.uk/places/ACCESS_KEY/countries.json and a JSON formatted response will be returned comprising a list of ISO-3166-1 recognised countries, or send a GET request to https://apis.qweb.co.uk/places/ACCESS_KEY/COUNTRY_CODE.json for a list of top level administrative regions within a given country, or send a GET request to https://apis.qweb.co.uk/places/ACCESS_KEY/COUNTRY_CODE-REGION_CODE.json for a list of sub-regions within a given region. You can request regions up to 5 levels deep, separating each region code with a url encoded space (%20), although not all countries have this many administrative levels.
The returned data will be a JSON object containing an answer property, which will either be success if the API key and any given country/region codes are valid, or an error message on fail. Additionally, if the return is successful, the JSON object will contain:
| Endpoint | Section | Properties | Description |
|---|---|---|---|
| countries.json | (Array) | code | ISO-3166-1 alpha 2 country code |
| name | |||
| latitude | |||
| longitude | |||
| COUNTRY_CODE.json | country (Object) | code | ISO-3166-1 alpha 2 country code |
| name | |||
| latitude | |||
| longitude | |||
| regions (Array) | code | Geonames region code | |
| name | |||
| latitude | |||
| longitude | |||
| COUNTRY_CODE-REGION_CODE.json | country (Object) | code | ISO-3166-1 alpha 2 country code |
| tree | Space separated tree of parent region codes | ||
| name | |||
| latitude | |||
| longitude | |||
| region (Object) | code | Geonames region code | |
| name | |||
| latitude | |||
| longitude | |||
| regions (Array) | code | Geonames region code | |
| name | |||
| latitude | |||
| longitude |
All fields are returned. If a field value cannot be determined, it's returned as an empty property or array.
For example, https://apis.qweb.co.uk/places/ACCESS_KEY/us.json will return the following JSON:
{
"country":{
"code":"US",
"name":"United States",
"latitude":"39.760000",
"longitude":"-98.500000"
},
"regions":[
{"code":"AR","name":"Arkansas","latitude":"34.750370","longitude":"-92.500440"},
{"code":"DC","name":"District of Columbia","latitude":"38.917060","longitude":"-77.000250"},
{"code":"DE","name":"Delaware","latitude":"39.000390","longitude":"-75.499920"},
{"code":"FL","name":"Florida","latitude":"28.750540","longitude":"-82.500100"},
{"code":"GA","name":"Georgia","latitude":"32.750420","longitude":"-83.500180"},
{"code":"KS","name":"Kansas","latitude":"38.500290","longitude":"-98.500630"},
{"code":"LA","name":"Louisiana","latitude":"31.000470","longitude":"-92.000400"},
{"code":"MD","name":"Maryland","latitude":"39.000390","longitude":"-76.749970"},
{"code":"MO","name":"Missouri","latitude":"38.250310","longitude":"-92.500460"},
{"code":"MS","name":"Mississippi","latitude":"32.750410","longitude":"-89.750360"},
{"code":"NC","name":"North Carolina","latitude":"35.500690","longitude":"-80.000320"},
{"code":"OK","name":"Oklahoma","latitude":"35.492090","longitude":"-97.503280"},
{"code":"SC","name":"South Carolina","latitude":"34.000430","longitude":"-81.000090"},
{"code":"TN","name":"Tennessee","latitude":"35.750350","longitude":"-86.250270"},
{"code":"TX","name":"Texas","latitude":"31.250440","longitude":"-99.250610"},
{"code":"WV","name":"West Virginia","latitude":"38.500380","longitude":"-80.500090"},
{"code":"AL","name":"Alabama","latitude":"32.750410","longitude":"-86.750260"},
{"code":"CT","name":"Connecticut","latitude":"41.667040","longitude":"-72.666480"},
{"code":"IA","name":"Iowa","latitude":"42.000270","longitude":"-93.500490"},
{"code":"IL","name":"Illinois","latitude":"40.000320","longitude":"-89.250370"},
{"code":"IN","name":"Indiana","latitude":"40.000320","longitude":"-86.250270"},
{"code":"ME","name":"Maine","latitude":"45.500320","longitude":"-69.249770"},
{"code":"MI","name":"Michigan","latitude":"44.250290","longitude":"-85.500330"},
{"code":"MN","name":"Minnesota","latitude":"46.250240","longitude":"-94.250550"},
{"code":"NE","name":"Nebraska","latitude":"41.500280","longitude":"-99.750670"},
{"code":"NH","name":"New Hampshire","latitude":"43.667020","longitude":"-71.499800"},
{"code":"NJ","name":"New Jersey","latitude":"40.167060","longitude":"-74.499870"},
{"code":"NY","name":"New York","latitude":"43.000350","longitude":"-75.499900"},
{"code":"OH","name":"Ohio","latitude":"40.250340","longitude":"-83.000180"},
{"code":"RI","name":"Rhode Island","latitude":"41.750380","longitude":"-71.499780"},
{"code":"VT","name":"Vermont","latitude":"44.000340","longitude":"-72.749830"},
{"code":"WI","name":"Wisconsin","latitude":"44.500240","longitude":"-90.000410"},
{"code":"CA","name":"California","latitude":"37.250220","longitude":"-119.751260"},
{"code":"CO","name":"Colorado","latitude":"39.000270","longitude":"-105.500830"},
{"code":"NM","name":"New Mexico","latitude":"34.500340","longitude":"-106.000850"},
{"code":"NV","name":"Nevada","latitude":"39.250210","longitude":"-116.751190"},
{"code":"UT","name":"Utah","latitude":"39.250240","longitude":"-111.751030"},
{"code":"AZ","name":"Arizona","latitude":"34.500300","longitude":"-111.500980"},
{"code":"ID","name":"Idaho","latitude":"44.500200","longitude":"-114.251180"},
{"code":"MT","name":"Montana","latitude":"47.000250","longitude":"-109.751020"},
{"code":"ND","name":"North Dakota","latitude":"47.500270","longitude":"-100.000680"},
{"code":"OR","name":"Oregon","latitude":"44.000130","longitude":"-120.501390"},
{"code":"SD","name":"South Dakota","latitude":"44.500260","longitude":"-100.250690"},
{"code":"WA","name":"Washington","latitude":"47.500120","longitude":"-120.501470"},
{"code":"WY","name":"Wyoming","latitude":"43.000240","longitude":"-107.500900"},
{"code":"HI","name":"Hawaii","latitude":"20.787850","longitude":"-156.386120"},
{"code":"AK","name":"Alaska","latitude":"64.000280","longitude":"-150.000280"},
{"code":"KY","name":"Kentucky","latitude":"38.200420","longitude":"-84.877620"},
{"code":"MA","name":"Massachusetts","latitude":"42.365650","longitude":"-71.108320"},
{"code":"PA","name":"Pennsylvania","latitude":"40.800000","longitude":"-77.700000"},
{"code":"VA","name":"Virginia","latitude":"37.548120","longitude":"-77.446750"}
],
"answer":"success"
}While https://apis.qweb.co.uk/places/ACCESS_KEY/us-ri.json, using the above RI code for Rhode Island, will return the following JSON:
{
"country":{
"code":"US",
"name":"United States",
"latitude":"39.760000",
"longitude":"-98.500000"
},
"region":{
"code":"RI",
"tree":"",
"name":"Rhode Island",
"latitude":"41.750380",
"longitude":"-71.499780"
},
"regions":[
{"code":"001","name":"Bristol County","latitude":"41.705540","longitude":"-71.286120"},
{"code":"003","name":"Kent County","latitude":"41.673340","longitude":"-71.578950"},
{"code":"005","name":"Newport County","latitude":"41.499800","longitude":"-71.281000"},
{"code":"007","name":"Providence County","latitude":"41.871360","longitude":"-71.578600"},
{"code":"009","name":"Washington County","latitude":"41.396490","longitude":"-71.619660"}
],
"answer":"success"
}And one level deeper, https://apis.qweb.co.uk/places/ACCESS_KEY/us-ri%20001.json, using the above RI code for Rhode Island and 001 code for Bristol County, will return the following JSON:
{
"country":{
"code":"US",
"name":"United States",
"latitude":"39.760000",
"longitude":"-98.500000"
},
"region":{
"code":"001",
"tree":"RI",
"name":"Bristol County",
"latitude":"41.705540",
"longitude":"-71.286120"
},
"regions":[
{"code":"05140","name":"Town of Barrington","latitude":"41.734240","longitude":"-71.319290"},
{"code":"09280","name":"Town of Bristol","latitude":"41.676130","longitude":"-71.273290"},
{"code":"73760","name":"Town of Warren","latitude":"41.724230","longitude":"-71.257670"}
],
"answer":"success"
}Being a REST API, you can access this data from any device with a working Internet connection, using any programming language or development framework that has the ability to request HTTP URIs. The following example is a PHP script using Curl to request and display the latitude and longitude of Rhode Island.
$api = curl_init();
$accessKey = 'YOUR_ACCESS_KEY';
$country = 'US';
$region = 'RI';
curl_setopt($api, CURLOPT_URL, 'https://apis.qweb.co.uk/places/'.$accessKey.'/'.$country.'-'.$region.'.json');
curl_setopt($api, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($api);
curl_close($api);
$data = json_decode($response);
if($data->answer == 'success')
echo $data->region->name.' has a latitude '.$data->region->latitude.', and a longitude '.$data->region->longitude;This IP lookup API has a built-in cache mechanic and is super quick to respond, and we of course aim to keep our servers up at all times, but in case of network issues and for the best possible performance, we recommend building your application to cache the results of your lookups locally. Lookup responses don't change often, so a cache of about 1 month should still be reasonably accurate.
Generate an access key or See our other API services
This service includes data available from http://www.geonames.org.
Copyright © 2023 - 2024 QWeb Ltd. All rights reserved. Company number 11693058. Privacy Policy