|
1 | 1 | # Free Zipcode Data |
2 | 2 |
|
3 | | -We got sick and tired of trying to find free zipcode data. So we pulled down all the census data we could find, parsed it and exported it into these .csv files. |
| 3 | +Zipcode data is free from the various governments around the world. Yet so many organizations, reputable or not, want to charge money for it. |
| 4 | + |
| 5 | +We originally pulled down all the US census data we could find, parsed it and exported it into .csv files. |
| 6 | + |
| 7 | +In 2017 we began using [GeoNames](http://www.geonames.org) data, which is licensed under Creative Commons: |
| 8 | + |
| 9 | +We thank [GeoNames](http://www.geonames.org) for sharing, and urge you to [visit their site](http://www.geonames.org) and support their work. |
| 10 | + |
| 11 | +## What's Included |
| 12 | + |
| 13 | +There are three rake tasks which automatically download the latest zipcode data from the country that you specify. Not all countries are accounted for. Please check [GeoNames](http://download.geonames.org/export/zip/) to see a list of supported country zip files. |
| 14 | + |
| 15 | +Each zipcode is correlated with estimated or zip-centroid, latitude and longitude coordinates. Where applicable, county/province, state and community are also correlated. |
| 16 | + |
| 17 | +See the GeoNames [readme.txt](http://download.geonames.org/export/zip/readme.txt) file for more information. |
| 18 | + |
| 19 | +## Usage |
| 20 | + |
| 21 | +```bash |
| 22 | +$ git clone https://github.com/midwire/free_zipcode_data |
| 23 | +$ cd free_zipcode_data |
| 24 | +``` |
| 25 | + |
| 26 | +Determine the countries you want to use at [GeoNames](http://download.geonames.org/export/zip/), or just use the rake task without any `country` argument to get zipcode data for all countries... |
| 27 | +```bash |
| 28 | +# download will pull down the zipcodes for the specified country |
| 29 | +$ rake data:download[country] |
| 30 | +# rake data:download[US] - For US-only zipcodes |
| 31 | +# rake data:download[GB_full.csv] - All UK data zipcodes: |
| 32 | +# rake data:download - ALL zipcodes |
| 33 | +``` |
| 34 | + |
| 35 | +```bash |
| 36 | +# build the .csv files |
| 37 | +$ rake data:build[country] |
| 38 | +# rake data:build - ALL countries |
| 39 | +``` |
| 40 | + |
| 41 | +```bash |
| 42 | +# populate_db will automatically download the zips and build the .csv files |
| 43 | +$ rake data:populate_db[country] |
| 44 | +# rake data:populate_db - ALL countries - WARNING: takes a long time |
| 45 | +``` |
| 46 | + |
| 47 | +The rake tasks cascade, from the bottom up. So if you run `rake data:populate_db`, it will automatically call `rake data:build` if the .csv files are missing, which will call `rake data:download` if the .zip files are missing. |
| 48 | + |
| 49 | +## SQLite3 Database |
| 50 | + |
| 51 | +The rake task `rake data:populate_db[country]` will create an SQLite3 database with the following tables, and populate each one: |
| 52 | + |
| 53 | +```sql |
| 54 | +create table countries ( |
| 55 | + id integer not null primary key, |
| 56 | + alpha2 varchar(2) not null, |
| 57 | + alpha3 varchar(3), |
| 58 | + iso varchar(3), |
| 59 | + name varchar(255) not null |
| 60 | +) |
| 61 | + |
| 62 | +create table states ( |
| 63 | + id integer not null primary key, |
| 64 | + country_id integer not null, |
| 65 | + abbr varchar(2) not null, |
| 66 | + name varchar(255) |
| 67 | +) |
| 68 | + |
| 69 | +create table counties ( |
| 70 | + id integer not null primary key, |
| 71 | + state_id integer, |
| 72 | + abbr varchar(255), |
| 73 | + name varchar(255), |
| 74 | + county_seat varchar(255) |
| 75 | +) |
| 76 | + |
| 77 | +create table zipcodes ( |
| 78 | + id integer not null primary key, |
| 79 | + code varchar(10) not null, |
| 80 | + state_id integer, |
| 81 | + county_id integer, |
| 82 | + city varchar(255), |
| 83 | + area_code varchar(3), |
| 84 | + lat float, |
| 85 | + lon float, |
| 86 | + accuracy varchar(8) |
| 87 | +) |
| 88 | +``` |
4 | 89 |
|
5 | | -## CSV Data |
6 | | - |
7 | | -### `all_us_counties.csv` |
8 | | - name, state, county_seat |
9 | | - |
10 | | -### `all_us_states.csv` |
11 | | - abbr, name |
12 | | - |
13 | | -### `all_us_zipcodes.csv` |
14 | | - code, city, state, county, area_code, lat, lon |
15 | | - |
16 | 90 | Both `lat` and `lon`, geocodes, are populated for each zipcode record. |
17 | 91 |
|
18 | | -## SQL Data |
19 | | - |
20 | | -### `counties_states_zipcodes.sql` |
21 | | - |
22 | | -This is a MySQL ready dump of the three tables `counties`, `states` and `zipcodes`. Both structure and data, along with complete and extended INSERTs are included in the dump. |
23 | | - |
24 | | -## Updating |
| 92 | +## Data License |
25 | 93 |
|
26 | | -Please add any missing data, or correct mistakes, and send us a pull request. |
| 94 | +The zipcode data is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>, carried forward from [GeoNames](http://www.geonames.org).<br /> |
| 95 | +<a rel="license" href="http://creativecommons.org/licenses/by/3.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/3.0/88x31.png" /></a> |
27 | 96 |
|
28 | 97 | ## Errata |
29 | 98 |
|
|
0 commit comments