About geocode.city

back to index

This is an open source project with simple goals: fast, city-only geocoding. The data comes from the geonames free data dump for cities with a population of 500 or more (cities500.zip).

The API is written in Haskell and deployed on Heroku, backed by Postgres and Redis. It is free to use, with the following notes:

• All endpoints are suitable to be called from client-side or server-side applications: appropriate CORS headers are sent in every response.
• No guarantees: I run it on cheapo dynos, it should be pretty performant, but if you want greater assurances, you should consider deploying it yourself -- it should be straightforward to do so on Heroku/AWS/GCS, with a modified version of the provided Dockerfile and seed scripts.
• You can make up to 1000 requests per origin, per day. See the info on rate limiting.
• If you need to make more than 1000 requests a day, drop me a note at api (at) geocode.city telling me about your project and I can give you an API key.

If you notice anything amiss, want to contribute a feature, or have ideas for features, please submit an issue.

Rate limiting

To prevent abuse, all API requests are rate limited; there's two methods: client origin (requesting website, or server IP), and API key. (you can see all of the below in action in the interactive documentation.)

You can include an API key either as the api-key querystring parameter or the X-Geocode-City-Api-Key custom header. If you omit it, your requesting origin will be used (for browser-originated requests, this means the Origin header, for any other client, this will be the originating IP Address.) If your API key is invalid (or it has been revoked,) you'll receive responses with status 403 Forbidden.

As mentioned above, a given origin can make up to 1000 requests/day. API keys allow you to make 100,000 requests/month, but we can adjust that if you state your needs -- though beyond that, you probably want to deploy your own.

Once you reach your limit, a status of 429 Too Many Requests will be returned in every response until the rate limit resets. The following headers are included in every response, to help you with rate limiting:

• X-RateLimit-Limit: the number of requests in total you're allowed to make in a given period.
• X-RateLimit-Remaining: the number of requests left in a given time period, before you start getting 429 Too Many Requests errors.
• X-RateLimit-Resets: A unix epoch (in decimal seconds) after which your can start making requests again.