Introduction

Places API is a RESTful API based on the Geonames database.

The GeoNames geographical database covers all countries and contains over eleven million placenames that are available for download free of charge.

The Places API utilizes Geonames' data dumps to provide its services.

These data dumps are automatically downloaded and parsed on a daily basis. The data is then cleaned up and exposed through an expressive and RESTful API.

If you enjoy using the Places API, please consider supporting me:

Authentication

The Places API authenticates your API requests using your account's API keys. If a request doesn't include a valid key, Places API returns an authentication error.

You can use the dashboard to create, delete, and regenerate API keys.

Authentication to the API is performed via HTTP Bearer Auth. When making requests using API tokens, the token should be included in the Authorization header as a Bearer token:

Authorization: Bearer <TOKEN>

Rate-Limiting

At this point in time, users can make a 25 requests per minute to the API before getting rate-limited.

You can determine how many requests you have remaining by inspecting the Response Headers of your Request:

X-RateLimit-Limit: 25
X-RateLimit-Remaining: 10

Querying Relations

You can query a relation by adding the include query parameter to the request.

Let's say you need to get all countries with their respective languages, then your request would look like this:

GET /api/v1/countries?include=languages

You can also query multiple relations by comma-separating the relations in the query string.

GET /api/v1/countries?include=languages,neighbours,flag

Filtering Results

To filter a result set, you can add the filter query parameter to the request.

For example, the following request returns all the place names in Australia (AU) that have a feature code of ADM1 (first-order administrative division).

GET /api/v1/countries/AU/places?filter[featureCode][eq]=ADM1

You can combine multiple filters to get a more specfic result set.

GET /api/v1/countries/AU/places?filter[featureCode][eq]=FLLS&filter[name][eq]=Wallaman Falls&include=location

The above request will return any waterfalls (FLLS) having the name Wallaman Falls in Australia. It also includes the location of the place in the response.

Operators

Comparison operators

Some of the available endpoints allow you to scope results using comparison operators. For example:

GET /api/v1/countries/AU/places?filter[featureCode][eq]=ADM1&filter[population][gte]=2000000

The above request will return all Australian states that have a population greater than or equal to 2,000,000.

Logical operators

Sorting results

All API results are sorted by their primary key by default. However, you are free to change the sort criteria by adding the sort query parameter to the request.

The below request will return all the countries sorted by population in ascending order.

GET /api/v1/countries?sort=population

To sort in descending order, simply add a - to the sort paramter.

GET /api/v1/countries?sort=-population

The above request will return all the countries sorted by population in descending order.

It is also possible to sort by multiple criteria by adding comma-separated sort parameters.

GET /api/v1/countries?sort=population,iso3166Alpha2

Pagination

Places API uses cursor based pagination to return paginated data. Cursor pagination will offer better performance for larger data-sets.

The cursor is an encoded string containing the location that the next paginated query should start paginating and the direction that it should paginate.

You can fetch the data on different pages by adding the page[cursor] query parameter to the request.

GET /api/v1/featureCodes?page[cursor]=eyJpc28zMTY2X2FscGhhMiI6IkFXIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ

By default, all API results are paginated with a total of 10 results per page. However, you are free to change the number of items per page using the page[size] query parameter.

GET /api/v1/featureCodes?page[size]=5&page[cursor]=eyJpc28zMTY2X2FscGhhMiI6IkFXIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ

The Places API will always return pagination data when it exists. This includes links to the next and previous pages of data in addition to meta data to help you build easily build UIs based using the API.

Examples

Before you begin make sure to take a look at this additional resource.

The featureClass is a rough categorization further enhanced by the featureCode which describes the feature in more detail. All places in the Places API are categorized into one out of 9 feature classes and further subcategorized into one out of 680 feature codes.

Eight-thousander mountains

GET /api/v1/places?filter[featureClass][eq]=T&filter[featureCode][eq]=MT&filter[elevation][gte]=8000&sort=-elevation

First, we begin by filtering all places to only those having featureClass equal to T. This limits our result set to places that are: "Mountain, hill, or Rock...".

Now, we filter by featureCode equal to MT which limits the result to only mountains.

To get only mountains that are of elevation higher or equal to 8,000 meters, we use the logical operator gte.

Finally, we sort in descending order using sort=-elevation.

States of the USA

GET /api/v1/countries/US/places?filter[featureClass][eq]=A&filter[featureCode][eq]=ADM1

First, we get all the places in the United States using the endpoint /api/v1/countries/US/places.

Next, we filter all those places to only ones having featureClass equal to A. This limits our result set to places that are: "Country, state, region,..." in the US.

Then, we filter by featureCode equal to ADM1 which represents a "First-order administrative division" (i.e. state).

Top-5 most populated capitals of the world

GET /api/v1/places?filter[featureClass][eq]=P&filter[featureCode][eq]=PPLC&sort=-population&page[size]=5

First, we begin by filtering all places to only those having featureClass equal to P. This limits our result set to places that are: "City, village...".

Then, we filter by featureCode equal to PPLC which limits the result to only places that are a "Capital of a political entity".

To get the capitals in the correct order, we sort by population in descending order.

Finally, we limit the result set to only the top 5 capitals using page[size]=5.

Portuguese-speaking countries

GET /api/v1/countries?filter[languageCodes][eq]=por&include=languages

We filter all countries by languageCodes equal to por; i.e. the ISO 639-3 language code of Portuguese.

Using include=languages is optional and will give you additional information about the languages spoken in a country.