Skip to content

Latest commit

 

History

History
112 lines (83 loc) · 3.61 KB

README.md

File metadata and controls

112 lines (83 loc) · 3.61 KB

Postcode.eu API Python Client

A Python client library for the Postcode.eu API, providing access to international address autocomplete, Dutch address lookup, and validation services.

Installation

uv add postcode-eu-api-client
# Or
pip install postcode-eu-api-client

Quick Start

from postcode_eu_api_client import Client

# Initialize the client
client = Client('your_api_key', 'your_api_secret', 'YourApp/1.0')

# International address autocomplete
import secrets
session_id = secrets.token_hex(16)
result = client.international_autocomplete(
    context='nld',
    term='den',
    session=session_id
)

# Dutch postcode lookup
address = client.dutch_address_by_postcode('1012JS', 1)

# Validate international address
validation = client.validate(
    country='bel',
    postcode='2000',
    locality='antwerpen',
    street='leystraat'
)

API Methods Overview

International Addresses

  • international_autocomplete() - Autocomplete an address
  • international_get_details() - Get address details
  • international_get_supported_countries() - List supported countries

Dutch Address Addresses

  • dutch_address_by_postcode() - Lookup by postcode and house number
  • dutch_address_rd() - Lookup by RD (Rijksdriehoeksmeting) coordinates
  • dutch_address_lat_lon() - Lookup by latitude and longitude
  • dutch_address_bag_number_designation() - Lookup by BAG Number Designation ID
  • dutch_address_bag_addressable_object() - Lookup by BAG Addressable Object ID
  • dutch_address_postcode_ranges() - Lookup streets and house number ranges by postcode

Validate Addresses

  • validate() - Validate international addresses
  • get_country() - Get country information

Accounts

  • account_info() - Get account information
  • create_client_account() - Create client account (resellers only)

View full documentation at https://developer.postcode.eu/documentation.

Exception Handling

The client provides specific exceptions for different error conditions:

from postcode_eu_api_client import Client, InvalidPostcodeException, AuthenticationException

client = Client('key', 'secret', 'platform')

try:
    result = client.dutch_address_by_postcode('invalid', 1)
except InvalidPostcodeException as e:
    print(f"Invalid postcode format: {e}")
except AuthenticationException as e:
    print(f"Authentication failed: {e}")

Available Exceptions

  • PostcodeEuException - Base exception for all Postcode.eu API client exceptions
  • AuthenticationException - Authentication failed with the API
  • BadRequestException - Bad request sent to the API
  • CurlException - HTTP request error (equivalent to cURL error in PHP)
  • CurlNotLoadedException - HTTP library not available (equivalent to cURL not loaded in PHP)
  • ForbiddenException - Access forbidden by the API
  • InvalidJsonResponseException - Invalid JSON response received from the API
  • InvalidPostcodeException - Invalid postcode format provided
  • InvalidSessionValueException - Invalid session value provided
  • NotFoundException - Resource not found
  • ServerUnavailableException - API server is unavailable
  • TooManyRequestsException - Too many requests sent to the API
  • UnexpectedException - Unexpected response from the API

Requirements

  • Python 3.10+
  • A postcode.eu account. Register your account at account.postcode.eu. You can test our service for free.

Examples

This repository includes examples for each API method. See examples/README.md for usage.

License

The code is available under the Simplified BSD License, see the included LICENSE file.