Skip to content

dribia/dripostal

Repository files navigation

dripostal

Test Publish Coverage Package version

A tiny API client for the Pelias Libpostal REST service.


Documentation: https://dribia.github.io/dripostal

Source Code: https://github.com/dribia/dripostal


Libpostal is a widely known C library for parsing and normalizing street addresses around the world.

Despite having its own Python bindings, getting to install the library can be quite hard and time-consuming. A common workaround is then to use a dockerized service exposing Libpostal as a REST API, e.g. Pelias' Libpostal REST service.

Dripostal aims to provide a Python interface with such API, both in the synchronous and the asynchronous ways.

Key features

  • Query Libpostal's parse and expand methods.
  • Return results as Pydantic models.
  • Provides a mirror async client enabling asynchronous queries to the Libpostal REST service.

Example

In order to successfully run the following example, a Libpostal service should be running locally:

docker run -d -p 4400:4400 pelias/libpostal-service

!!!info The command above will be pulling the libpostal-service Docker image from Pelias and running a container that will serve the Libpostal REST service through its port 4400.

* With option `-p 4400:4400` we are mapping port 
  `4400` in the docker container to port `4400` in the docker host, i.e. your computer. 
  You could map it to another port of the host, e.g. the `8080`, changing `4400:4400` for `8080:4400`.
* With option `-d` we are running the docker container in _detached mode_, i.e. in the background. 

Now we should be able to run the following code:

from dripostal import DriPostal

dripostal = DriPostal(url="http://0.0.0.0:4400")

dripostal.parse("Planta 3 mòdul 303, Carrer de la Llacuna, 162, 08018 Barcelona")

"""
Address(
    house='mòdul 303', 
    house_number='162', 
    road='carrer de la llacuna', 
    level='planta 3', 
    postcode='08018', 
    city='barcelona', 
    country=None, 
    ...
)
"""