Skip to content
Java/JNI bindings to libpostal for for fast international street address parsing/normalization
Branch: master
Clone or download
albarrentine Merge pull request #26 from openvenues/jaewoongchoi1-patch-1
Reverting Travis images to Precise, adding section on pkg-config
Latest commit 60a8b6f Nov 9, 2017
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
gradle/wrapper [fix] Adding gradle-wrapper.jar, was in .gitignore Feb 19, 2016
m4 [fix] newlines Mar 29, 2017
src [api][build][docs] upgrading Java binding to use libpostal 1.0 Apr 1, 2017
.gitignore Initial commit Feb 19, 2016
.travis.yml [fix] fixing the build for OpenJDK7 in travis-ci/travis-ci#5227 Oct 27, 2017
LICENSE
Makefile.am [build] Adding ACLOCAL_AMFLAGS to Makefile.am Feb 19, 2016
README.md
bootstrap.sh
build.gradle
build.sh [build] Adding autotools portion of the build, plus a Shell script to… Feb 19, 2016
configure.ac
gradlew
gradlew.bat

README.md

jpostal

Build Status

These are the Java/JNI bindings to libpostal, a fast, multilingual NLP library (written in C) for parsing/normalizing physical addresses around the world.

Usage

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

import com.mapzen.jpostal.AddressExpander;

// Singleton, libpostal setup is done in the constructor
AddressExpander e = AddressExpander.getInstance();
String[] expansions = e.expandAddress("Quatre vingt douze Ave des Champs-Élysées");

To parse addresses into components:

import com.mapzen.jpostal.AddressParser;

// Singleton, parser setup is done in the constructor
AddressParser p = AddressParser.getInstance();
ParsedComponent[] components = p.parseAddress("The Book Club 100-106 Leonard St, Shoreditch, London, Greater London, EC2A 4RH, United Kingdom");

for (ParsedComponent c : components) {
    System.out.printf("%s: %s\n", c.getLabel(), c.getValue());
}

To use a libpostal installation with a datadir known at setup-time:

import com.mapzen.jpostal.AddressParser;
import com.mapzen.jpostal.AddressExpander;

AddressExpander e = AddressExpander.getInstanceDataDir("/some/path");
AddressParser p = AddressParser.getInstanceDataDir("/some/path");

Building libpostal

Before building the Java 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

Note: libpostal >= v0.3.3 is required to use this binding.

Make sure pkg-config can find libpostal

Some users have reported issues with the jpostal build related to pkg-config.

For jpostal to build, make sure this command runs without any errors:

pkg-config --cflags --libs libpostal

If you get a message like No package 'libpostal' found, try the following:

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

Try the pkg-config --cflags --libs libpostal command again. If it still can't find libpostal, return to the libpostal checkout directory and try:

export PKG_CONFIG_PATH=$(pwd)

Building jpostal

Only one command is needed:

./gradlew assemble

This will implicitly run build.sh which automatically runs the Autotools build for the JNI/C portion of the library and installs the resulting shared libraries in the expected location for java.library.path

Usage in a Java project

The JNI portion of jpostal builds shared object files (.so on Linux, .jniLib on Mac) that need to be on java.library.path. After running gradle assemble the .so/.jniLib files can be found under src/main/jniLibs in the checkout dir. For running the tests, we set java.library.path explicitly here.

For gradle users, there's a plugin called gradle-natives that may be helpful: https://github.com/cjstehno/coffeaelectronica/wiki/Going-Native-with-Gradle

Compatibility

Building jpostal is known to work on Linux and Mac OSX. The Travis CI build tests Oracle JDK 7/8 and OpenJDK 7.

Tests

To run the tests:

./gradlew check

License

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

You can’t perform that action at this time.