Ruby bindings to libpostal for fast international address parsing/normalization
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Build Status Gem version

These are the Ruby bindings to libpostal for fast street address parsing and normalization.


To expand address strings into normalized forms suitable for geocoder queries:

require 'ruby_postal/expand'
Postal::Expand.expand_address('Quatre-vingt-douze Ave des Ave des Champs-Élysées')

To parse addresses into components:

require 'ruby_postal/parser'
Postal::Parser.parse_address('781 Franklin Ave Crown Heights Brooklyn NY 11216 USA')


Before using the Ruby bindings, you must install the libpostal C library. Make sure you have the following prerequisites:

On Ubuntu/Debian

sudo apt-get install curl autoconf automake libtool pkg-config


sudo yum install curl autoconf automake libtool pkgconfig

On Mac OSX

sudo brew install curl autoconf automake libtool pkg-config

Installing libpostal

git clone
cd libpostal
./configure --datadir=[...some dir with a few GB of space...]
sudo make install

# On Linux it's probably a good idea to run
sudo ldconfig


Add this line to your application's Gemfile:

gem 'ruby_postal'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ruby_postal


bundle install
bundle exec rake

If you installed libpostal to a non-standard location, use:

bundle exec rake --with-libpostal-dir=/libpostal/prefix

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


rake test


Bug reports and pull requests are welcome on GitHub at


The gem is available as open source under the terms of the MIT License.