How to use the GeoDB Cities API to get the nearest city to a GPS location

Here’s something that happens a lot with successful apps:

1. User meets app.
2. User logs into the app.
3. App says “Greetings user, here is your customized content for <User’s-Current-City>.”
4. App gets the user to come back.

In this article, we walk you through how to use the GeoDB Cities API to implement Step 3 – getting the user’s current city.

The first point to consider is what we mean by ‘current city’. Consider a user drifting 100 miles off the coast of Burma with a satellite phone (and a life jacket). Since Atlantis isn’t yet a thing, we clearly mean the nearest city to the user’s current location. And no offense to podunk towns and villages, but we probably also mean only cities large enough to either have a landing strip or a dungeon to keep a flying dragon. In other words, we mean the nearest city to the user’s current location that has at least some sufficiently large number of people living in it.

The GeoDB Cities API is an online database of the world’s cities, regions, and countries. It offers various city-querying operations with optional filters to get just the cities relevant to a given use-case.

For this use-case, we leverage the Find-Cities-Near-Location operation:

GET /v1/geo/locations/{LOCATION_ID}/nearbyCities
    ?radius={RADIUS}
    &minPopulation={MIN_POPULATION}
    &limit=MAX_RESULTS

Where:

• LOCATION_ID: The GPS latitude/longitude coordinates in ISO-6709 format: ±DD.DDDD±DDD.DDDD
• RADIUS: Only cities within this radius of the location (by default, in miles, unless you specify distanceUnit=KM)
• MIN_POPULATION: Only cities with at least this population
• MAX_RESULTS: The maximum number of cities to return in this request

So the sailor floating somewhere in the Bay of Bengal might send the following HTTP request from his phone:

GET /v1/geo/locations/19.098801+92.979204/nearbyCities
    ?radius=100
    &minPopulation=100000
    &limit=1

From JavaScript

unirest.get("https://wft-geo-db.p.rapidapi.com/v1/geo/locations/19.098801%2B92.979204/nearbyCities?limit=1&minPopulation=100000&radius=100")

.header("X-RapidAPI-Host", "wft-geo-db.p.rapidapi.com")

.header("X-RapidAPI-Key", "YOUR_RAPID-API_KEY")

.end(function (result) {

 console.log(result.status, result.headers, result.body);

});

From PHP

$response = UnirestRequest::get("https://wft-geo-db.p.rapidapi.com/v1/geo/locations/19.098801%2B92.979204/nearbyCities?limit=1&minPopulation=100000&radius=100",

 array(

   "X-RapidAPI-Host" => "wft-geo-db.p.rapidapi.com",

   "X-RapidAPI-Key" => "YOUR_RAPID-API_KEY"

 )

);

From Python

response = unirest.get("https://wft-geo-db.p.rapidapi.com/v1/geo/locations/19.098801%2B92.979204/nearbyCities?limit=1&minPopulation=100000&radius=100",

 headers={

   "X-RapidAPI-Host": "wft-geo-db.p.rapidapi.com",

   "X-RapidAPI-Key": "YOUR_RAPID-API_KEY"

 }

)

The Response

With this request, we should get a single result: the nearest city within one hundred miles of latitude=19.098801, longitude=92.979204, with at least 100,000 people.

{  
   "data":[  
      0:{  
         "id":71941,
         "wikiDataId":"Q738748",
         "type":"CITY",
         "city":"Sittwe",
         "name":"Sittwe",
         "country":"Myanmar",
         "countryCode":"MM",
         "region":"Sagaing Region",
         "regionCode":"01",
         "latitude":20.14624,
         "longitude":92.89835,
         "distance":72.56
      }
   ]   "metadata":{  
      "currentOffset":0,
      "totalCount":1
   }
}

Here, we see the nearest city is Sittwe, Myanmar (formerly Burma). In addition, the response indicates the straight-line distance from the specified location is about 72 miles.

If we want Sittwe’s population, we will have to make another request to get its details as follows:

GET /v1/geo/cities/71941 (or /Q738748)

Try it here in the online demo.

Conclusion

This example should show how easy it is to use GeoDB Cities to query and incorporate just the needed city data in your apps. There’s a whole lot more to check out in the API docs, including the ability to display results in multiple languages.

Explore away, Magellan!

The author’s views are entirely his or her own and may not reflect the views of RapidAPI.