mailwoman-client 6.0.0

Typed Python clients for Mailwoman's Photon / Nominatim / libpostal drop-in geocoding APIs and native /v1/* surface, generated from their OpenAPI specs.

mailwoman-client (Python)

Typed Python clients for Mailwoman's HTTP surfaces — generated from their published OpenAPI specs and bundled under one distributable:

Subpackage	Surface	Endpoints
mailwoman_client.photon	Photon drop-in	/api, /reverse
mailwoman_client.nominatim	Nominatim drop-in	/search, /reverse, /lookup, /status
mailwoman_client.libpostal	libpostal drop-in	/parse, /expand
mailwoman_client.mailwoman	Native surface	/v1/parse, /v1/geocode, /v1/batch, /v1/resolve, /v1/format

The four subpackages are generated verbatim by openapi-python-client (it runs its own ruff pass) and are overwritten on regen — do not hand-edit them. The only hand-written code is the thin ergonomics layer in mailwoman_client/__init__.py: PhotonClient / NominatimClient / LibpostalClient / MailwomanClient, each with a sensible default base_url. Regenerate with mailwoman clients generate (see the repo's docs/articles/api.mdx "Client libraries" section) — nothing here is hand-maintained.

Not yet published. This package is built and verified on every mailwoman clients generate run; publishing to PyPI happens from the gated CI job once the operator provisions a PyPI account (see the repo's RELEASING.md).

Install

pip install mailwoman-client

Requires Python 3.10+. The only runtime dependencies are httpx and attrs.

Usage

Forward-geocode against the hosted Photon trial endpoint (https://photon.sister.software, no local server needed):

from mailwoman_client import PhotonClient
from mailwoman_client.photon.api.geocoding import search

client = PhotonClient.hosted()  # or PhotonClient(base_url="http://127.0.0.1:2322") to self-host
result = search.sync(client=client, q="berlin", limit=3)

for feature in result.features:
    lon, lat = feature.geometry.coordinates
    props = feature.properties
    print(f"{props.name} ({props.type_}) — {lat:.4f}, {lon:.4f} [{props.country or '?'}]")

Self-hosting

PhotonClient(), NominatimClient(), LibpostalClient(), and MailwomanClient() default to their local serve ports (2322 / 8080 / 8081 / 3000), so they work out of the box against a self-hosted server (npx @mailwoman/photon serve, mailwoman serve, etc.). Only Photon has a hosted public trial endpoint. Point anywhere with base_url=.

Async

Every endpoint module also exposes an asyncio coroutine alongside sync:

result = await search.asyncio(client=client, q="berlin", limit=3)

License

AGPL-3.0-only OR LicenseRef-Commercial (see the repository).