Adds zipcode / postal code validation support to Rails (ActiveModel/ActiveRecord), considering postal code formats for mostly every country.

Monthly Downloads: 57,418
Programming language: Ruby
License: MIT License
Latest version: v0.4.0

ValidatesZipcode alternatives and similar gems

Based on the "Validation" category.
Alternatively, view ValidatesZipcode alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of ValidatesZipcode or a related project?

Add another 'Validation' Gem


ValidatesZipcode Build Status Code Climate Gem Version security

Adds zipcode / postal code validation support to Rails (ActiveModel), considering postal code formats for mostly every country.

ValidatesZipcode currently support 233 country codes. Regex data taken from several sources, being the main source the CLDR database (release 27, around 159). Any other country's postal code will validate without errors.

ValidatesZipcode supports Rails >= 4.2 and Ruby >= 2.4. This gem could work in Rails 3.2 and Ruby 1.9.3 as well, yet unsupported; try v0.2 series if having trouble with later versions. Truffleruby is also tested, but no reports of working in production apps for now.


Add this line to your application's Gemfile:

gem 'validates_zipcode'

And then execute:

$ bundle

Or install it yourself as:

$ gem install validates_zipcode


With ActiveModel::Validations

validates_zipcode :zipcode

validates :zipcode, zipcode: true

ValidatesZipcode expects the model to have an attribute called country_alpha2 to contain the country code. You can provide your own country_code using :country_code option, or specify which attribute contains this information using :country_code_attribute option.

validates :zipcode, zipcode: { country_code: :es }

validates :zipcode, zipcode: { country_code_attribute: :my_country_code_column }
Error Messaging

If you need to localize the error message, just add this to your I18n locale file:

    invalid_zipcode: Your zipcode error message.

You can override this on a per-model basis by passing in a :message key with the validation:

validates :zipcode, zipcode: { message: 'Your per-model zipcode error message.' }

Without ActiveModel::Validations

ValidatesZipcode.valid?('93108', 'ES')
# => true


This gem can also be used for formatting zipcodes according to country specific rules.

ValidatesZipcode.format('Sw1A 2aA', 'UK')
# => 'SW1A 2AA'

If the zipcode is not valid an exception is raised.

ValidatesZipcode.format('Sw1A 2aA', 'FR')
# => raises ValidatesZipcode::InvalidZipcodeError

At the moment not every country is supported. See [lib/validates_zipcode/formatter.rb](lib/validates_zipcode/formatter.rb) to find all available countries.

Test data

In order to generate test data, we suggest using the regexp-examples gem This dependency will allow you to create examples as follows:

require "regexp-examples"


# => ["00000", "00001", "00002", "00003", ..., "44443", "44444"]


# => "27072"


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

Also, you should read and follow our Code of Conduct.


To see the generous people who have contributed code, take a look at the contributors list.



Copyright (c) 2014 David Gil Pérez, released under the MIT license

*Note that all licence references and agreements mentioned in the ValidatesZipcode README section above are relevant to that project's source code only.