API documentation

Adres In Beeld Premium

Summary

Use this API to get real-time information about all 7.8 million Dutch households to gain customer insights and increase your conversion rates through personalized and relevant communication.

Methods and endpoints

MethodEndpoint
POSThttps://api.postnl.nl/address/national/insight/v1/premium

Input headers for API

Header keyHeader valueMandatory/optional
apikeyYour apikeyMandatory
Content-Typeapplication/jsonMandatory

Input fields for API body

FieldnameMandatory/optionalFormatExample
PostalCodeMandatoryString [6]1234AB
HouseNumberMandatoryString or Number [1-5]123 (only numerical values allowed)
HouseNumberAdditionOptionalString [0-6]A / a / a2
SelectionMandatoryArray of strings["Segments", "LivingArea", "CommercialActivity"]

Explanation of field ‘Selection’

With the Selection input field, you can select the fields you want to get. Requesting fewer fields can be cheaper.

This input field expects an array of strings, where each string contains the name of the output field you are interested in. There are two extra options, you can also select a full domain by using the name of the domain instead of listing all its corresponding fields. Second you can use the string “All” to request all available fields. In the table below (under section ‘expected output from API’) all the field names are listed. If you mistype or use a fieldname that is not listed, it will be ignored.

The address domain is free and is always included in the output.

Expected output from API

The expected output depends on the fields you have selected, the Address domain is always returned.

You can find all output fields, including their descriptions and formatting in the downloadable documentation.

Example request & response

RequestResponse

{
     "PostalCode": "1507TN",
      "HouseNumber": "6",
      "HouseNumberAddition": "",
      "Selection": ["All"]
}

[
  {
        "Address": {
            "PostalCode": "1507TN",
            "HouseNumber": 6,
            "HouseNumberAddition": ""
        },
         "Residence": {
            "PropertyType": 4,
            "HomeOwnership": 1,
            "YearBuilt": 4,
            "LivingArea": 96,
            "PlotArea": 149,
            "PlotAreaClassification":
            "Volume": 296,
            "PlotSize": 11,
            "EnergyPerformanceCertifcate": "C",
            "EstimatedNumberOfFloors": 2,
            "NumberOfAddressesOnProperty": 1,
            "NumberOfPropertiesOnTheSamePlot": 1,
            "OutbuildingAnnex": 2,
            "SurfaceAreaOutbuildingAnnex": 0,
            "GardenArea": 94,
            "RoofShape": 1,
            "HeightOfTheBuilding": 6,
            "CurrentValueClassification": 5,
            "PropertyValuationClassification": 7,
            "RentalValueInPrivateSectorClassification": 6,
            "DeliveryPoint": "Y",
            "PlotType": "T"
        },
        "SocioDemographic": {
            "AgeHeadOfHousehold": 8,
            "ChildrenInHousehold": 1,
            "AgeEldestChildInHousehold": 5,
            "AgeYoungestChildInHousehold": 5,
            "HouseholdSize": 3,
            "MaritalStatus": 1,
            "Lifestage": 5
        },
        "SocioEconomic": {
            "GrossFamilyIncome": 5,
            "IncomeDecile": 8,
            "NumberOfPeopleWithIncomeFromWork": 2,
            "Education": 2,
            "EmploymentStatus ": 1,
            "SocialClass": 3,
            "NumberOfCarsInHousehold": 1,
            "SpendingPowerIndex": 135,
            "SpendingPowerDecile": 8
        },
        "Segments": {
            "WhizeSegment": "G",
            "WhizeSubSegment": "G31"
        },
        "CommercialActivity": {
            "StandardBusinessClassification": 0,
            "SmallOfficeHomeOffice": 9,
            "EconomicallyActive": 9,
            "CommerciallyActive": 9,
        },
        "ParcelDelivery": {
            "Frequency": {
                "Frequency1": 4,
                "Frequency2": 8,
                "Frequency3": 0,
                "Frequency4": 12,
                "Frequency5": 12,
                "Frequency6": 17,
                "Frequency7": 46
            },
            "EveningDelivery": {
                "EveningDelivery1": 58,
                "EveningDelivery2": 42
            },
            "SameDayDelivery": {
                "SameDayDelivery1": 67,
                "SameDayDelivery2": 33
            },
            "SundayDelivery": {
                "SundayDelivery1": 62,
                "SundayDelivery2": 38
            },
            "Loyalty": {
                "Loyalty1": 33,
                "Loyalty2": 8,
                "Loyalty3": 8,
                "Loyalty4": 25,
                "Loyalty5": 25
            }
        },
        "AreasOfInterest": {
            "DepartmentStores": {
                "DepartmentStores1": 24,
                "DepartmentStores2": 12,
                "DepartmentStores3": 64
            },
            "Electronics": {
                "Electronics1": 16,
                "Electronics2": 20,
                "Electronics3": 64
            },
            "FashionSport": {
                "FashionSport1": 16,
                "FashionSport2": 16,
                "FashionSport3": 68
            },
            "HealthCarePersonalCare": {
                "HealthCarePersonalCare1": 36,
                "HealthCarePersonalCare2": 16,
                "HealthCarePersonalCare3": 48
            },
            "HomeGarden": {
                "HomeGarden1": 36,
                "HomeGarden2": 16,
                "HomeGarden3": 48
            },
            "MediaEntertainment": {
                "MediaEntertainment1": 80,
                "MediaEntertainment2": 20
            },
            "TravelOutdoor": {
                "TravelOutdoor1": 88,
                "TravelOutdoor2": 12
            },
            "PetSupplies": {
                "PetSupplies1": 80,
                "PetSupplies2": 20
            },
            "FoodBeverages": {
                "FoodBeverages1": 96,
                "FoodBeverages2": 4
            },
            "Mobility": {
                "Mobility1": 96,
                "Mobility2": 4
            },
            "Toys": {
                "Toys1": 96,
                "Toys2": 4
            }
        },
           "PriceClass": ">50"
    }
]

Possible error codes

Error codeStatus message
200JSON response with requested data.
206

Address is not a residential address. Example:

{
   "errors": [
     {
       "status": "206",
       "title": "Not a Residential Address",
       "detail": "We found this address in our database, but it is not a residential address."
      }
   ]
}

4xx

Error on customer-side. Example:

{
    "errors": [
       {
          "status": "400",
          "title": "Bad Request",
          "detail: "PostalCode has the wrong format. It should be: 1234AB"
       }
   ]
}

500Error on PostNL side.

Responselabels

You can find all response labels, including their descriptions in the downloadable documentation.

Download documentation