Last modified April 04, 2012

Countries

The countries dataset provides the core data for countries, returning the full name, abbreviations, capital, population area, and neighboring countries.

http://api.aerisframework.com/countries/PLACE_ID

Requirements

HTTP Method	GET
Requires Authentiation	No

Actions

The following actions are supported.

id	`/countries/:id`	Returns data for a place based on the specified id. Refer to the list of supported place value formats.
search	`/countries/search?query=:string`	Searches for data based on a single or combination of queries.

Parameters

All parameters listed below are optional unless noted otherwise.

p	`p=:place`	Defines the location to query data for. Refer to the list of supported place value formats.
limit	`limit=:total`	The total number of results to return as an integer. A maximum of 250 results is enforced. The default limit is 1 if not specified.
query	`query=:string`	Used to filter results based on certain fields in the data set.

Query Elements

Use the following supported property keys when creating custom queries for your requests.

name	Used to query the country full name. String should be lower case.
iso	Used to query the country 2 letter ISO abbreviation. Should be lower case.
iso3	Used to query the country 3 letter ISO abbreviation. Should be lower case.
pop	Used to query the population.
area	Used to query by the area in square kilometers.

Sortable Fields

You can use the following fields to sort the data returned in your response.

name	Used to sort by the country name Example: /countries/search?query=area:500000&sort=name&limit=100 (returns the first 100 countries with at least 500K km of area sorted by the country name)
iso	Used to sort by the country 2 letter abbreviation
iso3	Sort by the country 3 letter ISO abbreviation
pop	Used to sort by the countries population. NOTE: population values are not guaranteed to be accurate and are for general use in limiting results Example: /countries/search?query=area:0&sort=pop:-1&limit=100 (returns the top 100 countries based on population descending)

Supported Place Formats

The countries endpoing support all of the standard supported place formats plus the additional formats that can be passed to the p place parameter.

two-letter ISO country abbreviation	us mx
three-letter ISO country abbreviation	usa mex
full country name	united states mexico
standard formats	Plus all standard place formats are supported

Examples

Return country information the US.
/countries/us

Returns country information for the country specified by zip code 55403 (Minneapolis, MN, US)
/countries/55403

Returns country information for the closest location to the specified latitude/longitude.
/countries?p=45.25,-95.25

Returns up to 100 countries that have a population of at least 30 million. NOTE: population values are not guaranteed to be accurate and are for general use in limiting results
/countries/search?query=pop:30000000&limit=100

Returns up to 10 countries that have an area of 50 - 75 Million square kilometers. NOTE: Area values are not guaranteed to be accurate and are for general use in limiting results
/countries/search?query=profile.area:50000000:75000000&limit=10

Response

The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.

{
    "place":{
        "name":"united states",
        "iso":"us",
        "iso3":"usa",
        "isoNum":"840",
        "fips":"us",
        "continent":"na"
    },
    "profile":{
        "capital":"washington",
        "areaKM":9629091,
        "areaMI":5983239.75,
        "pop":310232863,
        "neighbors":["ca","mx","cu"]
    }
}

Response Properties

The following properties will be provided in every response object.

place.name	(string) The name of the country
place.iso	(string) The countries 2 letter ISO abbreviation
place.iso3	(string) The countries 3 letter ISO abbreviation
place.isoNum	(string) The countries 3 digit ISO numeric id. Kept as string to preserve leading zeros.
place.fips	(string) The FIPS abbreviation for the country
place.continent	(string) The continent abbreviation that the country primarily resides
profile.capital	(string) The name of the capital of the country
profile.areaKM	(number) The approximate area in square kilometers. NOTE: Area values are not guaranteed to be accurate and are for general use in limiting results
profile.areaMI	(number) The approximate area in square miles. NOTE: Area values are not guaranteed to be accurate and are for general use in limiting results
profile.pop	(number) The approximate population of the country. NOTE: population values are not guaranteed to be accurate and are for general use in limiting results
profile.neighbors	(array of strings) Array of the neighboring countries two letter ISO abbreviation.