GeoDB Cities API

Excluding North Korea & Other Best Practices


The importance of caching cannot be overstated. Things like countries and regions change vary rarely and should be aggressively cached. This helps both you by keeping your app performant and GeoDB by cutting down needless load on the service.

Specifically, you should cache all countries on app startup and lazily cache regions using something like an LRU cache.

You might also use an LRU cache when getting cities by id.

However, due to data refreshes sometimes correcting existing data, it is not recommended to persist any GeoDB data across restarts of your application. If your application is a long-running service, we recommend purging any long-lived caches at least once a week (e.g., the country cache).

Error Handling

Although GeoDB will validate your requests for syntactic and semantic consistency, it would be better for both of us if your app preemptively checks (or proactively prevents) invalid user input as much as possible to avoid sending bad requests in the first place.

For example, your UI might automatically disable the location/excludedCountryCodes filter when retrieving cities in case the includedCountryCodes filter is set.

Excluding Rogue Regimes

And finally, if you're designing something like a travel app and you want to avoid the possibility of the end-user accidentally routing themselves somewhere where the sun don't shine, never to be heard from again - or you just want to do a solid for the free-thinking world - it might be good form to exclude certain countries from even being considered in your city requests.

For example, to exclude Iran and the DPRK:

curl --get --include ',KP&offset=0&limit=10' \
    -H 'X-Mashape-Key: YOUR_API_KEY' \
    -H 'X-Mashape-Host:'