Getting Started

The core offering of Zippopotam.us is a free, open source API that allows application developers to do various things with postal and US ZIP codes.

GeoNames data is ingested into a RediSearch instance which is then queried by the Zippopotam.us API service which is written in Go.

Core Use Cases

Some of the core use cases for implementing the Zippopotam.us service in your website or application are:

  1. Pre-filling city and state/province based on postal code

  2. Finding POIs around a user when you only have their postal or zip code.

  3. Looking up cities or places by name to get a centroid latitude and longitude pair to use in queries against data stores that allow for searching by location.

Data Coverage and Accuracy

All data in the Zippopotam.us API service is from GeoNames. Data served through the service is provided "as-is" without any guarantee on accuracy, coverage, etc.

GeoNames also notes the following postal code restrictions that are by extension applicable to this service:

For Canada we have only the first letters of the full postal codes (for copyright reasons)
For Chile we have only the first digits of the full postal codes (for copyright reasons)
For Ireland we have only the first letters of the full postal codes (for copyright reasons)
For Malta we have only the first letters of the full postal codes (for copyright reasons)
The Argentina data file contains the first 5 positions of the postal code.
For Brazil only major postal codes are available (only the codes ending with -000 and the major code per municipality).

Adding or Correcting Postal Data

Since Zippopotam.us doesn't curate or maintain its own data, any and all data corrections or additional data should be contributed directly to GeoNames.

Cross-Origin Resource Sharing (CORS)

The API service has CORS enabled, which should allow consuming developers to use the service from Javascript run in the browser from any website.