GeoDB Cities API

Caching

The importance of caching cannot be overstated. Things like countries and regions change vary rarely and should be aggressively cached. This helps you by keeping your app performant. It also helps 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 sides 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 want to keep the user from accidentally routing themselves where the sun don't shine — never to be heard from again (or just want to do a solid for the free-thinking world) — you might want to exclude certain countries from even being considered.

Below we exclude Iran and the DPRK.

GraphQL

curl --request POST \
     --url https://geodb-cities-graphql.p.rapidapi.com/ \
     --header 'content-type: application/json' \
     --header 'x-rapidapi-host: geodb-cities-graphql.p.rapidapi.com' \
     --header 'x-rapidapi-key: YOUR_API_KEY' \
     --data '{"query":"QUERY"}'

Where QUERY:

{
  populatedPlaces(excludedCountryIds:["IR","KP"], first:10) {
    totalCount
    pageInfo{
      startCursor
      endCursor
      hasNextPage
    }
    edges {
      node {
        id
        name
        country {
          name
        }
      }   
    }
  }
}

REST

curl --get --include 'https://wft-geo-db.p.rapidapi.com/v1/geo/cities?excludedCountryCodes=IR,KP&offset=0&limit=10' \
    -H 'x-rapidapi-key: YOUR_API_KEY' \
    -H 'x-rapidapi-host: wft-geo-db.p.rapidapi.com'