postcodepy API

Postcode API module.

Interface to the REST-service

The REST-service endpoints are covered by the methods of postcode.API class.

class postcodepy.API(environment='practice', access_key=None, access_secret=None, headers=None)

Bases: postcodepy.postcodepy.EndpointsMixin, object

API - postcode API class.

__init__(environment='practice', access_key=None, access_secret=None, headers=None)

Instantiate API wrapper.

Parameters:

• environment (str) – the environment to use. Currently only ‘live’.
• access_key (str) – the access key provided by postcode.nl . If not provided an ERRauthAccessUnknownKey exception is raised
• access_secret (str) – the access secret provided by postcode.nl . If not provided an ERRauthAccessUnknownSecret exception is raised
• headers (dict) – optional headers to set
• returns – a response dictionary

get_postcodedata(postcode, nr, addition='', **params)

get_postcodedata - fetch information for ‘postcode’.

Parameters:

• postcode (string) – The full (dutch) postcode
• nr (int) – The housenumber
• addition (string (optional)) – the extension to a housenumber
• params (dict (optional)) – a list of parameters to send with the request.
• returns – a response dictionary

get_signalcheck(sar, **params)

get_signalcheck - perform a signal check.

Parameters:

• sar (dict) – signal-api-request specified as a dictionary of parameters. All of these parameters are optional. For details check https://api.postcode.nl/documentation/signal-api-example.
• returns – a response dictionary

Exceptions

class postcodepy.PostcodeError(exceptionId, response_data=None)

Bases: exceptions.Exception

PostcodeError - Generic error class, catches response errors.

__init__(exceptionId, response_data=None)

instantiate PostcodeError instance.

Parameters:

• exceptionId (str) – the id of the exception. It should match one of the known exception id’s. If it does not match it is set to: ERRUnknownExceptionFromPostcodeNl
• response_data (data) – the data received at the moment the exception occurred

Typedefs

Type definitions.

postcodepy.typedefs.translate_addresstype(f)

decorator to translate the addressType field.

translate the value of the addressType field of the API response into a translated type.

postcodepy.typedefs.translate_purposes(f)

decorator to translate the purposes field.

translate the values of the purposes field of the API response into translated values.

POSTCODE_API_TYPEDEFS_ADDRES_TYPES =
{
    "building": "verblijfsobject",
    "house boat site": "location used for mooring house boats",
    "PO box": "PO box",
    "mobile home site": "location used for mobile homes and trailers"
}

POSTCODE_API_TYPEDEFS_PURPOSES =
{
    "assembly": "bijeenkomstfunctie",
    "office": "kantoorfunctie",
    "detention": "celfunctie",
    "lodging": "logiesfunctie",
    "shopping": "winkelfunctie",
    "sport": "sportfunctie",
    "education": "onderwijsfunctie",
    "industry": "industriefunctie",
    "other": "overige gebruiksfunctie",
    "residency": "woonfunctie",
    "healthcare": "gezondheidszorgfunctie"
}

The REST responses may contain fields that can be translated into the standard descriptions as provided by postcode.nl. This translation can be accomplished by simply applying the decorators to a function that parses the return value of the API-call.

Logging

In case values can’t be translated, a warning is logged by logger. The message will contain the postcode that was responsible for the warning.