Address Parsing API

The Address Parsing API provides multi-language address parsing, normalization, and extraction capabilities. It extracts structured address components along with personal information (names, phones, emails) from unstructured address strings.

Overview

The Address API enables you to:

Parse Addresses: Extract structured components from free-form address text
Extract Information: Pull names, phone numbers, emails, and company names
Format Addresses: Generate country-specific formatted addresses
Batch Processing: Parse multiple addresses in a single request
Expand Addresses: Get address variants and expansions
Multi-Country Support: Format for US, UK, EU, CN, AU, and more

Dependencies

The Address service relies on:

libpostal: Open-source address parsing library
pypostal-multiarch: Python bindings with multi-architecture support

Installation

If libpostal is not installed, the service will return unavailable status. See the service status endpoint for checking availability.

Endpoints

Service Status

GET /api/address/status

Check if the address parsing service is available and properly installed.

Response:

json

{
    "available": true,
    "libpostal_installed": true,
    "message": "Address service available"
}

Response Fields:

Field	Type	Description
available	boolean	Service is ready to use
libpostal_installed	boolean	libpostal C library installed
message	string	Human-readable status message

Parse Address

POST /api/address/parse

Parse a free-form address string into structured components.

Request Body:

json

{
    "address": "John Smith 123 Main Street Apt 4B New York NY 10001 United States john@example.com +1-555-123-4567",
    "language": "en"
}

Parameters:

Parameter	Type	Default	Description
address	string	✓	Address string to parse
language	string	"en"	Language code hint

Response:

json

{
    "success": true,
    "message": "Address parsed successfully",
    "data": {
        "raw_input": "John Smith 123 Main Street...",
        "full_name": "John Smith",
        "first_name": "John",
        "last_name": "Smith",
        "company": null,
        "tel": "+1-555-123-4567",
        "email": "john@example.com",
        "country": "United States",
        "country_code": "US",
        "state": "NY",
        "province": "NY",
        "city": "New York",
        "suburbs": null,
        "postcode": "10001",
        "road": "Main Street",
        "house_number": "123",
        "address1": "123 Main Street",
        "address2": "Apt 4B",
        "address3": null,
        "format_locale": "123 Main Street Apt 4B\nNew York NY 10001\nUnited States"
    }
}

Parsed Components:

Field	Description
raw_input	Original input string
full_name	Extracted full name
first_name	First name from full name
last_name	Last name from full name
company	Extracted company name
tel	Extracted phone number
email	Extracted email address
country	Country name
country_code	ISO 3166 country code
state/province	State or province
city	City name
suburbs	Suburb/district name
postcode	Postal/ZIP code
road	Street/road name
house_number	House/building number
address1	Address line 1
address2	Address line 2
address3	Address line 3
format_locale	Locale-formatted address string

Format Address

POST /api/address/format

Generate a properly formatted address string from components for a specific country.

Request Body:

json

{
    "raw_input": "Customer order #12345",
    "full_name": "Jane Doe",
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "ACME Corporation",
    "tel": "+44-20-7946-0958",
    "email": "jane@acme.co.uk",
    "country": "United Kingdom",
    "country_code": "GB",
    "state": "England",
    "city": "London",
    "postcode": "SW1A 1AA",
    "road": "Downing Street",
    "house_number": "10",
    "address1": "10 Downing Street",
    "address2": "Westminster",
    "address3": ""
}

Response:

json

{
    "success": true,
    "message": "Address formatted successfully",
    "data": {
        "raw_input": "Customer order #12345",
        "full_name": "Jane Doe",
        "company": "ACME Corporation",
        "country_code": "GB",
        "city": "London",
        "postcode": "SW1A 1AA",
        "road": "Downing Street",
        "house_number": "10",
        "format_locale": "Jane Doe\nACME Corporation\n10 Downing Street\nWestminster\nLondon SW1A 1AA\nUnited Kingdom"
    }
}

Country-Specific Formats:

Country	Format Example
US	House Street, City State ZIP
GB	House Street, City Postcode
NL	Street House, Postcode City
DE	Street House, Postcode City
FR	House Street, Postcode City
CN	Province City Street House
AU	House Street, Suburb City Postcode
BE	Street House, Postcode City, BE

Batch Parse

POST /api/address/batch

Parse multiple addresses in a single API call.

Request Body:

json

{
    "addresses": [
        "1600 Pennsylvania Ave NW Washington DC 20500",
        "10 Downing Street London SW1A 1AA UK",
        "Rue de la Loi 175 1040 Bruxelles BE",
        "北京市海淀区中关村大街1号 100871"
    ],
    "language": "en"
}

Parameters:

Parameter	Type	Description
addresses	string[]	Array of address strings
language	string	Language code

Response:

json

{
    "success": true,
    "message": "Successfully parsed 4 addresses",
    "results": [
        {
            "raw_input": "1600 Pennsylvania Ave NW Washington DC 20500",
            "house_number": "1600",
            "road": "Pennsylvania Ave NW",
            "city": "Washington",
            "state": "DC",
            "postcode": "20500",
            "country_code": "US",
            "format_locale": "1600 Pennsylvania Ave NW\nWashington DC 20500\nUnited States"
        },
        {
            "raw_input": "10 Downing Street London SW1A 1AA UK",
            "house_number": "10",
            "road": "Downing Street",
            "city": "London",
            "postcode": "SW1A 1AA",
            "country_code": "GB",
            "format_locale": "10 Downing Street\nLondon SW1A 1AA\nUnited Kingdom"
        }
    ]
}

Batch Processing

Batch processing is more efficient than multiple individual calls. Recommended batch size: 10-50 addresses per request.

Address Expansion

POST /api/address/expand

Generate address variants and expansions using libpostal's expansion capabilities.

Request Body:

json

{
    "address": "123 Main St New York NY",
    "language": "en"
}

Response:

json

{
    "success": true,
    "message": "Address expansion successful",
    "data": {
        "original": "123 Main St New York NY",
        "expanded": [
            "123 main street new york new york",
            "123 main saint new york new york",
            "123 main str new york new york"
        ]
    }
}

Expansions are useful for:

Address deduplication
Fuzzy matching
Standardization

Health Check

GET /api/address/health

Check service health status.

Response:

json

{
    "status": "healthy",
    "service": "address",
    "version": "1.0.0",
    "libpostal_installed": true
}

Error Handling

Service Unavailable

When libpostal is not installed:

json

{
    "success": false,
    "message": "pypostal not installed, please install pypostal-multiarch",
    "data": null
}

Parsing Errors

Individual address parsing failures in batch mode:

json

{
    "raw_input": "invalid address string",
    "success": false,
    "error": "Failed to parse address components"
}

Usage Examples

Python Example

python

import requests

API_KEY = "your-api-key"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Parse single address
response = requests.post(
    "https://api.alaikis.com/api/address/parse",
    json={
        "address": "John Smith 123 Main St New York NY 10001",
        "language": "en"
    },
    headers=headers
)

result = response.json()
if result["success"]:
    data = result["data"]
    print(f"Name: {data['full_name']}")
    print(f"City: {data['city']}")
    print(f"Postcode: {data['postcode']}")
    print(f"Phone: {data['tel']}")

Batch Processing Example

python

addresses = [
    "Customer 1: 1 Main St Boston MA 02101",
    "Customer 2: 2 Oak St Chicago IL 60601",
    "Customer 3: 3 Pine St Seattle WA 98101"
]

response = requests.post(
    "https://api.alaikis.com/api/address/batch",
    json={"addresses": addresses, "language": "en"},
    headers=headers
)

results = response.json()["results"]
for addr in results:
    print(f"{addr['city']}, {addr['postcode']}")

International Addresses

python

# Netherlands format
response = requests.post(
    "https://api.alaikis.com/api/address/parse",
    json={
        "address": "Pieter de la Court 175 1040 BC Amsterdam",
        "language": "nl"
    },
    headers=headers
)

# Chinese address
response = requests.post(
    "https://api.alaikis.com/api/address/parse",
    json={
        "address": "北京市海淀区中关村大街1号",
        "language": "zh"
    },
    headers=headers
)

Information Extraction

The parser automatically extracts:

Personal Names

Full name detection
First/last name splitting
Honorific recognition (Mr, Ms, Dr, etc.)

Phone Numbers

International format (+1, +44, +86)
National format with parentheses
Extensions (ext, x, extension)

Email Addresses

Standard email pattern matching
Company domain extraction

Company Names

Legal suffix detection (Inc, Ltd, GmbH, SARL)
Company pattern recognition

Performance

Operation	Typical Time
Single parse	10-50ms
Batch (10 addresses)	50-200ms
Batch (50 addresses)	200-800ms
Address expansion	5-20ms

Best Practices

1. Provide Complete Information

Include as much context as possible:

python

# Better
"John Doe, ACME Inc, 123 Main St, Apt 4B, New York NY 10001"

# Worse
"123 Main St NY"

2. Use Appropriate Language Hints

Set the language parameter for better parsing:

"en" for English addresses
"nl" for Dutch
"de" for German
"fr" for French
"zh" for Chinese

3. Batch Similar Addresses

Group addresses from the same country in batch requests for consistent formatting.

4. Validate Before Use

Always verify critical fields:

python

parsed = parse_address(raw_address)
if not parsed["postcode"]:
    # Fallback to manual entry
    pass

Installation Troubleshooting

If libpostal is not installed:

Linux (Debian/Ubuntu):

bash

apt-get install libpostal-dev
pip install pypostal-multiarch

macOS:

bash

brew install libpostal
pip install pypostal-multiarch

From Source:

bash

git clone https://github.com/openvenues/libpostal
cd libpostal
./bootstrap.sh
./configure --datadir=/usr/local/share/libpostal
make
make install

Always check service status before using the API:

python

response = requests.get("https://api.alaikis.com/api/address/status")
if not response.json()["available"]:
    print("Address service unavailable")

Address Parsing API ​

Overview ​

Dependencies ​

Endpoints ​

Service Status ​

GET /api/address/status ​

Parse Address ​

POST /api/address/parse ​

Format Address ​

POST /api/address/format ​

Batch Parse ​

POST /api/address/batch ​

Address Expansion ​

POST /api/address/expand ​

Health Check ​

GET /api/address/health ​

Error Handling ​

Service Unavailable ​

Parsing Errors ​

Usage Examples ​

Python Example ​

Batch Processing Example ​

International Addresses ​

Information Extraction ​

Personal Names ​

Phone Numbers ​

Email Addresses ​

Company Names ​

Performance ​

Best Practices ​

1. Provide Complete Information ​

2. Use Appropriate Language Hints ​

3. Batch Similar Addresses ​

4. Validate Before Use ​

Installation Troubleshooting ​

Address Parsing API

Overview

Dependencies

Endpoints

Service Status

GET /api/address/status

Parse Address

POST /api/address/parse

Format Address

POST /api/address/format

Batch Parse

POST /api/address/batch

Address Expansion

POST /api/address/expand

Health Check

GET /api/address/health

Error Handling

Service Unavailable

Parsing Errors

Usage Examples

Python Example

Batch Processing Example

International Addresses

Information Extraction

Personal Names

Phone Numbers

Email Addresses

Company Names

Performance

Best Practices

1. Provide Complete Information

2. Use Appropriate Language Hints

3. Batch Similar Addresses

4. Validate Before Use

Installation Troubleshooting