Postal web server
This Docker image provides a web server that grants access to the libpostal library, enabling the parsing and normalization of street addresses globally.
Ready docker image
docker pull ghcr.io/le0pard/postal_server:latest
Usage
To expand address strings into normalized forms suitable for geocoder queries, use the /expand
endpoint with the address
query parameter. For example, to expand the address "Quatre-vingt-douze Ave des Ave des Champs-Élysées":
GET /expand?address=Quatre-vingt-douze%20Ave%20des%20Ave%20des%20Champs-Élysées
[
"92 avenue des avenue des champs-elysees",
"92 avenue des avenue des champs elysees",
"92 avenue des avenue des champselysees"
]
This will provide the expanded and normalized addresses ready for geocoding queries.
To parse addresses into components, use the /parse
endpoint with the address
query parameter. For example, to parse the address "781 Franklin Ave Crown Heights Brooklyn NY 11216 USA":
GET /parse?address=781%20Franklin%20Ave%20Crown%20Heights%20Brooklyn%20NY%2011216%20USA
[
{
"label": "house_number",
"value": "781"
},
{
"label": "road",
"value": "franklin ave"
},
{
"label": "suburb",
"value": "crown heights"
},
{
"label": "city_district",
"value": "brooklyn"
},
{
"label": "state",
"value": "ny"
},
{
"label": "postcode",
"value": "11216"
},
{
"label": "country",
"value": "usa"
}
]
This will break down the address into its individual components.
Endpoint /health
can be use to check webserver healthcheck (like in k8s env):
$ curl http://localhost:8000/health
{"status":"ok"}
Auth for server
You can set up either basic authentication or bearer token authentication to protect your web server, while keeping the /health
endpoint public
Configuration
Configuration environment variables:
POSTAL_SERVER_HOST - server host (default: 0.0.0.0)
POSTAL_SERVER_PORT or PORT - server port (default: 8000)
POSTAL_SERVER_TRUSTED_PROXIES - trusted proxies IP addresses (separated by comma)
POSTAL_SERVER_LOG_FORMAT - log format, can be "json" or "text" (default: "text")
POSTAL_SERVER_LOG_LEVEL - log level (default: "info")
POSTAL_SERVER_BASIC_AUTH_USERNAME - basic auth username (required if basic auth password is set)
POSTAL_SERVER_BASIC_AUTH_PASSWORD - basic auth password (required if basic auth username is set)
POSTAL_SERVER_BEARER_AUTH_TOKEN - bearer auth token
Development
Local build:
docker build -t postal-server .