Postal Codes Search

Gem to obtain postal codes for US and CA only.

Installation

Add this line to your application's Gemfile:

gem 'postal-codes-search', '~> 1.1'

And then execute:

$ bundle

Or install it yourself as:

$ gem install postal-codes-search

Usage

You can search generally by any keyword like country, county, postal code, state and or city like this

PostalCodesSearch.find('Y1A')
# => [{"country"=>"CA", "postal_code"=>"Y1A", "city"=>"Whitehorse", "state"=>"Yukon", "county"=>nil}]
# This will return an array. If you put an incomplete postal code, it will return the most similar results

You can use more specific search depending on the attribute you want to use

By code

PostalCodesSearch.find_by(code: 'Y1A')
# => [{"country"=>"CA", "postal_code"=>"Y1A", "city"=>"Whitehorse", "state"=>"Yukon", "county"=>nil}]

By country

PostalCodesSearch.find_by(country: 'US').count
# => 41469

By county

PostalCodesSearch.find_by(county: 'Yukon-Koyukuk').first
# => {"country"=>"US", "postal_code"=>99558, "city"=>"Anvik", "state"=>"Alaska", "county"=>"Yukon-Koyukuk (CA)"}

By state

PostalCodesSearch.find_by(state: 'Alaska').count
# => 273

By city

PostalCodesSearch.find_by(city: 'Venetie')
# => [{"country"=>"US", "postal_code"=>99781, "city"=>"Venetie", "state"=>"Alaska", "county"=>"Yukon-Koyukuk (CA)"}]

Using rails, you can load all the values in a initializer

# config/initializers/postal_codes.rb
PostalCodesSearch.load unless Rails.env.development?

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request