free_zipcode_data 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dfe97e5c2963d4c40da211303f3f3c31ad9b29253c70c3d3f2ff303d92d51c9a
+  data.tar.gz: 38744e59531dcaf6dbc710a8343c7b97f72b3e35f4c48d73f499eacdfee6ea2b
+SHA512:
+  metadata.gz: a65a8d0bfcece72ef8e8a93bb654f0c50436de7d3639f1fefca845f8e3a1082aba1ae0597be269967715eb2ebcc01090a5f714cb7ec10b141c9c041bdde9349a
+  data.tar.gz: 0611b47e763d063e84029de8022fda6f2ffd2bceeb6f2ff8a6f04499a5d8814a700bd8b6b14520a627338947ff5aa171b20703d59a9afc7ab5d673b7949d2588

data/.gitignore

@@ -0,0 +1,7 @@
+/.bundle
+/free_zipcode_data.sqlite3
+/data
+/build
+/stubs
+/vendor/bundle/
+/pkg

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,88 @@
+AllCops:
+  TargetRubyVersion: 2.3
+
+  # Include gemspec and Rakefile
+  Include:
+    - '**/*.gemspec'
+    - '**/*.podspec'
+    - '**/*.jbuilder'
+    - '**/*.rake'
+    - '**/Gemfile'
+    - '**/Rakefile'
+    - '**/Capfile'
+    - '**/Guardfile'
+    - '**/Podfile'
+    - '**/Thorfile'
+    - '**/Vagrantfile'
+  Exclude:
+    - 'vendor/**/*'
+    - 'stubs/**/*'
+    - 'spec/support/shared_contexts/*'
+
+# Checks formatting of special comments
+CommentAnnotation:
+  Keywords:
+    - TODO
+    - FIXME
+    - OPTIMIZE
+    - HACK
+    - REVIEW
+
+########################################
+# Style Cops
+
+Style/ClassVars:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FileName:
+  Enabled: false
+
+Style/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+
+Style/RegexpLiteral:
+  Enabled: false
+
+Style/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Style/RaiseArgs:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/PerlBackrefs:
+  Enabled: false
+
+########################################
+# Lint Cops
+
+Lint/Eval:
+  Enabled: false
+
+Lint/HandleExceptions:
+  Enabled: false
+
+########################################
+# Metrics Cops
+
+Metrics/LineLength:
+  Max: 110
+
+Metrics/MethodLength:
+  CountComments: false # count full line comments?
+  Max: 30
+
+Metrics/ClassLength:
+  Max: 120
+
+Metrics/AbcSize:
+  Enabled: false
+
+# rubocop:disable Metrics/AbcSize
+# rubocop:disable Metrics/MethodLength
+# rubocop:disable Metrics/BlockLength

data/CHANGELOG

@@ -0,0 +1,42 @@
+*1.0.1* (April 23, 2018)
+
+* Made it a gem with a command line executable bin/free_zipcode_data
+* Use Kiba for ETL
+* Support user switches for various options including custom table names and generating .csv files
+* Use in-memory SQLite database to create the tables, then save it as a file on disk
+* Separate concerns for each table
+* Add a progressbar with ETA
+* Fix a bug when looking up state_id
+* Add a ‘name’ index on states table
+* Add a switch to generate individual .csv files [--generate-files]
+* Add a switch to overwrite [--clobber] downloaded and generated .csv files
+
+### Previous History
+
+### 10/28/2017:
+
+* Removed old .csv files
+* Add template files (CODE_OF_CONDUCT.md, CONTRIBUTING.md, ISSUE_TEMPLATE.md, LICENSE.md, PULL_REQUEST_TEMPLATE.md)
+* Use new data provider - [GeoNames](http://www.geonames.org)
+* Test USA
+* Started to test `allCountries.zip` but it takes too long. Let me know if there are any bugs.
+* Create `country_lookup_table.yml` for country code lookups
+
+### 05/04/2011:
+
+* Removed un-assigned zipcodes, which were not valid for today
+* Added a Rakefile and some rake tasks to facilitate building a SQLite relational database for the three tables (states, counties, zipcodes)
+* Zipcodes without an associated county == 0
+* Counties without a zipcode == 1 (PISCATAGUIS, Maine)
+
+### 01/24/2011:
+
+* 670 orphaned zipcodes without an associated county
+* 1 county without any zipcodes (PISCATAGUIS, Maine)
+
+### 01/13/2011:
+
+At last check there were ...
+
+* 897 orphaned zipcodes without an associated county
+* 1 county without any zipcodes (PISCATAGUIS, Maine)

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Free Zipcode Data Code of Conduct
+
+The Free Zipcode Data project strongly values contributors from anywhere, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, ethnicity, age, religion, or nationality. As a result, the Free Zipcode Data team has agreed to and enforces this code of conduct in order to provide a harassment-free experience for everyone who participates in the development of Free Zipcode Data.
+
+### Summary
+
+Just Be Nice!!!
+
+Harassment in code and discussion or violation of physical boundaries is completely unacceptable anywhere in the Free Zipcode Data codebase, issue trackers, chat rooms, mailing lists, meetups, and any other events. Violators will be warned and then blocked or banned by the core team at or before the 3rd violation.
+
+### In Detail
+
+Harassment includes offensive verbal comments related to level of experience, gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, ethnicity, age, religion, nationality, the use of sexualized language or imagery, deliberate intimidation, stalking, sustained disruption, and unwelcome sexual attention.
+
+Individuals asked to stop any harassing behavior are expected to comply immediately.
+
+Maintainers, including the core team, are also subject to the anti-harassment policy.
+
+If anyone engages in abusive, harassing, or otherwise unacceptable behavior, including maintainers, we may take appropriate action, up to and including warning the offender, deletion of comments, removal from the project’s codebase and communication systems, and escalation to GitHub support.
+
+If you are being harassed, notice that someone else is being harassed, or have any other concerns, please contact [Chris Blackburn](mailto:87a1779b@opayq.com).
+
+We expect everyone to follow these rules anywhere in the Free Zipcode Data codebase, issue trackers, IRC channel, group chat, and mailing lists.
+
+This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+
+Finally, don't forget that it is human to make mistakes! We all do. Let’s work together to help each other, resolve issues, and learn from the mistakes that we will all inevitably make from time to time.
+
+### Thanks
+
+Thanks to the [JSConf Code of Conduct](http://jsconf.com/codeofconduct.html) and [Fedora Code of Conduct](http://fedoraproject.org/code-of-conduct) for inspiration and ideas.
+
+### License
+
+<p class="license" xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
+  To the extent possible under law, <a rel="dct:publisher" href="https://github.com/midwire/free_zipcode_data">The Free Zipcode Data Team</a> has waived all copyright and related or neighboring rights to the <span property="dct:title">Free Zipcode Data Code of Conduct</span>. This work is published from the <span property="vcard:Country" datatype="dct:ISO3166" content="US" about="https://github.com/midwire/free_zipcode_data">United States.</span>
+  <br>
+  <br>
+  <a rel="license" href="http://creativecommons.org/publicdomain/zero/1.0/">
+    <img src="http://i.creativecommons.org/p/zero/1.0/88x31.png" style="border-style: none;" alt="CC0">
+  </a>
+</p>

data/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+## How to contribute to free_zipcode_data
+
+#### **Did you find a bug?**
+
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/midwire/free_zipcode_data/issues).
+
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/midwire/free_zipcode_data/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
+
+#### **Did you write a patch that fixes a bug?**
+
+* Open a new GitHub pull request with the patch.
+
+* Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
+
+* Before submitting, please read run [Rubocop](http://batsov.com/rubocop/) on your code. If your PR fails our Rubocop convensions defined in `.rubocop.yml`, it will likely be rejected on those grounds.
+
+* Ensure that you write RSpec tests that cover any new or modified code. PR's without spec coverage will likely be rejected.
+
+#### **Did you fix whitespace, format code, or make a purely cosmetic patch?**
+
+Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability of Free Zipcode Data will generally not be accepted.
+
+Thanks for any contributions!
+
+--Midwire

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,82 @@
+PATH
+  remote: .
+  specs:
+    free_zipcode_data (1.0.1)
+      colored (~> 1.2)
+      kiba (~> 2.0)
+      ruby-progressbar (~> 1.9)
+      rubyzip (~> 1.2)
+      sqlite3 (~> 1.3)
+      trollop (~> 2.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.0)
+    coderay (1.1.2)
+    colored (1.2)
+    diff-lcs (1.3)
+    docile (1.3.0)
+    json (2.1.0)
+    kiba (2.0.0)
+    method_source (0.8.2)
+    parallel (1.12.1)
+    parser (2.5.1.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.1)
+    pry (0.10.4)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    pry-nav (0.2.4)
+      pry (>= 0.9.10, < 0.11.0)
+    rainbow (3.0.0)
+    rake (12.2.1)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.1)
+    rubocop (0.55.0)
+      parallel (~> 1.10)
+      parser (>= 2.5)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-prof (0.17.0)
+    ruby-progressbar (1.9.0)
+    rubyzip (1.2.1)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    slop (3.6.0)
+    sqlite3 (1.3.13)
+    trollop (2.1.2)
+    unicode-display_width (1.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  free_zipcode_data!
+  pry-nav (~> 0.2)
+  rake (~> 12.0)
+  rspec (~> 3.7)
+  rubocop (~> 0.55)
+  ruby-prof (~> 0.17)
+  simplecov (~> 0.16)
+
+BUNDLED WITH
+   1.16.1

data/ISSUE_TEMPLATE.md

@@ -0,0 +1,9 @@
+### Expected Behavior
+
+### Actual Behavior
+
+### Steps to reproduce the problem
+
+---
+* Current Version:
+* Operating System:

data/LICENSE.md

@@ -0,0 +1,21 @@
+## The MIT License (MIT)
+
+##### Copyright (c) 2017 Midwire Technologies, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+**_THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE._**

data/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,5 @@
+- [ ] I wrote specs to cover new or modified code in this PR
+- [ ] I ran `rake spec` locally and ALL specs pass
+
+Related Issue: # <please-add-issue-number-here>
+Description: <please-add-a-comprehensive-description-of-fix/feature>

data/README.md

@@ -0,0 +1,115 @@
+# Free Zipcode Data
+
+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.
+
+## History
+
+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 using [GeoNames](http://www.geonames.org) data, which is licensed under Creative Commons. We are grateful to [GeoNames](http://www.geonames.org) for sharing, and urge you to [visit their site](http://www.geonames.org) 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.
+
+## What's Included
+
+* 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 check [GeoNames](http://download.geonames.org/export/zip/) 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 GeoNames [readme.txt](http://download.geonames.org/export/zip/readme.txt) file for more information.
+
+## Usage
+
+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:
+
+```bash
+$ gem install free_zipcode_data
+```
+
+Determine the 2-letter country codes for the countries you want to use at [GeoNames](http://download.geonames.org/export/zip/), or don't specify a country to get all zipcodes for all available countries...
+
+### Command Line Options
+
+```bash
+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 code for processing, or all countries if not specified
+  -g, --generate-files           Generate CSV files: [counties.csv, states.csv, countries.csv, zipcodes.csv]
+  -o, --country-tablename=<s>    Specify the name for the `countries` table (default: countries)
+  -s, --state-tablename=<s>      Specify the name for the `states` table (default: states)
+  -u, --county-tablename=<s>     Specify the name for the `counties` table (default: counties)
+  -z, --zipcode-tablename=<s>    Specify the name for 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
+```
+
+### Examples
+
+**Download and process all US zipcodes**:
+
+```bash
+$ free_zipcode_data --work-dir /tmp/work_dir --country US --generate-files
+```
+
+**Download and process zipcodes for all available countries**:
+
+```bash
+$ free_zipcode_data --work-dir /tmp/work_dir --generate-files
+```
+
+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.
+
+## SQLite3 Database
+
+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.
+
+```sql
+create table countries (
+  id integer not null primary key,
+  alpha2 varchar(2) not null,
+  alpha3 varchar(3),
+  iso varchar(3),
+  name varchar(255) not null
+)
+
+create table states (
+  id integer not null primary key,
+  country_id integer not null,
+  abbr varchar(2) not null,
+  name varchar(255)
+)
+
+create table counties (
+  id integer not null primary key,
+  state_id integer,
+  abbr varchar(255),
+  name varchar(255),
+  county_seat varchar(255)
+)
+
+create table zipcodes (
+  id integer not null primary key,
+  code varchar(10) not null,
+  state_id integer,
+  city varchar(255),
+  area_code varchar(3),
+  lat float,
+  lon float,
+  accuracy varchar(8)
+)
+```
+
+Both `lat` and `lon`, geocodes, are populated for each zipcode record.
+
+## Data License
+
+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 />
+<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>
+
+See [CHANGELOG](CHANGELOG) for more history and errata.