Technical documentation Uitgaven API
This technical document will help you understand the structure of input and output data model used in Uitgaven API's Referentiebedragen . The documentation explains everything needed to use the latest version V6. If you are using a previous version look at the release notes for this version for any changes.
Not all input data are required. The API is designed to handle the optional input data by assigning a default input value. This makes it flexible to deliver the output shown to the user in different ways.
POST Platform
Method used in Refentiebedragen is POST, the API can be called using HTTP Post and it can accept JSON or XML input types.
1. JSON Input
The JSON input consists of an object with several keys:
JSON Key
JSON Data Type
Hoofdpersonen
Kinderen
Huisgenoten
Autos
Woning
NettoBesteedbaarInkomenPerMaand
Adviesdatum
Array
Array
Array
Array
Object
Number
String
Hoofdpersonen must have at least one Hoofdpersoon object . Hoofdpersoon objects have the following keys:
Key
Data type
Enums
Geboortedatum
Geslacht
String
Number/String
NA
0 / Man | 1 / Vrouw
Kinderen can be an empty array or can contain Kind objects. Kind objects have the following keys:
Key
Data type
Enums
Geboortedatum
Geslacht
Woonsituatie
Schooltype
String
Number/String
Number/String
Number/String
NA
0 / Man, 1 / Vrouw
0 / Thuiswonen, 1 / Uitwonend
0 / Geen
1 / Basis
2 / Mbo
3 / HboUniversiteit
4 / NietErkendeOpleiding
5 / OnderbouwHavoVwo
6 / BovenbouwHavoVwo
7 / Vmbo
Huisgenoten can be an empty array or can contain Huisgenoot objects. Huisgenoot objects have the following keys:
Key
Data type
Enums
Geboortedatum
Geslacht
String
Number/String
NA
0 / Man, 1 / Vrouw
Autos can be an empty array or can contain Auto objects. Auto objects have the following keys:
Key
Data type
Enums
Nieuwwaarde
KilometersPerJaar
Status
Number
Number
Number/String
NA
NA
0 / Nieuw, 1 / Tweedehands
NettoBesteedbaarInkomenPerMaand is a JSON data with number as data type. It must have a value.
Woning is an object with the following keys:
Key
Data type
Enums
Soort
Type Woning
Bouwjaar
Energielabel
WozWaarde
GemeenteId
GemeenteCbsId
Number / String
Number/String
Number/String
Number/String
Number
String
String
0 / Huurwoning, 1 / Koopwoning
0 / VrijstaandGroot
1 / VrijstaandKlein
2 / TweeOnderEenKap
3 / RijtjeswoningTussen
4 / RijtjeswoningHoek
5 / Maisonette
6 / Galerij
7 / Portiekwoning
8 / OverigFlat
9 / Kamer
0 / BouwjaarVoor1946
1 / Bouwjaar1946TotEnMet1964
2 / Bouwjaar1965TotEnMet1974
3 / Bouwjaar1975TotEnMet1991
4 / Bouwjaar1992TotEnMet1999
5 / BouwjaarVanaf2000
0 / Onbekend
1 / A
2 / B
3 / C
4 / D
5 / E
6 / F
7 / G
NA
*
*
* You are able to get a list of available municipalities (gemeenten) by doing a HTTP GET call to 'gemeentes'. You can choose to give either the gemeenteId or gemeenteCbsId.
An example of JSON input
2. XML Input
All elements in xml input must be under the namespace of "http://nibud.nl/uitgaven". The root element for xml input must be "Gezin". The elements under "Gezin" will be as follows:
Key
Elements
Hoofdpersonen
Kinderen
Huisgenoten
Autos
Woning
NettoBesteedbaarInkomenPerMaand
Adviesdatum
Subelements
Subelements
Subelements
Subelements
Subelements
Decimal
Date
The element NettoBesteedbaarInkomenPerMaand contains a number, whereas elements contain sub-elements.
The element Hoofdpersonen can have one or more 'Hoofdpersoon'. A 'Hoofdpersoon' contains following elements under it:
Key
Element
Geboortedatum
Geslacht
Date
Man, Vrouw
The element Kinderen can have 0 or more 'Kind' elements. A 'Kind' element contains following elements under it:
Key
Element
Geboortedatum
Geslacht
Woonsituatie
Schooltype
Date
Man, Vrouw
Thuiswonend, Uitwonend
Geen
Basis
Mbo
HboUniversiteit
NietErkendeOpleiding
OnderbouwHavoVwo
BovenbouwHavoVwo
Vmbo
The element Huisgenoten can have 0 or more 'Huisgenoot' elements. A 'Huisgenoot' element contains following elements under it:
Key
Element
Geboortedatum
Geslacht
Date
Man, Vrouw
The element Autos can have 0 or more 'Auto' elements. An 'Auto' element contains following elements under it:
Key
Element
Nieuwwaarde
KilometersPerJaar
Status
Decimal
Integer
Nieuw , Tweedehands
The Woning element contains following elements:
Key
Element
Soort
Type Woning
Bouwjaar
Energielabel
WozWaarde
GemeenteId
GemeenteCbsId
Huurwoning , Koopwoning
VrijstaandGroot
VrijstaandKlein
TweeOnderEenKap
RijtjeswoningTussen
RijtjeswoningHoek
Maisonette
Galerij
Portiekwoning
OverigFlat
Kamer
Voor1945
Van1946TotEnMet1965
Van1966TotEnMet1975
Van1976TotEnMet1979
Van1980TotEnMet1988
Van1989TotEnMet2000
Na2001
Onbekend
A
B
C
D
E
F
G
Decimal
String
String
An example of XML input
3. The Output
The output contains different household expenditures that can be grouped together as expenditure heads with sub items such as 'Insurance' or 'Transport'. The grouping can be discussed with Nibud for the different household expenditures in order to provide best suited output format for the application where Uitgaven Webservice is being used.
For each expenditure item two amounts (basic and example) are returned by the webservice. The Basis is the 'basic amount' and the Voorbeeld is the 'example amount'. The basic amounts are not dependent on the income and show the minimum expenditure amount needed for the given household type. The example amounts depend on the income. Which amount is most suited for a particular application can be discussed with Nibud.
Key
Value Json
Value Xml
Basis
Voorbeeld
Id
Number
Number
Number
Number
Number
String
Every uitgavepost is identified by a unique id:
Uitgavepost
Json Id
Xml Id
Gas
Electriciteit
Water
Onroerende zaakbelasting
Reinigingsheffing
Rioolheffing
Zuiveringsheffing
Heffing gebouwd
Ingezetenenheffing
Mobiele telefoon
Televisie en internet
Aansprakelijkheidsverzekering
Inboedel- en opstalverzekering
Uitvaartverzekering
Zorgverzekering: basis
Zorgverzekering: aanvullend
Overige verzekeringen
Schoolkosten kinderen
Contributies en abonnementen
Belasting auto
Verzekeringen auto
Onderhoud auto
Afschrijving auto
Brandstof auto
Fiets
Openbaar vervoer
Overig vervoer
Kleding
Inboedel
Onderhoud
Eigen risico zorgverzekering
Zelfzorgmiddelen
Recreatie
Voeding
Reiniging
Persoonlijke verzorging
Diverse huishoudelijke uitgaven
Hypotheek
Huur
0
1
2
10
11
12
13
14
15
21
22
33
34
36
37
38
39
40
57
60
61
62
63
64
65
66
70
80
90
100
111
113
120
130
132
133
134
135
136
Gas
Electriciteit
Water
Onroerendezaakbelasting
Reinigingsheffing
Rioolrecht
Waterzuiveringsheffing
OmslagGebouwd
Ingezetenenheffing
MobieleTelefoon
TelevisieEnInternet
Aansprakelijkheidsverzekering
InboedelEnOpstalverzekering
Begrafenisverzekering
Basisverzekering
AanvullendeVerzekering
OverigVerzekering
Schoolkosten
ContributiesEnAbonnementen
AutoBelasting
AutoVerzekeringen
AutoOnderhoud
AutoAfschrijving
AutoBrandstof
Fiets
OpenbaarVervoer
Overigvervoer
Kleding
Inventaris
Onderhoud
Eigenrisico
Zelfzorgmedicijnen
Recreatie
Voeding
Reiniging
PersoonlijkeVerzorging
OverigHuishoudgeld
Hypotheek
Huur
An example of JSON output
An example of XML output
