# Referentiewoningen API

Aan de hand van een adres geeft dit endpoint tot 50 kwalitatief goede referentieobjecten terug. Deze referenties zijn voorzien van een geïndexeerde transactieprijs zodat u makkelijk de objecten in de lijst met elkaar kan vergelijken zonder rekening te houden met de verkoopdatum. Daarnaast is elke referentie voorzien van een referentiescore zodat u makkelijk kunt zien welke objecten de beste referentie zijn voor het te evalueren object. Deze score is gebaseerd op de karakteristieken van de woning, de verkoopdatum en de afstand tussen de objecten.

### Voor wie is het?

* U wilt een zo compleet mogelijke lijst van referentieobjecten voor een bepaald object
* U wilt deze objecten graag in één oogopslag kunnen vergelijken

### Wat moet ik weten?

* Dit endpoint levert geen koopsommen terug. In plaats daarvan krijgt u toegang tot een geïndexeerde transactieprijs wat u in staat stelt om te vergelijken zonder rekening te houden met de verkoopdatum
* Deze oplossing wordt gebruikt en regelmatig getest door onafhankelijke taxateurs

## GET /mx-reference-finder

> Returns comparable properties with price ranges.

```json
{"openapi":"3.0.3","info":{"title":"Matrixian API","version":"0.0.1"},"servers":[{"url":"https://api.matrixian.com/v1","description":"Matrixian API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"{{API_KEY}}"}},"schemas":{"MxReferenceFinderInput":{"properties":{"postalCode":{"type":"string","title":"Postalcode","description":"Postal code"},"houseNumber":{"type":"integer","title":"Housenumber","description":"House number"},"houseLetter":{"title":"Houseletter","description":"House letter","type":"string","nullable":true},"houseNumberExt":{"title":"Housenumberext","description":"House number extension","type":"string","nullable":true},"valuationDate":{"type":"string","format":"date","title":"Valuationdate","description":"Valuation date","default":"2026-04-16"},"buildYear":{"title":"Buildyear","description":"Indication of the year in which the building will originally be delivered in, or is architecturally ready. Also known as construction year.","type":"integer","nullable":true},"houseType":{"description":"Type of dwelling.","$ref":"#/components/schemas/HouseType","nullable":true},"useSurface":{"title":"Usesurface","description":"The usable surface area of a property object in m2.","type":"integer","nullable":true},"parcelSurface":{"title":"Parcelsurface","description":"The lot/parcel surface in m2.","type":"integer","nullable":true},"allowedHouseTypes":{"title":"Allowedhousetypes","description":"Allowed house types of reference objects, separated by commas.","items":{"$ref":"#/components/schemas/HouseType"},"type":"array","uniqueItems":true,"nullable":true},"locationWeight":{"title":"Locationweight","description":"Measure of Location importance in finding reference objects.","default":0.4,"type":"number","nullable":true},"houseDetailsWeight":{"title":"Housedetailsweight","description":"Measure of House details importance in finding WOZ reference objects.","default":0.4,"type":"number","nullable":true},"volume":{"title":"Volume","description":"Volume in m3.","type":"integer","nullable":true},"energyLabel":{"description":"A label indicating how well the property object is insulated.","$ref":"#/components/schemas/EnergyLabel","nullable":true},"nReferences":{"type":"integer","maximum":50,"title":"Nreferences","description":"Amount of reference objects to return.","default":50},"minUseSurface":{"title":"Minusesurface","description":"Minimal use surface of reference objects.","type":"integer","nullable":true},"maxUseSurface":{"title":"Maxusesurface","description":"Maximal use surface of reference objects.","type":"integer","nullable":true},"minBuildYear":{"title":"Minbuildyear","description":"Minimum build year of reference objects.","type":"integer","nullable":true},"maxBuildYear":{"title":"Maxbuildyear","description":"Maximum build year of reference objects.","type":"integer","maximum":2026,"nullable":true},"minParcelSurface":{"title":"Minparcelsurface","description":"Minimal parcel surface of reference objects.","type":"integer","nullable":true},"maxParcelSurface":{"title":"Maxparcelsurface","description":"Maximum parcel surface of reference objects.","type":"integer","nullable":true},"maxDistance":{"type":"integer","title":"Maxdistance","description":"Maximum distance from the valuation object to the reference object in meters.","default":10000},"minTransportDate":{"title":"Mintransportdate","description":"Minimal transport date of reference objects.","type":"string","format":"date","nullable":true},"maxTransportDate":{"title":"Maxtransportdate","description":"Maximum  transport date of reference objects.","type":"string","format":"date","nullable":true},"transportDateWeight":{"title":"Transportdateweight","description":"Measure of transport date importance in finding reference objects.","default":0.2,"type":"number","nullable":true},"includeImageUrls":{"title":"Includeimageurls","default":true,"type":"boolean","nullable":true},"minReferenceScore":{"title":"Minreferencescore","description":"Minimal reference score of reference objects.","default":0.6,"type":"number","nullable":true},"customSorting":{"default":"DEFAULT","allOf":[{"$ref":"#/components/schemas/CustomSorting"}]}},"type":"object","required":["postalCode","houseNumber"],"title":"MxReferenceFinderInput"},"HouseType":{"type":"string","enum":["Appartement","Galerijflat","Maisonnette","Portiekwoning","Portiekflat","Corridorflat","Bovenwoning","Benedenwoning","Tussenwoning","Geschakelde woning","Eindwoning","Hoekwoning","2-onder-1-kapwoning","Geschakelde 2-onder-1-kapwoning","Halfvrijstaande woning","Vrijstaande woning"],"title":"HouseType"},"EnergyLabel":{"type":"string","enum":["A+++++","A++++","A+++","A++","A+","A","B","C","D","E","F","G"],"title":"EnergyLabel"},"CustomSorting":{"type":"string","enum":["DEFAULT","WOZWET","BEZWAARMAKER"],"title":"CustomSorting"},"MxReferenceFinderResponse":{"properties":{"postalCode":{"type":"string","title":"Postal Code","description":"Postal code"},"houseNumber":{"type":"integer","title":"House Number","description":"House number"},"houseLetter":{"title":"House Letter","description":"House letter","type":"string","nullable":true},"houseNumberExt":{"title":"House Number Ext","description":"House number extension","type":"string","nullable":true},"houseType":{"type":"string","title":"House Type","description":"Dwelling type"},"buildYear":{"type":"integer","title":"Build Year","description":"Indication of the year in which the building will originally be delivered in, or is architecturally ready. Also known as construction year."},"useSurface":{"type":"integer","title":"Use Surface","description":"The usable surface area of a property object in square meters."},"useSurfaceBAG":{"type":"integer","title":"Use Surface Bag","description":"The usable surface area of a property object in square meters according to the BAG."},"parcelSurface":{"type":"integer","title":"Parcel Surface","description":"The lot/parcel surface in m2."},"references":{"items":{"$ref":"#/components/schemas/ReferenceResponse"},"type":"array","title":"References","description":"List of references"},"valuationDate":{"type":"string","format":"date","title":"Valuation Date","description":"The date of the valuation"},"frontImageUrl":{"title":"Front Image Url","description":"The front image url of the house/object.","type":"string","nullable":true},"energyLabel":{"title":"Energy Label","description":"A label indicating how well the property object is insulated.","type":"string","nullable":true},"energyLabelRegistrationValidUntil":{"title":"Energy Label Registration Valid Until","description":"Date until which the energy label is valid.","type":"string","format":"date","nullable":true},"volume":{"title":"Volume","description":"Volume in m3.","type":"integer","nullable":true},"storageSpace":{"title":"Storage Space","description":"Description of available storage space.","type":"string","nullable":true},"garage":{"title":"Garage","description":"Description of garage facilities.","type":"string","nullable":true},"description":{"title":"Description","description":"Description of the property listing.","type":"string","nullable":true},"dateTransaction":{"title":"Date Transaction","description":"Date of transaction","type":"string","format":"date","nullable":true},"transactionPriceIndexed":{"title":"Transaction Price Indexed","description":"The price of the transaction, indexed to the valuation date.","type":"integer","nullable":true},"transactionPriceIndexedDateTransport":{"title":"Transactions Price Indexed Date Transport","description":"The price of the transaction, indexed to the transport date.","type":"integer","nullable":true},"transactionPriceIndexedDateSale":{"title":"Transaction Price Indexed Date Sale","description":"The price of the transaction, indexed to the sale date.","type":"integer","nullable":true},"dateSale":{"title":"Date Sale","description":"Date of sale","type":"string","format":"date","nullable":true},"dateTransport":{"title":"Date Transport","description":"Date of transport","type":"string","format":"date","nullable":true}},"type":"object","required":["postalCode","houseNumber","houseType","buildYear","useSurface","useSurfaceBAG","parcelSurface","valuationDate","energyLabel","volume"],"title":"MxReferenceFinderResponse"},"ReferenceResponse":{"properties":{"index":{"description":"Index number","title":"Index Nr","type":"integer"},"bagId":{"description":"Identification number according to the BAG.","title":"Number Id","type":"string"},"streetName":{"description":"Street name","title":"Street Name","type":"string"},"postalCode":{"description":"Postal code","title":"Postal Code","type":"string"},"houseNumber":{"description":"House number","title":"House Number","type":"integer"},"houseLetter":{"default":null,"description":"House letter","title":"House Letter","type":"string","nullable":true},"houseNumberExt":{"default":null,"description":"House number extension","title":"House Number Ext","type":"string","nullable":true},"town":{"description":"City","title":"City Name","type":"string"},"municipality":{"description":"Municipality","title":"Municipality Name","type":"string"},"province":{"description":"Province","title":"Province Name","type":"string"},"latitude":{"description":"Latitude","title":"Latitude","type":"number"},"longitude":{"description":"Longitude","title":"Longitude","type":"number"},"distance":{"description":"Distance of the reference object from the valuation object in meter.","title":"Distance","type":"number"},"houseType":{"description":"Dwelling type","title":"House Type","type":"string"},"buildYear":{"description":"Indication of the year in which the building will originally be delivered in, or is architecturally ready. Also known as construction year.","title":"Build Year","type":"integer"},"useSurface":{"description":"The usable surface area of a property object in square meters.","title":"Use Surface","type":"integer"},"useSurfaceBAG":{"description":"The usable surface area of a property object in square meters according to the BAG.","title":"Use Surface Bag","type":"integer","nullable":true},"parcelSurface":{"description":"The lot/parcel surface in m2.","title":"Parcel Surface","type":"integer"},"volume":{"default":null,"description":"Volume in cubic meters.","title":"Volume","type":"integer","nullable":true},"energyLabel":{"default":null,"description":"A label indicating how well the property object is insulated.","title":"Energy Label","type":"string","nullable":true},"energyLabelIsRegistered":{"description":"Boolean indicating whether the energy label has been registered.","title":"Energy Label Is Registered","type":"boolean","nullable":true},"energyLabelRegistrationValidUntil":{"default":null,"description":"Date until which the energy label is valid.","title":"Energy Label Registration Valid Until","format":"date","type":"string","nullable":true},"dateTransaction":{"description":"Transaction date","format":"date","title":"Date Transaction","type":"string"},"priceClassLow":{"description":"Lower bound of the price class based on indexed transaction price.","title":"Price Class Low","type":"integer"},"priceClassHigh":{"description":"Upper bound of the price class based on indexed transaction price.","title":"Price Class High","type":"integer"},"dateOnOfferSince":{"default":null,"description":"Date since when the reference object is offered on the market.","title":"Date On Offer Since","format":"date","type":"string","nullable":true},"offeredPrice":{"default":null,"description":"Price for which the listing of the reference object is on offer","title":"Offered Price","type":"integer","nullable":true},"status":{"default":null,"description":"Status of the listing of the reference object (online/offline)","title":"Status","type":"string","nullable":true},"storageSpace":{"default":null,"description":"Description of available storage space.","title":"Storage Space","type":"string","nullable":true},"exteriorSpace":{"default":null,"description":"Description of available exterior space (e.g. garden, balcony, terrace).","title":"Exterior Space","type":"string","nullable":true},"garage":{"default":null,"description":"Description of garage facilities.","title":"Garage","type":"string","nullable":true},"insulation":{"default":null,"description":"Description of insulation provisions.","title":"Insulation","type":"string","nullable":true},"imageFront":{"default":null,"description":"Url of the image of the front side of the house/object.","title":"Image Front","type":"string","nullable":true},"imageOther":{"default":null,"description":"List of image urls of the object.","title":"Image Other","items":{"type":"string"},"type":"array","nullable":true},"description":{"default":null,"description":"Description of the listing of the reference object","title":"Description","type":"string","nullable":true},"addressSrc":{"description":"Source of the address data value.","title":"Address Source","type":"string"},"houseTypeSrc":{"description":"Source of the dwelling type value.","title":"House Type Source","type":"string"},"buildYearSrc":{"description":"Source of the build year value.","title":"Build Year Source","type":"string"},"useSurfaceSrc":{"description":"Source of the use surface value.","title":"Use Surface Source","type":"string"},"parcelSurfaceSrc":{"description":"Source of the parcel surface value.","title":"Parcel Surface Source","type":"string"},"volumeSrc":{"default":null,"description":"Source of the volume value.","title":"Volume Source","type":"string","nullable":true},"energyLabelSrc":{"description":"Source of the energy label value.","title":"Energy Label Source","type":"string"},"dateTransactionSrc":{"description":"Source of the transaction date value.","title":"Date Transaction Source","type":"string"},"dateOnOfferSinceSrc":{"default":null,"description":"Source of the date on offer since value.","title":"Date On Offer Since Source","type":"string","nullable":true},"offeredPriceSrc":{"default":null,"description":"Source of the offered price value.","title":"Offered Price Source","type":"string","nullable":true},"statusSrc":{"description":"Source of the status value.","title":"Status Source","type":"string","nullable":true},"storageSpaceSrc":{"default":null,"description":"Source of the storage space value.","title":"Storage Space Source","type":"string","nullable":true},"exteriorSpaceSrc":{"default":null,"description":"Source of the exterior space value.","title":"Exterior Space Source","type":"string","nullable":true},"garageSrc":{"default":null,"description":"Source of the garage value.","title":"Garage Source","type":"string","nullable":true},"insulationSrc":{"default":null,"description":"Source of the insulation value.","title":"Insulation Source","type":"string","nullable":true},"imageFrontSrc":{"default":null,"description":"Source of the front view image url.","title":"Image Front Source","type":"string","nullable":true},"imageOtherSrc":{"default":null,"description":"Source of the other image urls.","title":"Image Other Source","type":"string","nullable":true},"descriptionSrc":{"default":null,"description":"Source of the description value.","title":"Description Source","type":"string","nullable":true},"multipleObjects":{"description":"Boolean indicating whether the address has multiple objects.","title":"Multiple Objects","type":"boolean"},"referenceTransactionApiCallPrice":{"default":null,"description":"The transaction price of this reference object at the time of the API call.","title":"Reference Transaction Api Call Price","type":"integer","nullable":true},"transactionPrice":{"default":null,"description":"The price of the transaction.","title":"Transaction Price","type":"integer","nullable":true},"compScore":{"description":"A weighted score on the comparability between the input house and the reference house, based on house type, build year, nett surface, parcel surface and energy label","title":"Similarity Score","type":"number"},"fillGrade":{"description":"A measure indicating the data coverage of all house characteristic data in percentage","title":"Filling Grade","type":"number"},"ownershipSituationFunda":{"default":null,"description":"Ownership situation as reported by Funda (e.g. freehold, leasehold).","title":"Ownership Situation Funda","type":"string","nullable":true},"ownershipSituationKadaster":{"default":null,"description":"Ownership situation as registered in the Kadaster (land registry).","title":"Ownership Situation Kadaster","type":"string","nullable":true},"dateTransport":{"description":"Date of transport","format":"date","title":"Date Transport","type":"string"},"dateSale":{"default":null,"description":"Date of sale","title":"Date Sale","format":"date","type":"string","nullable":true},"transactionPriceIndexed":{"description":"The price of the transaction, indexed to the valuation date.","title":"Transaction Price Indexed","type":"integer"},"transactionPriceIndexedDateTransport":{"default":null,"description":"The price of the transaction, indexed to the transport date.","title":"Transactions Price Indexed Date Transport","type":"integer","nullable":true},"transactionPriceIndexedDateSale":{"default":null,"description":"The price of the transaction, indexed to the sale date.","title":"Transaction Price Indexed Date Sale","type":"integer","nullable":true},"isMonument":{"default":false,"description":"Boolean indicating whether the house is a monument.","title":"Is Monument","type":"boolean","nullable":true},"nettUseSurface":{"default":null,"description":"Net usable surface area of the reference object in square meters.","title":"Nett Use Surface","type":"integer","nullable":true},"referenceScore":{"description":"Overall weighted reference score combining location and house details scores.","title":"Reference Score","type":"number"},"dateScore":{"description":"Score reflecting how recent the transaction date of the reference object is.","title":"Date Score","type":"number"},"locationScore":{"description":"Score reflecting the proximity and postal code similarity of the reference object.","title":"Location Score","type":"number"},"houseDetailsScore":{"description":"A weighted score on the comparability between the input house and the reference house, based on house type, build year, nett surface, parcel surface and energy label","title":"House Details Score","type":"number"}},"required":["index","bagId","streetName","postalCode","houseNumber","town","municipality","province","latitude","longitude","distance","houseType","buildYear","useSurface","useSurfaceBAG","parcelSurface","energyLabelIsRegistered","dateTransaction","priceClassLow","priceClassHigh","addressSrc","houseTypeSrc","buildYearSrc","useSurfaceSrc","parcelSurfaceSrc","energyLabelSrc","dateTransactionSrc","statusSrc","multipleObjects","compScore","fillGrade","dateTransport","transactionPriceIndexed","referenceScore","dateScore","locationScore","houseDetailsScore"],"title":"ReferenceResponse","type":"object"},"ErrorObject":{"properties":{"code":{"type":"integer","title":"Code"},"message":{"type":"string","title":"Message"},"errors":{"items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array","title":"Errors"}},"type":"object","required":["code","message","errors"],"title":"ErrorObject"},"ErrorDetail":{"properties":{"reason":{"type":"string","title":"Reason"},"message":{"type":"string","title":"Message"}},"type":"object","required":["reason","message"],"title":"ErrorDetail"}}},"paths":{"/mx-reference-finder":{"get":{"description":"Returns comparable properties with price ranges.","operationId":"mxReferenceFinder","parameters":[{"description":"Postal code","required":true,"style":"form","explode":true,"schema":{"type":"string"},"name":"postalCode","in":"query"},{"description":"House number","required":true,"style":"form","explode":true,"schema":{"type":"integer"},"name":"houseNumber","in":"query"},{"description":"House letter","required":false,"style":"form","explode":true,"schema":{"type":"string"},"name":"houseLetter","in":"query"},{"description":"House number extension","required":false,"style":"form","explode":true,"schema":{"type":"string"},"name":"houseNumberExt","in":"query"},{"description":"Valuation date","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"date","default":"2026-04-16"},"name":"valuationDate","in":"query"},{"description":"Indication of the year in which the building will originally be delivered in, or is architecturally ready. Also known as construction year.","required":false,"style":"form","explode":true,"schema":{"type":"integer"},"name":"buildYear","in":"query"},{"description":"Type of dwelling.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["Appartement","Galerijflat","Maisonnette","Portiekwoning","Portiekflat","Corridorflat","Bovenwoning","Benedenwoning","Tussenwoning","Geschakelde woning","Eindwoning","Hoekwoning","2-onder-1-kapwoning","Geschakelde 2-onder-1-kapwoning","Halfvrijstaande woning","Vrijstaande woning"]},"name":"houseType","in":"query"},{"description":"The usable surface area of a property object in m2.","required":false,"style":"form","explode":true,"schema":{"type":"integer"},"name":"useSurface","in":"query"},{"description":"The lot/parcel surface in m2.","required":false,"style":"form","explode":true,"schema":{"type":"integer"},"name":"parcelSurface","in":"query"},{"description":"Allowed house types of reference objects, separated by commas.","required":false,"style":"form","explode":false,"schema":{"items":{"type":"string","enum":["Appartement","Galerijflat","Maisonnette","Portiekwoning","Portiekflat","Corridorflat","Bovenwoning","Benedenwoning","Tussenwoning","Geschakelde woning","Eindwoning","Hoekwoning","2-onder-1-kapwoning","Geschakelde 2-onder-1-kapwoning","Halfvrijstaande woning","Vrijstaande woning"]},"type":"array","uniqueItems":true},"name":"allowedHouseTypes","in":"query"},{"description":"Measure of Location importance in finding reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"number","default":0.4},"name":"locationWeight","in":"query"},{"description":"Measure of House details importance in finding WOZ reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"number","default":0.4},"name":"houseDetailsWeight","in":"query"},{"description":"Volume in m3.","required":false,"style":"form","explode":true,"schema":{"type":"integer"},"name":"volume","in":"query"},{"description":"A label indicating how well the property object is insulated.","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["A+++++","A++++","A+++","A++","A+","A","B","C","D","E","F","G"]},"name":"energyLabel","in":"query"},{"description":"Amount of reference objects to return.","required":false,"style":"form","explode":true,"schema":{"type":"integer","default":50},"name":"nReferences","in":"query"},{"description":"Minimal use surface of reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"integer"},"name":"minUseSurface","in":"query"},{"description":"Maximal use surface of reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"integer"},"name":"maxUseSurface","in":"query"},{"description":"Minimum build year of reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"integer"},"name":"minBuildYear","in":"query"},{"description":"Maximum build year of reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"integer"},"name":"maxBuildYear","in":"query"},{"description":"Minimal parcel surface of reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"integer"},"name":"minParcelSurface","in":"query"},{"description":"Maximum parcel surface of reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"integer"},"name":"maxParcelSurface","in":"query"},{"description":"Maximum distance from the valuation object to the reference object in meters.","required":false,"style":"form","explode":true,"schema":{"type":"integer","default":10000},"name":"maxDistance","in":"query"},{"description":"Minimal transport date of reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"date"},"name":"minTransportDate","in":"query"},{"description":"Maximum  transport date of reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"date"},"name":"maxTransportDate","in":"query"},{"description":"Measure of transport date importance in finding reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"number","default":0.2},"name":"transportDateWeight","in":"query"},{"description":"Minimal reference score of reference objects.","required":false,"style":"form","explode":true,"schema":{"type":"number","default":0.6},"name":"minReferenceScore","in":"query"}],"responses":{"200":{"description":"MxReferenceFinderResponse","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","nullable":true},"params":{"$ref":"#/components/schemas/MxReferenceFinderInput"},"data":{"$ref":"#/components/schemas/MxReferenceFinderResponse"},"error":{"additionalProperties":{"type":"string"},"type":"object"},"meta":{"additionalProperties":{"type":"string"},"type":"object","nullable":true},"status":{"type":"string"}},"type":"object","required":["data","status"]}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","nullable":true},"params":{"$ref":"#/components/schemas/MxReferenceFinderInput"},"data":{"additionalProperties":{"type":"string"},"type":"object"},"error":{"$ref":"#/components/schemas/ErrorObject"},"meta":{"additionalProperties":{"type":"string"},"type":"object","nullable":true},"status":{"type":"string"}},"type":"object","required":["error","status"]}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","nullable":true},"params":{"$ref":"#/components/schemas/MxReferenceFinderInput"},"data":{"additionalProperties":{"type":"string"},"type":"object"},"error":{"$ref":"#/components/schemas/ErrorObject"},"meta":{"additionalProperties":{"type":"string"},"type":"object","nullable":true},"status":{"type":"string"}},"type":"object","required":["error","status"]}}}},"403":{"description":"HTTP 403","content":{"application/json":{"schema":{"properties":{"message":{"type":"string"}},"type":"object","required":["message"]}}}},"404":{"description":"HTTP 404","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","nullable":true},"params":{"$ref":"#/components/schemas/MxReferenceFinderInput"},"data":{"additionalProperties":{"type":"string"},"type":"object"},"error":{"$ref":"#/components/schemas/ErrorObject"},"meta":{"additionalProperties":{"type":"string"},"type":"object","nullable":true},"status":{"type":"string"}},"type":"object","required":["error","status"]}}}},"500":{"description":"HTTP 500","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","nullable":true},"params":{"$ref":"#/components/schemas/MxReferenceFinderInput"},"data":{"additionalProperties":{"type":"string"},"type":"object"},"error":{"$ref":"#/components/schemas/ErrorObject"},"meta":{"additionalProperties":{"type":"string"},"type":"object","nullable":true},"status":{"type":"string"}},"type":"object","required":["error","status"]}}}}}}}}}
```

## The MxReferenceFinderResponse object

```json
{"openapi":"3.0.3","info":{"title":"Matrixian API","version":"0.0.1"},"components":{"schemas":{"MxReferenceFinderResponse":{"properties":{"postalCode":{"type":"string","title":"Postal Code","description":"Postal code"},"houseNumber":{"type":"integer","title":"House Number","description":"House number"},"houseLetter":{"title":"House Letter","description":"House letter","type":"string","nullable":true},"houseNumberExt":{"title":"House Number Ext","description":"House number extension","type":"string","nullable":true},"houseType":{"type":"string","title":"House Type","description":"Dwelling type"},"buildYear":{"type":"integer","title":"Build Year","description":"Indication of the year in which the building will originally be delivered in, or is architecturally ready. Also known as construction year."},"useSurface":{"type":"integer","title":"Use Surface","description":"The usable surface area of a property object in square meters."},"useSurfaceBAG":{"type":"integer","title":"Use Surface Bag","description":"The usable surface area of a property object in square meters according to the BAG."},"parcelSurface":{"type":"integer","title":"Parcel Surface","description":"The lot/parcel surface in m2."},"references":{"items":{"$ref":"#/components/schemas/ReferenceResponse"},"type":"array","title":"References","description":"List of references"},"valuationDate":{"type":"string","format":"date","title":"Valuation Date","description":"The date of the valuation"},"frontImageUrl":{"title":"Front Image Url","description":"The front image url of the house/object.","type":"string","nullable":true},"energyLabel":{"title":"Energy Label","description":"A label indicating how well the property object is insulated.","type":"string","nullable":true},"energyLabelRegistrationValidUntil":{"title":"Energy Label Registration Valid Until","description":"Date until which the energy label is valid.","type":"string","format":"date","nullable":true},"volume":{"title":"Volume","description":"Volume in m3.","type":"integer","nullable":true},"storageSpace":{"title":"Storage Space","description":"Description of available storage space.","type":"string","nullable":true},"garage":{"title":"Garage","description":"Description of garage facilities.","type":"string","nullable":true},"description":{"title":"Description","description":"Description of the property listing.","type":"string","nullable":true},"dateTransaction":{"title":"Date Transaction","description":"Date of transaction","type":"string","format":"date","nullable":true},"transactionPriceIndexed":{"title":"Transaction Price Indexed","description":"The price of the transaction, indexed to the valuation date.","type":"integer","nullable":true},"transactionPriceIndexedDateTransport":{"title":"Transactions Price Indexed Date Transport","description":"The price of the transaction, indexed to the transport date.","type":"integer","nullable":true},"transactionPriceIndexedDateSale":{"title":"Transaction Price Indexed Date Sale","description":"The price of the transaction, indexed to the sale date.","type":"integer","nullable":true},"dateSale":{"title":"Date Sale","description":"Date of sale","type":"string","format":"date","nullable":true},"dateTransport":{"title":"Date Transport","description":"Date of transport","type":"string","format":"date","nullable":true}},"type":"object","required":["postalCode","houseNumber","houseType","buildYear","useSurface","useSurfaceBAG","parcelSurface","valuationDate","energyLabel","volume"],"title":"MxReferenceFinderResponse"},"ReferenceResponse":{"properties":{"index":{"description":"Index number","title":"Index Nr","type":"integer"},"bagId":{"description":"Identification number according to the BAG.","title":"Number Id","type":"string"},"streetName":{"description":"Street name","title":"Street Name","type":"string"},"postalCode":{"description":"Postal code","title":"Postal Code","type":"string"},"houseNumber":{"description":"House number","title":"House Number","type":"integer"},"houseLetter":{"default":null,"description":"House letter","title":"House Letter","type":"string","nullable":true},"houseNumberExt":{"default":null,"description":"House number extension","title":"House Number Ext","type":"string","nullable":true},"town":{"description":"City","title":"City Name","type":"string"},"municipality":{"description":"Municipality","title":"Municipality Name","type":"string"},"province":{"description":"Province","title":"Province Name","type":"string"},"latitude":{"description":"Latitude","title":"Latitude","type":"number"},"longitude":{"description":"Longitude","title":"Longitude","type":"number"},"distance":{"description":"Distance of the reference object from the valuation object in meter.","title":"Distance","type":"number"},"houseType":{"description":"Dwelling type","title":"House Type","type":"string"},"buildYear":{"description":"Indication of the year in which the building will originally be delivered in, or is architecturally ready. Also known as construction year.","title":"Build Year","type":"integer"},"useSurface":{"description":"The usable surface area of a property object in square meters.","title":"Use Surface","type":"integer"},"useSurfaceBAG":{"description":"The usable surface area of a property object in square meters according to the BAG.","title":"Use Surface Bag","type":"integer","nullable":true},"parcelSurface":{"description":"The lot/parcel surface in m2.","title":"Parcel Surface","type":"integer"},"volume":{"default":null,"description":"Volume in cubic meters.","title":"Volume","type":"integer","nullable":true},"energyLabel":{"default":null,"description":"A label indicating how well the property object is insulated.","title":"Energy Label","type":"string","nullable":true},"energyLabelIsRegistered":{"description":"Boolean indicating whether the energy label has been registered.","title":"Energy Label Is Registered","type":"boolean","nullable":true},"energyLabelRegistrationValidUntil":{"default":null,"description":"Date until which the energy label is valid.","title":"Energy Label Registration Valid Until","format":"date","type":"string","nullable":true},"dateTransaction":{"description":"Transaction date","format":"date","title":"Date Transaction","type":"string"},"priceClassLow":{"description":"Lower bound of the price class based on indexed transaction price.","title":"Price Class Low","type":"integer"},"priceClassHigh":{"description":"Upper bound of the price class based on indexed transaction price.","title":"Price Class High","type":"integer"},"dateOnOfferSince":{"default":null,"description":"Date since when the reference object is offered on the market.","title":"Date On Offer Since","format":"date","type":"string","nullable":true},"offeredPrice":{"default":null,"description":"Price for which the listing of the reference object is on offer","title":"Offered Price","type":"integer","nullable":true},"status":{"default":null,"description":"Status of the listing of the reference object (online/offline)","title":"Status","type":"string","nullable":true},"storageSpace":{"default":null,"description":"Description of available storage space.","title":"Storage Space","type":"string","nullable":true},"exteriorSpace":{"default":null,"description":"Description of available exterior space (e.g. garden, balcony, terrace).","title":"Exterior Space","type":"string","nullable":true},"garage":{"default":null,"description":"Description of garage facilities.","title":"Garage","type":"string","nullable":true},"insulation":{"default":null,"description":"Description of insulation provisions.","title":"Insulation","type":"string","nullable":true},"imageFront":{"default":null,"description":"Url of the image of the front side of the house/object.","title":"Image Front","type":"string","nullable":true},"imageOther":{"default":null,"description":"List of image urls of the object.","title":"Image Other","items":{"type":"string"},"type":"array","nullable":true},"description":{"default":null,"description":"Description of the listing of the reference object","title":"Description","type":"string","nullable":true},"addressSrc":{"description":"Source of the address data value.","title":"Address Source","type":"string"},"houseTypeSrc":{"description":"Source of the dwelling type value.","title":"House Type Source","type":"string"},"buildYearSrc":{"description":"Source of the build year value.","title":"Build Year Source","type":"string"},"useSurfaceSrc":{"description":"Source of the use surface value.","title":"Use Surface Source","type":"string"},"parcelSurfaceSrc":{"description":"Source of the parcel surface value.","title":"Parcel Surface Source","type":"string"},"volumeSrc":{"default":null,"description":"Source of the volume value.","title":"Volume Source","type":"string","nullable":true},"energyLabelSrc":{"description":"Source of the energy label value.","title":"Energy Label Source","type":"string"},"dateTransactionSrc":{"description":"Source of the transaction date value.","title":"Date Transaction Source","type":"string"},"dateOnOfferSinceSrc":{"default":null,"description":"Source of the date on offer since value.","title":"Date On Offer Since Source","type":"string","nullable":true},"offeredPriceSrc":{"default":null,"description":"Source of the offered price value.","title":"Offered Price Source","type":"string","nullable":true},"statusSrc":{"description":"Source of the status value.","title":"Status Source","type":"string","nullable":true},"storageSpaceSrc":{"default":null,"description":"Source of the storage space value.","title":"Storage Space Source","type":"string","nullable":true},"exteriorSpaceSrc":{"default":null,"description":"Source of the exterior space value.","title":"Exterior Space Source","type":"string","nullable":true},"garageSrc":{"default":null,"description":"Source of the garage value.","title":"Garage Source","type":"string","nullable":true},"insulationSrc":{"default":null,"description":"Source of the insulation value.","title":"Insulation Source","type":"string","nullable":true},"imageFrontSrc":{"default":null,"description":"Source of the front view image url.","title":"Image Front Source","type":"string","nullable":true},"imageOtherSrc":{"default":null,"description":"Source of the other image urls.","title":"Image Other Source","type":"string","nullable":true},"descriptionSrc":{"default":null,"description":"Source of the description value.","title":"Description Source","type":"string","nullable":true},"multipleObjects":{"description":"Boolean indicating whether the address has multiple objects.","title":"Multiple Objects","type":"boolean"},"referenceTransactionApiCallPrice":{"default":null,"description":"The transaction price of this reference object at the time of the API call.","title":"Reference Transaction Api Call Price","type":"integer","nullable":true},"transactionPrice":{"default":null,"description":"The price of the transaction.","title":"Transaction Price","type":"integer","nullable":true},"compScore":{"description":"A weighted score on the comparability between the input house and the reference house, based on house type, build year, nett surface, parcel surface and energy label","title":"Similarity Score","type":"number"},"fillGrade":{"description":"A measure indicating the data coverage of all house characteristic data in percentage","title":"Filling Grade","type":"number"},"ownershipSituationFunda":{"default":null,"description":"Ownership situation as reported by Funda (e.g. freehold, leasehold).","title":"Ownership Situation Funda","type":"string","nullable":true},"ownershipSituationKadaster":{"default":null,"description":"Ownership situation as registered in the Kadaster (land registry).","title":"Ownership Situation Kadaster","type":"string","nullable":true},"dateTransport":{"description":"Date of transport","format":"date","title":"Date Transport","type":"string"},"dateSale":{"default":null,"description":"Date of sale","title":"Date Sale","format":"date","type":"string","nullable":true},"transactionPriceIndexed":{"description":"The price of the transaction, indexed to the valuation date.","title":"Transaction Price Indexed","type":"integer"},"transactionPriceIndexedDateTransport":{"default":null,"description":"The price of the transaction, indexed to the transport date.","title":"Transactions Price Indexed Date Transport","type":"integer","nullable":true},"transactionPriceIndexedDateSale":{"default":null,"description":"The price of the transaction, indexed to the sale date.","title":"Transaction Price Indexed Date Sale","type":"integer","nullable":true},"isMonument":{"default":false,"description":"Boolean indicating whether the house is a monument.","title":"Is Monument","type":"boolean","nullable":true},"nettUseSurface":{"default":null,"description":"Net usable surface area of the reference object in square meters.","title":"Nett Use Surface","type":"integer","nullable":true},"referenceScore":{"description":"Overall weighted reference score combining location and house details scores.","title":"Reference Score","type":"number"},"dateScore":{"description":"Score reflecting how recent the transaction date of the reference object is.","title":"Date Score","type":"number"},"locationScore":{"description":"Score reflecting the proximity and postal code similarity of the reference object.","title":"Location Score","type":"number"},"houseDetailsScore":{"description":"A weighted score on the comparability between the input house and the reference house, based on house type, build year, nett surface, parcel surface and energy label","title":"House Details Score","type":"number"}},"required":["index","bagId","streetName","postalCode","houseNumber","town","municipality","province","latitude","longitude","distance","houseType","buildYear","useSurface","useSurfaceBAG","parcelSurface","energyLabelIsRegistered","dateTransaction","priceClassLow","priceClassHigh","addressSrc","houseTypeSrc","buildYearSrc","useSurfaceSrc","parcelSurfaceSrc","energyLabelSrc","dateTransactionSrc","statusSrc","multipleObjects","compScore","fillGrade","dateTransport","transactionPriceIndexed","referenceScore","dateScore","locationScore","houseDetailsScore"],"title":"ReferenceResponse","type":"object"}}}}
```

## The ReferenceResponse object

```json
{"openapi":"3.0.3","info":{"title":"Matrixian API","version":"0.0.1"},"components":{"schemas":{"ReferenceResponse":{"properties":{"index":{"description":"Index number","title":"Index Nr","type":"integer"},"bagId":{"description":"Identification number according to the BAG.","title":"Number Id","type":"string"},"streetName":{"description":"Street name","title":"Street Name","type":"string"},"postalCode":{"description":"Postal code","title":"Postal Code","type":"string"},"houseNumber":{"description":"House number","title":"House Number","type":"integer"},"houseLetter":{"default":null,"description":"House letter","title":"House Letter","type":"string","nullable":true},"houseNumberExt":{"default":null,"description":"House number extension","title":"House Number Ext","type":"string","nullable":true},"town":{"description":"City","title":"City Name","type":"string"},"municipality":{"description":"Municipality","title":"Municipality Name","type":"string"},"province":{"description":"Province","title":"Province Name","type":"string"},"latitude":{"description":"Latitude","title":"Latitude","type":"number"},"longitude":{"description":"Longitude","title":"Longitude","type":"number"},"distance":{"description":"Distance of the reference object from the valuation object in meter.","title":"Distance","type":"number"},"houseType":{"description":"Dwelling type","title":"House Type","type":"string"},"buildYear":{"description":"Indication of the year in which the building will originally be delivered in, or is architecturally ready. Also known as construction year.","title":"Build Year","type":"integer"},"useSurface":{"description":"The usable surface area of a property object in square meters.","title":"Use Surface","type":"integer"},"useSurfaceBAG":{"description":"The usable surface area of a property object in square meters according to the BAG.","title":"Use Surface Bag","type":"integer","nullable":true},"parcelSurface":{"description":"The lot/parcel surface in m2.","title":"Parcel Surface","type":"integer"},"volume":{"default":null,"description":"Volume in cubic meters.","title":"Volume","type":"integer","nullable":true},"energyLabel":{"default":null,"description":"A label indicating how well the property object is insulated.","title":"Energy Label","type":"string","nullable":true},"energyLabelIsRegistered":{"description":"Boolean indicating whether the energy label has been registered.","title":"Energy Label Is Registered","type":"boolean","nullable":true},"energyLabelRegistrationValidUntil":{"default":null,"description":"Date until which the energy label is valid.","title":"Energy Label Registration Valid Until","format":"date","type":"string","nullable":true},"dateTransaction":{"description":"Transaction date","format":"date","title":"Date Transaction","type":"string"},"priceClassLow":{"description":"Lower bound of the price class based on indexed transaction price.","title":"Price Class Low","type":"integer"},"priceClassHigh":{"description":"Upper bound of the price class based on indexed transaction price.","title":"Price Class High","type":"integer"},"dateOnOfferSince":{"default":null,"description":"Date since when the reference object is offered on the market.","title":"Date On Offer Since","format":"date","type":"string","nullable":true},"offeredPrice":{"default":null,"description":"Price for which the listing of the reference object is on offer","title":"Offered Price","type":"integer","nullable":true},"status":{"default":null,"description":"Status of the listing of the reference object (online/offline)","title":"Status","type":"string","nullable":true},"storageSpace":{"default":null,"description":"Description of available storage space.","title":"Storage Space","type":"string","nullable":true},"exteriorSpace":{"default":null,"description":"Description of available exterior space (e.g. garden, balcony, terrace).","title":"Exterior Space","type":"string","nullable":true},"garage":{"default":null,"description":"Description of garage facilities.","title":"Garage","type":"string","nullable":true},"insulation":{"default":null,"description":"Description of insulation provisions.","title":"Insulation","type":"string","nullable":true},"imageFront":{"default":null,"description":"Url of the image of the front side of the house/object.","title":"Image Front","type":"string","nullable":true},"imageOther":{"default":null,"description":"List of image urls of the object.","title":"Image Other","items":{"type":"string"},"type":"array","nullable":true},"description":{"default":null,"description":"Description of the listing of the reference object","title":"Description","type":"string","nullable":true},"addressSrc":{"description":"Source of the address data value.","title":"Address Source","type":"string"},"houseTypeSrc":{"description":"Source of the dwelling type value.","title":"House Type Source","type":"string"},"buildYearSrc":{"description":"Source of the build year value.","title":"Build Year Source","type":"string"},"useSurfaceSrc":{"description":"Source of the use surface value.","title":"Use Surface Source","type":"string"},"parcelSurfaceSrc":{"description":"Source of the parcel surface value.","title":"Parcel Surface Source","type":"string"},"volumeSrc":{"default":null,"description":"Source of the volume value.","title":"Volume Source","type":"string","nullable":true},"energyLabelSrc":{"description":"Source of the energy label value.","title":"Energy Label Source","type":"string"},"dateTransactionSrc":{"description":"Source of the transaction date value.","title":"Date Transaction Source","type":"string"},"dateOnOfferSinceSrc":{"default":null,"description":"Source of the date on offer since value.","title":"Date On Offer Since Source","type":"string","nullable":true},"offeredPriceSrc":{"default":null,"description":"Source of the offered price value.","title":"Offered Price Source","type":"string","nullable":true},"statusSrc":{"description":"Source of the status value.","title":"Status Source","type":"string","nullable":true},"storageSpaceSrc":{"default":null,"description":"Source of the storage space value.","title":"Storage Space Source","type":"string","nullable":true},"exteriorSpaceSrc":{"default":null,"description":"Source of the exterior space value.","title":"Exterior Space Source","type":"string","nullable":true},"garageSrc":{"default":null,"description":"Source of the garage value.","title":"Garage Source","type":"string","nullable":true},"insulationSrc":{"default":null,"description":"Source of the insulation value.","title":"Insulation Source","type":"string","nullable":true},"imageFrontSrc":{"default":null,"description":"Source of the front view image url.","title":"Image Front Source","type":"string","nullable":true},"imageOtherSrc":{"default":null,"description":"Source of the other image urls.","title":"Image Other Source","type":"string","nullable":true},"descriptionSrc":{"default":null,"description":"Source of the description value.","title":"Description Source","type":"string","nullable":true},"multipleObjects":{"description":"Boolean indicating whether the address has multiple objects.","title":"Multiple Objects","type":"boolean"},"referenceTransactionApiCallPrice":{"default":null,"description":"The transaction price of this reference object at the time of the API call.","title":"Reference Transaction Api Call Price","type":"integer","nullable":true},"transactionPrice":{"default":null,"description":"The price of the transaction.","title":"Transaction Price","type":"integer","nullable":true},"compScore":{"description":"A weighted score on the comparability between the input house and the reference house, based on house type, build year, nett surface, parcel surface and energy label","title":"Similarity Score","type":"number"},"fillGrade":{"description":"A measure indicating the data coverage of all house characteristic data in percentage","title":"Filling Grade","type":"number"},"ownershipSituationFunda":{"default":null,"description":"Ownership situation as reported by Funda (e.g. freehold, leasehold).","title":"Ownership Situation Funda","type":"string","nullable":true},"ownershipSituationKadaster":{"default":null,"description":"Ownership situation as registered in the Kadaster (land registry).","title":"Ownership Situation Kadaster","type":"string","nullable":true},"dateTransport":{"description":"Date of transport","format":"date","title":"Date Transport","type":"string"},"dateSale":{"default":null,"description":"Date of sale","title":"Date Sale","format":"date","type":"string","nullable":true},"transactionPriceIndexed":{"description":"The price of the transaction, indexed to the valuation date.","title":"Transaction Price Indexed","type":"integer"},"transactionPriceIndexedDateTransport":{"default":null,"description":"The price of the transaction, indexed to the transport date.","title":"Transactions Price Indexed Date Transport","type":"integer","nullable":true},"transactionPriceIndexedDateSale":{"default":null,"description":"The price of the transaction, indexed to the sale date.","title":"Transaction Price Indexed Date Sale","type":"integer","nullable":true},"isMonument":{"default":false,"description":"Boolean indicating whether the house is a monument.","title":"Is Monument","type":"boolean","nullable":true},"nettUseSurface":{"default":null,"description":"Net usable surface area of the reference object in square meters.","title":"Nett Use Surface","type":"integer","nullable":true},"referenceScore":{"description":"Overall weighted reference score combining location and house details scores.","title":"Reference Score","type":"number"},"dateScore":{"description":"Score reflecting how recent the transaction date of the reference object is.","title":"Date Score","type":"number"},"locationScore":{"description":"Score reflecting the proximity and postal code similarity of the reference object.","title":"Location Score","type":"number"},"houseDetailsScore":{"description":"A weighted score on the comparability between the input house and the reference house, based on house type, build year, nett surface, parcel surface and energy label","title":"House Details Score","type":"number"}},"required":["index","bagId","streetName","postalCode","houseNumber","town","municipality","province","latitude","longitude","distance","houseType","buildYear","useSurface","useSurfaceBAG","parcelSurface","energyLabelIsRegistered","dateTransaction","priceClassLow","priceClassHigh","addressSrc","houseTypeSrc","buildYearSrc","useSurfaceSrc","parcelSurfaceSrc","energyLabelSrc","dateTransactionSrc","statusSrc","multipleObjects","compScore","fillGrade","dateTransport","transactionPriceIndexed","referenceScore","dateScore","locationScore","houseDetailsScore"],"title":"ReferenceResponse","type":"object"}}}}
```