dripostal 0.1.1
A tiny API client for the Pelias Libpostal REST service.
License: MIT
Requires Python: >=3.6.2,<4.0

<p style="text-align: center; padding-bottom: 1rem;">
    <a href="https://dribia.github.io/dripostal">
        <img 
            src="https://dribia.github.io/dripostal/img/logo_dribia_blau_cropped.png" 
            alt="dripostal" 
            style="display: block; margin-left: auto; margin-right: auto; width: 40%;"
        >
    </a>
</p>

<p style="text-align: center">
    <a href="https://github.com/dribia/dripostal/actions?query=workflow%3ATest" target="_blank">
        <img src="https://github.com/dribia/dripostal/workflows/Test/badge.svg" alt="Test">
    </a>
    <a href="https://github.com/dribia/dripostal/actions?query=workflow%3APublish" target="_blank">
        <img src="https://github.com/dribia/dripostal/workflows/Publish/badge.svg" alt="Publish">
    </a>
    <a href="https://codecov.io/gh/dribia/dripostal" target="_blank">
        <img src="https://img.shields.io/codecov/c/github/dribia/dripostal?color=%2334D058" alt="Coverage">
    </a>
    <a href="https://pypi.org/project/dripostal" target="_blank">
        <img src="https://img.shields.io/pypi/v/dripostal?color=%2334D058&label=pypi%20package" alt="Package version">
    </a>
</p>

<p style="text-align: center;">
    <em>A tiny API client for the Pelias Libpostal REST service.</em>
</p>

---

**Documentation**: <a href="https://dribia.github.io/dripostal" target="_blank">https://dribia.github.io/dripostal</a>

**Source Code**: <a href="https://github.com/dribia/dripostal" target="_blank">
https://github.com/dribia/dripostal</a>

---

[**Libpostal**](https://github.com/openvenues/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**](https://github.com/pelias/libpostal-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`**](https://github.com/openvenues/libpostal#examples-of-parsing) and [**`expand`**](https://github.com/openvenues/libpostal#examples-of-normalization) methods.
* Return results as [**Pydantic**](https://pydantic-docs.helpmanual.io/) models.
* Provides a mirror [**async client**](https://docs.python.org/3/library/asyncio.html) enabling asynchronous queries to the Libpostal REST service.

## Example

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

```shell
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:

```python
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, 
    ...
)
"""
```