https://github.com/openvenues/ruby_postal
Ruby bindings to libpostal for fast international address parsing/normalization
https://github.com/openvenues/ruby_postal
Last synced: about 1 month ago
JSON representation
Ruby bindings to libpostal for fast international address parsing/normalization
- Host: GitHub
- URL: https://github.com/openvenues/ruby_postal
- Owner: openvenues
- License: mit
- Created: 2016-02-13T16:54:37.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2025-01-30T05:48:15.000Z (10 months ago)
- Last Synced: 2025-05-09T07:28:57.386Z (7 months ago)
- Language: C
- Size: 30.3 KB
- Stars: 141
- Watchers: 9
- Forks: 12
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
- Awesome-Geospatial - ruby_postal - Ruby bindings to libpostal for fast international address parsing/normalization. (Ruby)
- awesome-gis - ruby_postal - Ruby bindings to libpostal for fast international address parsing/normalization. (Geospatial Library / Ruby)
README
# ruby_postal
[](https://travis-ci.org/openvenues/ruby_postal) [](https://rubygems.org/gems/ruby_postal)
These are the Ruby bindings to [libpostal](https://github.com/openvenues/libpostal) for
fast street address parsing and normalization.
## Usage
To expand address strings into normalized forms suitable for geocoder queries:
```ruby
require 'ruby_postal/expand'
Postal::Expand.expand_address('Quatre-vingt-douze Ave des Ave des Champs-Élysées')
```
To parse addresses into components:
```ruby
require 'ruby_postal/parser'
Postal::Parser.parse_address('781 Franklin Ave Crown Heights Brooklyn NY 11216 USA')
```
## Prerequisites
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
```
**On CentOS/RHEL**
```
sudo yum install curl autoconf automake libtool pkgconfig
```
**On Mac OSX**
```
brew install curl autoconf automake libtool pkg-config
```
**Installing libpostal**
```
git clone https://github.com/openvenues/libpostal
cd libpostal
./bootstrap.sh
./configure --datadir=[...some dir with a few GB of space...]
make
sudo make install
# On Linux it's probably a good idea to run
sudo ldconfig
```
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'ruby_postal'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install ruby_postal
## Development
```
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 [rubygems.org](https://rubygems.org).
## Tests
```
rake test
```
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/openvenues/ruby_postal.
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).