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.

  • environment (str) – the environment to use. Currently only ‘live’.
  • access_key (str) – the access key provided by . If not provided an ERRauthAccessUnknownKey exception is raised
  • access_secret (str) – the access secret provided by . 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’.

  • 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.



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.

  • 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


Type definitions.


decorator to translate the addressType field.

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


decorator to translate the purposes field.

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

    "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"
    "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 This translation can be accomplished by simply applying the decorators to a function that parses the return value of the API-call.


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.