address-validator

What it is

A lightweight Python API service designed to handle imperfect address inputs, such as those from voice-to-text systems. It parses raw strings, generates phonetic variants (e.g., swapping vowels, joining/splitting words), and concurrently queries the Photon geocoder to find valid USPS-standardized matches. It also integrates with OSRM to calculate driving distances, times, and route geometries between validated points without requiring API keys.

Features

• Resolves messy/voice-transcribed addresses to USPS-standardized format
• Generates ~40 phonetic variants for fuzzy matching against geocoders
• Calculates driving routes, distances, and times via OpenStreetMap/OSRM
• Supports multi-stop routing with mixed address and coordinate inputs
• No API keys required; uses public Photon and OSRM instances by default

Quickstart

pip install -r requirements.txt
python server.py

Architecture

flowchart TD
    Client[Client App] -->|POST /validate-address| API[FastAPI Server]
    Client -->|POST /route| API
    API -->|Generate Variants| Logic[Phonetic Variant Logic]
    Logic -->|Concurrent Requests| Photon[Photon Geocoder API]
    Photon -->|Coordinates & Address Data| API
    API -->|Send Coordinates| OSRM[OSRM Routing API]
    OSRM -->|Route Geometry & Duration| API
    API -->|JSON Response| Client

How it's built

Built with FastAPI for the HTTP interface and httpx for asynchronous external requests. Address validation relies on custom phonetic variant generation logic and the Jellyfish library for string similarity, querying the public Photon (Komoot) geocoder. Routing is handled by sending resolved coordinates to the public OSRM (Open Source Routing Machine) API. The application is stateless and configured via environment variables for service endpoints.

How it runs

sequenceDiagram
    participant C as Client
    participant S as FastAPI Server
    participant P as Photon Geocoder
    participant O as OSRM Router

    Note over C, S: Address Validation Flow
    C->>S: POST /validate-address {raw_address}
    S->>S: Parse address parts
    S->>S: Generate phonetic variants
    loop For each variant
        S->>P: GET /api?q={variant}
        P-->>S: Geocoding Result
    end
    S->>S: Select best match
    S-->>C: JSON {formatted_address, lat, lng}

    Note over C, S: Route Calculation Flow
    C->>S: POST /route {origin, destination}
    alt Input is Address
        S->>S: Validate/Resolve Address (as above)
    else Input is Lat/Lng
        S->>S: Use coordinates directly
    end
    S->>O: GET /route/v1/driving/{coords}
    O-->>S: GeoJSON Route & Duration
    S-->>C: JSON {distance, duration, geometry}

How to apply & reuse

Deploy as a microservice in dispatch or logistics applications where user input is unstructured. Use the /validate-address endpoint to clean customer data before storage, and the /route endpoint to estimate driver ETAs and distances for multi-stop deliveries. Ideal for voice-enabled interfaces where exact spelling cannot be guaranteed.

At a glance