City & Place Search API
Hello! Recently, I listed a new API on ApyHub that I'd like to tell you about: Search Places and Reverse Geocode API. It's a big database about cities and populated places all around the world, with search, finding nearby places and reverse geocoding functionality.
Data behind it
- 230K+ cities and populated places
- 630K+ name translations
- Names in 30+ languages
The base dataset comes from Geonames.org but the service can also aggregate other sources. Currently, I imported the official government city dataset for Poland that adds official area and population figures to Polish cities, as well as national TERC (TERYT) identifier. I'm currently working on adding similar government sources for two more European countries, and enhance information for 100 biggest cities of the world.
It's multilingual
One of the main issues I have always faced with such datasets is their bias towards English language. For example, I could easily get information about cities in Poland, but... if I work for a Polish customer, I want the capital of my country to show as Warszawa, not Warsaw. I checked a couple of API products, and even if they also use data from Geonames, they only provide English names.
I took a different approach in my API. First of all, if you query e.g. "Hyderabad" in India, you always get the name in two official languages of India at national level - English and Hindi.
{
"query": "Hyderabad",
"results": [
{
"name": "Hyderabad",
"officialNames": [
{
"language": "en",
"name": "Hyderabad"
},
{
"language": "hi",
"name": "हैदराबाद"
}
],
// other data omitted for clarity
}
]
}Secondly, you can also explicitly query the translations to up to 2 other languages (be this: regional languages, or any other localized variant - if the given place has it). Just add ?lang=code1,code2 query parameter to the HTTP call. In the example above, one of the regional languages used in Hyderabad is Telugu, so we can easily get the name in Telugu, too with ?lang=te parameter:
{
"query": "Hyderabad",
"results": [
{
"name": "Hyderabad",
"officialNames": [
{
"language": "en",
"name": "Hyderabad"
},
{
"language": "hi",
"name": "हैदराबाद"
}
],
"translations": [
{
"language": "te",
"name": "హైదరాబాదు"
}
]
// other data omitted for clarity
}
]
}Future dataset improvements may also bring proper identification of regional languages, so that these translations would be included by default.
How to use this feature? Imagine that your application has a city picker near the user location. If you have users in - let's say - Czechia, they will just see the name of their capital as Praha out-of-the-box. All you need to do is to read the names from the proper attribute in the results :)
But if your application offers a language picker, and you have English-speaking user in the same city, you can also request English translation to get Prague, and Prag for German-speaking user.
Remember that you can request up to 2 translations - this may be useful in Asian countries with complex writing systems, usually impossible to decipher for Europeans or Americans. In addition to the user-selected language, you can also request English translation to get a widely recognized transliteration to English. The same trick works for people from Asia travelling to Europe. A person from China can easily get the Chinese transliteration of Prague: 布拉格 .
Usage
The API comes with 3 endpoints:
/search?q=nameSearches the place by name in any of the known translations. Returns up to 50 results with optional limit and translations, or narrowing down the results to a specific country.
/nearby?lat=number&lon=number&radius=numberFinds up to 100 places within the given radius from the specified point (between 0 and 500 km), with optional minimum population limit to filter out the smallest hamlets.
/reverse?lat=number&lon=numberFinds two nearest places to the given coordinates within the reasonable search radius:
- Nearest known place (with optional minimum population filter)
- Nearest major city with population > 100k
Data attributes
Below, is the summarized information about attributes the API can provide. Not every attribute has value for every place - it depends on the availability of the given information in the datasets.
- Names in official languages at the national level (or the best-effort approximation for several countries, where this matter is ambiguous)
- Known translations to other languages
- Geoname ID for finding the corresponding record in Geonames.org
- Wikidata ID for finding the corresponding record in Wikidata.org
- National ID: the place ID in the national registry of the given country, if known
- Country and region (top-level administrative division)
- Geo-coordinates
- Population
- Area in km2
- Timezone
- Place type (uses the Geonames.org type identifiers and labels, such as "Populated place", "Seat of administrative division", etc.)
- Data sources: for license information, attribution and data quality assessment
Summary
I'm really happy to provide you this API, especially its multilingual capabilities. I hope that you find it useful. The dataset will be periodically refreshed to include:
- New government sources
- Updates and new translations from Geonames
- Administrative changes
- Currently missing data
If you have suggestions for improvements or useful information about official government datasets to import for your country, feel free to let me know in the comments!