Sign inSign up

kevintboyle/libpostal-api

By kevintboyle

•Updated 8 months ago

This supports a REST interface to the LibPostal API

Image
Languages & frameworks
0

355

kevintboyle/libpostal-api repository overview

⁠libpostal REST API

A fault-tolerant REST interface for libpostal⁠ using Python, FastAPI, and pypostal.

⁠Features

  • Address Parsing: Parse addresses into labeled components (house_number, road, city, state, postcode, country, etc.)
  • Address Expansion: Normalize addresses with expanded abbreviations and standardized formatting
  • Bulk Operations: Process multiple addresses in a single request
  • Fault Tolerance: Graceful error handling with detailed error reporting
  • Health Checks: Monitor service and libpostal module availability

⁠Endpoints

MethodEndpointDescription
GET/API information
GET/healthHealth check
POST/parseParse single address
GET/parseParse single address (query params)
POST/parse_bulkParse multiple addresses
POST/expandExpand single address
GET/expandExpand single address (query params)
POST/expand_bulkExpand multiple addresses

⁠Installation

⁠Using Docker (Recommended)
docker build -t libpostal-api .
docker run -p 8000:8000 libpostal-api
⁠Manual Installation

Requires libpostal to be installed on the system first. See libpostal installation⁠.

pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000

⁠Usage Examples

⁠Parse Single Address
# POST
curl -X POST http://localhost:8000/parse \
  -H "Content-Type: application/json" \
  -d '{"address": "123 Main St, New York, NY 10001"}'

# GET
curl "http://localhost:8000/parse?address=123%20Main%20St%2C%20New%20York%2C%20NY%2010001"

Response:

{
  "input": "123 Main St, New York, NY 10001",
  "components": [
    {"label": "house_number", "value": "123"},
    {"label": "road", "value": "main st"},
    {"label": "city", "value": "new york"},
    {"label": "state", "value": "ny"},
    {"label": "postcode", "value": "10001"}
  ]
}
⁠Parse Bulk Addresses
curl -X POST http://localhost:8000/parse_bulk \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "123 Main St, New York, NY 10001",
      "456 Oak Ave, Los Angeles, CA 90001",
      "789 Pine Rd, Chicago, IL 60601"
    ]
  }'

Response:

{
  "results": [
    {
      "input": "123 Main St, New York, NY 10001",
      "components": [...]
    },
    {
      "input": "456 Oak Ave, Los Angeles, CA 90001",
      "components": [...]
    },
    {
      "input": "789 Pine Rd, Chicago, IL 60601",
      "components": [...]
    }
  ],
  "total": 3,
  "errors": []
}
⁠Expand Address
curl -X POST http://localhost:8000/expand \
  -H "Content-Type: application/json" \
  -d '{"address": "123 Main St Apt 4"}'

Response:

{
  "input": "123 Main St Apt 4",
  "expansions": [
    "123 main street apartment 4",
    "123 main street apt 4"
  ]
}
⁠Expand Bulk Addresses
curl -X POST http://localhost:8000/expand_bulk \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "123 Main St",
      "456 Oak Ave"
    ]
  }'
⁠Health Check
curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "libpostal_parser": true,
  "libpostal_expand": true
}

⁠API Documentation

Interactive API documentation is available at:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

⁠Error Handling

The API returns appropriate HTTP status codes:

  • 200: Success
  • 400: Bad request (e.g., empty address)
  • 500: Internal server error
  • 503: Service unavailable (libpostal not initialized)

Bulk endpoints collect errors per-address and return them in the errors array while still processing valid addresses.

⁠Configuration

Environment variables:

  • HOST: Server host (default: 0.0.0.0)
  • PORT: Server port (default: 8000)
  • LOG_LEVEL: Logging level (default: info)

Tag summary

Content type

Image

Digest

sha256:dc7e924dd…

Size

1 GB

Last updated

8 months ago

docker pull kevintboyle/libpostal-api