Authentication, input and response

Interactive Reference API

POST https://api.altum.ai/interactive-reference

Post the address and optional parameters

Headers

Name	Type	Description
x-api-key*	String	Unique API Key from Altum. Create one via Mopsus(https://mopsus.altum.ai)
Content-Type	String	application/json

Request Body

Name	Type	Description
postcode*	String	1234AB
housenumber*	Number	1
houseaddition	String	A
valuationdate	String	Enter as YYYYMMDD, default is TODAY. Ex: 20211230
innersurfacearea	Number	160
buildyear	Number	2001
housetype	String	See page
energylabel	String	A
url	String	The facade url image of the target house
reference_number	Number	Minimum 3 till 30
strict_street	Boolean	Strict search on street level
strict_buurt	Boolean	Strict search on buurt level
strict_wijk	Boolean	Strict search on wijk level
strict_energylabel	Boolean	Strict search for similar houses with this energy label
comparable_housetype	Number	0,1,2. Default: 0
comparable_innersurfacearea	Number	0,1,2,3. Default: 0
comparable_buildyear	Number	0,1,2,3. Default: 0
comparable_distance	Number	0,1,2. Default: 0
weight_innersurfacearea	Number	Between 0 and 1. Default: 0.2
weight_buildyear	Number	Between 0 and 1. Default: 0.9
weight_transactiondate	Number	Between 0 and 1. Default: 0.2
weight_distance	Number	Between 0 and 1. Default: 0.5
weight_visualsimilarity	Number	Between 0 and 1. Default: 0.5
visual_similarity	Boolean	0: if interested for visual similarity 1: if not interested for visual similarity
date_limit	Number	Between 6 and 60 in months search history of transactions. Default: 60.
housetype_to_search	List	Function to only search for given house types, see page.
include_listings	Boolean	0: if only Kadaster references preferred 1: if both listing and Kadaster references preferred

200: OK Successful response

{
	"GivenHouse": {
		"PostCode": "6942HE",
		"HouseNumber": 56,
		"HouseAddition": null,
		"ValuationDate": 20231125,
		"InnerSurfaceArea": 140,
		"OuterSurfaceArea": 360,
		"HouseType": "Vrijstaande woning",
		"BuildYear": 1960,
		"EnergyLabel": {
			"DefinitiveEnergyLabel": "E",
			"DefinitiveType": "NEN7120",
			"DefinitiveValidity": "2030-10"
		},
		"Image": "https://cloud.funda.nl/valentina_media/165/982/890_720x480.jpg"
	},
	"Inputs": {
		"StrictStreet": 0,
		"StrictBuurt": 0,
		"StrictWijk": 0,
		"StrictEnergyLabel": 0,
		"ComparableHouseType": 0,
		"ComparableInnerSurfaceArea": 0,
		"ComparableBuildYear": 0,
		"ComparableDistance": 0,
		"DateLimit": 60
	},
	"ReferenceData": {
		"ReferencePriceMean": "350000-375000",
		"ReferenceHouses": [
			{
				"PostCode": "6566XN",
				"HouseNumber": 2,
				"HouseAddition": null,
				"Street": "Burgemeester Reijmersstraat",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Geschakelde woning",
				"BuildYear": 1955,
				"InnerSurfaceArea": 171,
				"OuterSurfaceArea": 305,
				"Volume": 598.0,
				"DefinitiveEnergyLabel": "A",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2027-09",
				"Longitude": 6.051181765879782,
				"Latitude": 51.861647149194276,
				"Transactiondate": 201909,
				"Image": "https://cloud.funda.nl/valentina_media/085/383/417_1440.jpg",
				"TransactionPrice": "275000-300000",
				"IndexedTransactionPrice": "400000-450000",
				"PriceIndex": 128.5,
				"Distance": 10616,
				"VisualSimilarityScore": 84.178,
				"Weight": 1.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566AA",
				"HouseNumber": 9,
				"HouseAddition": null,
				"Street": "Burgemeester Hermsenstraat",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Hoekwoning",
				"BuildYear": 1971,
				"InnerSurfaceArea": 110,
				"OuterSurfaceArea": 269,
				"Volume": 385.0,
				"DefinitiveEnergyLabel": null,
				"DefinitiveType": null,
				"DefinitiveValidity": null,
				"Longitude": 6.05011576095955,
				"Latitude": 51.86221046589032,
				"Transactiondate": 202007,
				"Image": "https://cloud.funda.nl/valentina_media/127/400/732_1440x960.jpg",
				"TransactionPrice": "225000-250000",
				"IndexedTransactionPrice": "275000-300000",
				"PriceIndex": 139.2,
				"Distance": 10616,
				"VisualSimilarityScore": 82.376,
				"Weight": 0.978,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566ZT",
				"HouseNumber": 7,
				"HouseAddition": null,
				"Street": "Dennenstraat",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Hoekwoning",
				"BuildYear": 1979,
				"InnerSurfaceArea": 84,
				"OuterSurfaceArea": 203,
				"Volume": 294.0,
				"DefinitiveEnergyLabel": "C",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2028-11",
				"Longitude": 6.0548413275038975,
				"Latitude": 51.859765755682105,
				"Transactiondate": 201903,
				"Image": "https://cloud.funda.nl/valentina_media/086/290/288_1440x960.jpg",
				"TransactionPrice": "150000-175000",
				"IndexedTransactionPrice": "250000-275000",
				"PriceIndex": 124.9,
				"Distance": 10615,
				"VisualSimilarityScore": 75.15,
				"Weight": 0.891,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6942HS",
				"HouseNumber": 16,
				"HouseAddition": null,
				"Street": "Liemersweg",
				"BuurtCode": "BU19550203",
				"WijkCode": "WK195502",
				"City": "Didam",
				"HouseType": "2 onder 1 kap woning",
				"BuildYear": 1957,
				"InnerSurfaceArea": 119,
				"OuterSurfaceArea": 540,
				"Volume": 409.0,
				"DefinitiveEnergyLabel": "D",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2030-11",
				"Longitude": 6.152381715356643,
				"Latitude": 51.933182786208704,
				"Transactiondate": 202104,
				"Image": null,
				"TransactionPrice": "250000-275000",
				"IndexedTransactionPrice": "300000-325000",
				"PriceIndex": 155.4,
				"Distance": 84,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566AA",
				"HouseNumber": 5,
				"HouseAddition": null,
				"Street": "Burgemeester Hermsenstraat",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Tussenwoning",
				"BuildYear": 1971,
				"InnerSurfaceArea": 103,
				"OuterSurfaceArea": 149,
				"Volume": 363.0,
				"DefinitiveEnergyLabel": null,
				"DefinitiveType": null,
				"DefinitiveValidity": null,
				"Longitude": 6.050000952095453,
				"Latitude": 51.862300999960034,
				"Transactiondate": 201910,
				"Image": null,
				"TransactionPrice": "125000-150000",
				"IndexedTransactionPrice": "200000-225000",
				"PriceIndex": 130.3,
				"Distance": 10614,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566XD",
				"HouseNumber": 17,
				"HouseAddition": null,
				"Street": "Wethouder Koenenstraat",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "2 onder 1 kap woning",
				"BuildYear": 1948,
				"InnerSurfaceArea": 182,
				"OuterSurfaceArea": 427,
				"Volume": null,
				"DefinitiveEnergyLabel": null,
				"DefinitiveType": null,
				"DefinitiveValidity": null,
				"Longitude": 6.050890939815937,
				"Latitude": 51.86180598611541,
				"Transactiondate": 201906,
				"Image": null,
				"TransactionPrice": "175000-200000",
				"IndexedTransactionPrice": "250000-275000",
				"PriceIndex": 126.4,
				"Distance": 10615,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "7009CR",
				"HouseNumber": 30,
				"HouseAddition": null,
				"Street": "Bloemersstraat",
				"BuurtCode": "BU02220904",
				"WijkCode": "WK022209",
				"City": "Doetinchem",
				"HouseType": "Hoekwoning",
				"BuildYear": 1950,
				"InnerSurfaceArea": 128,
				"OuterSurfaceArea": 395,
				"Volume": 448.0,
				"DefinitiveEnergyLabel": "C",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2030-02",
				"Longitude": 6.2905459609860666,
				"Latitude": 51.97695144905982,
				"Transactiondate": 202008,
				"Image": null,
				"TransactionPrice": "300000-325000",
				"IndexedTransactionPrice": "400000-450000",
				"PriceIndex": 139.2,
				"Distance": 10616,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566EV",
				"HouseNumber": 140,
				"HouseAddition": null,
				"Street": "Heerbaan",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Vrijstaande woning",
				"BuildYear": 1976,
				"InnerSurfaceArea": 250,
				"OuterSurfaceArea": 843,
				"Volume": null,
				"DefinitiveEnergyLabel": "B",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2032-07",
				"Longitude": 6.04799884793402,
				"Latitude": 51.86338192770656,
				"Transactiondate": 202306,
				"Image": null,
				"TransactionPrice": "600000-650000",
				"IndexedTransactionPrice": "600000-650000",
				"PriceIndex": 182.3,
				"Distance": 10616,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566XA",
				"HouseNumber": 3,
				"HouseAddition": null,
				"Street": "Acaciahof",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Tussenwoning",
				"BuildYear": 1979,
				"InnerSurfaceArea": 106,
				"OuterSurfaceArea": 165,
				"Volume": 362.0,
				"DefinitiveEnergyLabel": "D",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2028-11",
				"Longitude": 6.055114592952519,
				"Latitude": 51.85959341801129,
				"Transactiondate": 201811,
				"Image": null,
				"TransactionPrice": "150000-175000",
				"IndexedTransactionPrice": "225000-250000",
				"PriceIndex": 123.1,
				"Distance": 10618,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "7009CC",
				"HouseNumber": 52,
				"HouseAddition": null,
				"Street": "Zandstraat",
				"BuurtCode": "BU02220903",
				"WijkCode": "WK022209",
				"City": "Doetinchem",
				"HouseType": "Tussenwoning",
				"BuildYear": 1960,
				"InnerSurfaceArea": 112,
				"OuterSurfaceArea": 182,
				"Volume": 352.0,
				"DefinitiveEnergyLabel": "E",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2030-10",
				"Longitude": 6.285970438505862,
				"Latitude": 51.98227174501624,
				"Transactiondate": 202012,
				"Image": null,
				"TransactionPrice": "175000-200000",
				"IndexedTransactionPrice": "225000-250000",
				"PriceIndex": 142.7,
				"Distance": 10623,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			}
		]
	}
}

422: Unprocessable Entity Wrong input format

{
	"detail": [
		{
			"loc": [
				"body",
				43
			],
			"msg": "Expecting value: line 3 column 18 (char 43)",
			"type": "value_error.jsondecode",
			"ctx": {
				"msg": "Expecting value",
				"doc": "{\n  \"postcode\": \"2201PZ\",\n  \"housenumber\": a,\n  \"valuationdate\": \"20121001\"\n}",
				"pos": 43,
				"lineno": 3,
				"colno": 18
			}
		}
	]
}

400: Bad Request Unsuccessful response

{
    'Output': 'The given house type is unsupported.'
}

{
    'Output': 'The energy label of the given house is unknown. Please fill the energylabel input.'
}

{
    'Output': 'We do not have an image for the given house. Please fill the url input.'
}

{
    'Output': 'The given house address not found in database, the combination of Post Code, House Number and House Addition does not exist.'
}

401: Unauthorized No access

{
    'Output': 'Please use https://api.altum.ai or visit https://mopsus.altum.ai to make your request.'
}

403: Forbidden Forbidden

{
	"message": "Missing Authentication Token"
}

500: Internal Server Error Service is not available and/or down

{
	"message": "Internal server error"
}

Request body

Example request

{
  "postcode": "6631KJ",
  "housenumber": 11,
  "houseaddition": "",
  "buildyear": null,
  "innersurfacearea": null,
  "housetype": null,
  "reference_number": 30,
  "strict_street": 1,
  "strict_buurt": 0,
  "strict_wijk": 0,
  "strict_energylabel": 0,
  "date_limit": 24,
  "comparable_housetype": 1,
  "comparable_innersurfacearea": 1,
  "comparable_buildyear": 2,
  "comparable_distance": 0,
  "weight_innersurfacearea": 0.3,
  "weight_buildyear": 0.3,
  "weight_transactiondate": 0.3,
  "weight_distance": 0.3,
  "weight_visualsimilarity": 0.6,
  "housetype_to_search": [],
  "include_funda_data": 0
}