Skip to main content

API client for

Project description

Test result Coverage report Code Climate Requirements Status

Python package providing an API client for which contains public sector information licensed under the Open Government License v2.0


pip install postcodeinfo



You will need an authentication token (auth token). If you’re using MOJ DS’s Postcode Info server, you can get a token by emailing with a brief summary of:

  • who you are

  • what project you’re going to be using it on

  • roughly how many lookups you expect to do per day

If you’re running your own server, see for instructions on how to create a token.

Quick Start

In your code:

>>> import postcodeinfo

>>> # create a client
>>> client = postcodeinfo.Client("YOUR-ACCESS-TOKEN")

>>> # lookup a postcode
>>> postcode = client.lookup_postcode("SW1A 1AA")

>>> # postcode details
>>> postcode.valid

>>> postcode.latitude

>>> postcode.longitude

>>> postcode.local_authority
    'gss_code': 'E09000033',
    'name': 'Westminster'

    "name": "England",
    "gss_code": "E92000001"

>>> postcode.addresses
        "uprn": "10033544614",
        "organisation_name": "BUCKINGHAM PALACE",
        "department_name": "",
        "po_box_number": "",
        "building_name": "",
        "sub_building_name": "",
        "building_number": None,
        "thoroughfare_name": "",
        "dependent_thoroughfare_name": "",
        "dependent_locality": "",
        "double_dependent_locality": "",
        "post_town": "LONDON",
        "postcode": "SW1A 1AA",
        "postcode_type": "L",
        "formatted_address": "Buckingham Palace\nLondon\nSW1A 1AA",
        "point": {
            "type": "Point",
            "coordinates": [


Apart from the auth token, there is only one other parameter the API client needs - api_url.

Explicit api_url

You can set the api_url explicitly by passing it to the Client constructor

# create a client
client = postcodeinfo.Client("YOUR-API-TOKEN", api_url="https://some.dom.ain")

or by setting it on an existing client, like this

client = postcodeinfo.Client("YOUR-API-TOKEN")
client.api_url = "https://some.dom.ain"

Implicit api_url

If you don’t pass an api_url to the constructor, it will attempt to infer one from the environment. The client has a built-in mapping of environment names to URLs.

>>> postcodeinfo.Client.api_urls
    'development': 'http://localhost:8000',
    'test': 'http://localhost:8000',
    'staging': '',
    'production': ''

It will use the following rules to infer the URL:

  1. If you pass an env parameter to the constructor (eg: client = postcodeinfo.Client("YOUR-API-TOKEN", env="staging")), it will use that as a reference into the api_urls mapping.

  2. If you have DJANGO_SETTINGS_MODULE set in your environment, it will try to find the following settings in that module:

  3. Otherwise it will default to development


This source code is provided as-is, with no incident response or support levels. Please log all questions, issues, and feature requests in the Github issue tracker for this repo, and we’ll take a look as soon as we can. If you’re reporting a bug, then it really helps if you can provide the smallest possible bit of code that reproduces the issue. A failing test is even better!


  • Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed

  • Check the issue tracker to make sure someone hasn’t already requested and/or contributed the feature

  • Fork the project

  • Start a feature/bugfix branch

  • Commit and push until you are happy with your contribution

  • Make sure your changes are covered by unit tests, so that we don’t break it unintentionally in the future.

  • Please don’t mess with, version or history.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

postcodeinfo-0.2.2.tar.gz (6.7 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page