https://github.com/wherobots/jpostal
Wherobots' Fork of jpostal
https://github.com/wherobots/jpostal
geocoding jpostal libpostal
Last synced: 5 months ago
JSON representation
Wherobots' Fork of jpostal
- Host: GitHub
- URL: https://github.com/wherobots/jpostal
- Owner: wherobots
- License: mit
- Created: 2025-05-27T18:29:08.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-10T00:40:21.000Z (11 months ago)
- Last Synced: 2025-07-10T04:33:16.442Z (11 months ago)
- Topics: geocoding, jpostal, libpostal
- Language: Java
- Homepage:
- Size: 253 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
jpostal
-------
These are the Java/JNI bindings to [libpostal](https://github.com/openvenues/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:
```java
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:
```java
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:
```java
import com.mapzen.jpostal.AddressParser;
import com.mapzen.jpostal.AddressExpander;
AddressExpander e = AddressExpander.getInstanceDataDir("/some/path");
AddressParser p = AddressParser.getInstanceDataDir("/some/path");
```
To configure the library to download the model data automatically when not present:
```java
import com.mapzen.jpostal.AddressParser;
import com.mapzen.jpostal.AddressExpander;
import com.mapzen.jpostal.Config;
Config config = Config.builder()
.downloadDataIfNeeded(true)
.senzing(true) // Set to true if you want to use Senzing model files
.dataDir("/some/path")
.build();
AddressExpander e = AddressExpander.getInstanceConfig(config);
AddressParser p = AddressParser.getInstanceConfig(config);
```
Installation from Maven Central
-------------------------------
TODO: Publish to Maven Central. For now you can download the jar
from [github](https://github.com/wherobots/jpostal/actions/runs/16152059927/artifacts/3489422226).
TODO: add maven link
We are publishing this version of jpostal to Maven Central. It contains the native code (libjpostal and libpostal). You
can use it in your Java projects with just a Maven dependency. We support:
* ARM and Intel architectures
* Linux and Mac OSX
## Build from Source
If you want to builde from source or have a specific version of libpostal, you can build the JNI bindings.
### 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**
```shell
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.
### Building jpostal
Only one command is needed:
```
./gradlew assemble
```
This will leverage gradle's NativeLibrarySpec support to 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 ```./libs/jpostal/shared``` in the build
dir. For running the tests, we set java.library.path
explicitly [here](https://github.com/Qualytics/jpostal/blob/master/build.gradle#L63).
Compatibility
-------------
- Building jpostal is known to work on Linux and Mac OSX (including Mac silicon).
- Requires JDK 16 or later. Make sure JAVA_HOME points to JDK 16+.
## Development
### Tests
To run the tests:
```
./gradlew check
```
License
-------
The package is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).