Repository files navigation

Zipcode data is free from the various governments around the world. Yet so many organizations, reputable or not, want to charge money for it.

This project is an automated solution for retrieving and collating US and worldwide zipcode data.

In 2011, we originally pulled down all the US census data we could find, parsed it and exported it into 3 .csv files. Later, we wrote 3 rake tasks to automate this process.

In 2017 we began usingGeoNames data, which is licensed under Creative Commons. We are grateful toGeoNames for sharing, and urge you tovisit their site and support their work.

In 2018 we refactored the project and made it into a Ruby gem with a command-line executable for automating this process.

• An executable:free_zipcode_data - which automates the process of downloading and process the zipcode data from GeoNames. Not all countries are accounted for. Please checkGeoNames to see a list of supported country zip files.

Each zipcode is correlated with estimated or zip-centroid, latitude and longitude coordinates. Where applicable, country, county/province, state and community are also correlated.

See the GeoNamesreadme.txt file for more information.

First, you need to install Ruby and Rubygems. Though that is not a difficult task, it is beyond the scope of this README. A search engine of your choice will help discover how to do this. Once you have done that:

$ gem install free_zipcode_data

Determine the 2-letter country codes for the countries you want to use atGeoNames, or don't specify a country to get all zipcodes for all available countries...

Options:  -w, --work-dir=<s>             REQUIRED: Specify your work/build directory, where the SQLite and .csv files will be built  -f, --country=<s>              Specify the country codefor processing, or all countriesif not specified  -g, --generate-files           Generate CSV files: [counties.csv, states.csv, countries.csv, zipcodes.csv]  -o, --country-tablename=<s>    Specify the namefor the`countries` table (default: countries)  -s, --state-tablename=<s>      Specify the namefor the`states` table (default: states)  -u, --county-tablename=<s>     Specify the namefor the`counties` table (default: counties)  -z, --zipcode-tablename=<s>    Specify the namefor the`zipcodes` table (default: zipcodes)  -c, --clobber                  Overwrite existing files  -d, --dry-run                  Do not actually move or copy files  -v, --verbose                  Be verbose with output  -h, --help                     Show this message

Download and process all US zipcodes:

$ free_zipcode_data --work-dir /tmp/work_dir --country US --generate-files

Download and process zipcodes for all available countries:

$ free_zipcode_data --work-dir /tmp/work_dir --generate-files

The rake tasks cascade, from the bottom up. So if you runrake data:populate_db, it will automatically callrake data:build if the .csv files are missing, which will callrake data:download if the .zip files are missing.

The executable will generate an SQLite3 database in the specified directory--work-dir but it will not generate the.csv files by default. Specify--generate-files if you want those as well.

By default the tables will be named as follows. To override the table names see the command line options above.

createtablecountries (  idintegernot nullprimary key,  alpha2varchar(2)not null,  alpha3varchar(3),  isovarchar(3),  namevarchar(255)not null)createtablestates (  idintegernot nullprimary key,  country_idintegernot null,  abbrvarchar(2)not null,  namevarchar(255))createtablecounties (  idintegernot nullprimary key,  state_idinteger,  abbrvarchar(255),  namevarchar(255),  county_seatvarchar(255))createtablezipcodes (  idintegernot nullprimary key,  codevarchar(10)not null,  state_idinteger,  cityvarchar(255),  area_codevarchar(3),  lat float,  lon float,  accuracyvarchar(8))

Bothlat andlon, geocodes, are populated for each zipcode record.

The zipcode data is licensed under aCreative Commons Attribution 3.0 Unported License, carried forward fromGeoNames.

SeeCHANGELOG for more history and errata.