Authentication

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 platforms@digital.justice.gov.uk 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 https://github.com/ministryofjustice/postcodeinfo#auth_tokens 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
True

>>> postcode.latitude
51.50100893654096

>>> postcode.longitude
-0.141587558526369

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

>>> postcode.country
{
    "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": [
                -0.141587558526369,
                51.50100893654096
            ]
        }
    }
]

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': 'https://postcodeinfo-staging.dsd.io',
    'production': 'https://postcodeinfo.service.justice.gov.uk'
}

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:

   POSTCODEINFO_API_URL
   POSTCODEINFO_API_TOKEN
   POSTCODEINFO_API_TIMEOUT

3. Otherwise it will default to development