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:

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: