django-postcode-lookup

This Django app provides a pluggable postcode Django REST Framework endpoint. It currently only works for postcodes in The Netherlands.

Currently supports the following services:

- ApiWise
- Webservices.nl
- postcodeapi.nu

Status

Installation

pip install django_postcode_lookup

Minimum supported Django version: 5.2 (Django 6 supported)

Usage

Add the following to your urls.py:

path('postcode-lookup/', include('django_postcode_lookup.urls')),

Add a setting with the required backend

Webservices:

POSTCODE_LOOKUP = {
    'default': {
        'backend': 'django_postcode_lookup.backends.Webservices',
        'OPTIONS': {
            'username': 'someuser',
            'password': 'somepassword',
        }
    }
}

ApiWise:

POSTCODE_LOOKUP = {
    'default': {
        'backend': 'django_postcode_lookup.backends.ApiWise',
        'OPTIONS': {
            'api_key': 'somekey',
        }
    }
}

postcodeapi.nu:

POSTCODE_LOOKUP = {
    'default': {
        'backend': 'django_postcode_lookup.backends.PostcodeApiNu',
        'OPTIONS': {
            'api_key': 'somekey',
            'base_url': 'https://somebaseurl.com',
        }
    }
}

To offer some form of protection to the api endpoint for usage by others a valid csrf token is required.

Changelog and releases

This project uses changie for changelog management.

Add a changelog fragment in pull requests with:

changie new

To prepare a release, run the Prepare release PR GitHub Actions workflow. It batches unreleased fragments, updates CHANGELOG.md and version files, then opens a release pull request. Merging that release PR publishes the package and creates the GitHub release from the changelog entry.