---
title: "Market Valuation"
url: "https://real-estate-agency.apim.eu/apis/market-valuation/versions/3b18507e-d857-48a4-a3bc-b79b2eb2cfa4"
---

# Market Valuation

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Market Valuation","version":"1.0.0","description":"Produces an initial price indication for a property - based on comparable\nsales in the area, the local rent index and the property's own\ncharacteristics.\n\nThe result is an **indication**, not a formal valuation report prepared\nunder a certified appraisal standard. Every response therefore carries a\nrange and a note on the underlying data basis, so it stays clear in\nconversations with clients how reliable the figure is.\n","contact":{"name":"API Support - Real Estate Agency","email":"api-support@realestateagency.example"}},"servers":[{"url":"https://api.realestateagency.example/v1","description":"Production"},{"url":"https://sandbox.api.realestateagency.example/v1","description":"Sandbox"}],"tags":[{"name":"Valuations"},{"name":"Comparables"},{"name":"Rent Index"}],"security":[{"apiKey":[]}],"paths":{"/valuations":{"post":{"tags":["Valuations"],"summary":"Request a valuation","description":"Starts a valuation. Either for an existing property via `property_id`\nor for freeform input via `characteristics` - for example during an\ninitial consultation, before a property record exists.\n","operationId":"requestValuation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationRequest"},"examples":{"existingProperty":{"summary":"For an already-created property","value":{"property_id":"prop_8f2c1a","reason":"sale"}},"freeformInput":{"summary":"During an initial consultation, without a property record","value":{"reason":"initial_consultation","characteristics":{"type":"apartment","postal_code":"10001","living_area_sqm":86.5,"rooms":3,"year_built":1908,"condition":"well_maintained","finish_level":"upscale"}}}}}}},"responses":{"201":{"description":"Valuation created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationResult"},"example":{"id":"val_3e18","reason":"sale","market_value_eur":638000,"range_eur":{"low":602000,"high":674000},"price_per_sqm_eur":7376,"confidence":"medium","basis":{"comparables_count":23,"period_months":12,"radius_meters":1200},"created_at":"2026-08-20T09:52:00Z"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"422":{"description":"Data basis too thin for an indication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"insufficient_data","message":"Too few comparable sales are available for this location.","details":[{"field":"basis.comparables_count","reason":"below_minimum"}]}}}}}}},"/valuations/{valuationId}":{"parameters":[{"name":"valuationId","in":"path","required":true,"schema":{"type":"string","example":"val_3e18"}}],"get":{"tags":["Valuations"],"summary":"Retrieve a valuation","operationId":"getValuation","responses":{"200":{"description":"Valuation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationResult"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/comparables":{"get":{"tags":["Comparables"],"summary":"List comparable sales","description":"Anonymized closed sales from the surrounding area. Addresses are\nrounded to the street level so no individual sale can be traced back.\n","operationId":"listComparables","parameters":[{"name":"postal_code","in":"query","required":true,"schema":{"type":"string","example":"10001"}},{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["apartment","house","land","commercial"]}},{"name":"living_area_sqm","in":"query","description":"Reference size; matches are searched within a ±20 percent corridor.","schema":{"type":"number","format":"float","example":86.5}},{"name":"period_months","in":"query","schema":{"type":"integer","minimum":3,"maximum":36,"default":12}}],"responses":{"200":{"description":"Comparable sales","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Comparable"}},"stats":{"$ref":"#/components/schemas/Metrics"}}}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"}}}},"/rent-index":{"get":{"tags":["Rent Index"],"summary":"Get rent index values","description":"Typical comparable rent for the area, based on aggregated market rent data.","operationId":"getRentIndex","parameters":[{"name":"postal_code","in":"query","required":true,"schema":{"type":"string","example":"10001"}},{"name":"living_area_sqm","in":"query","required":true,"schema":{"type":"number","format":"float","example":86.5}},{"name":"year_built","in":"query","schema":{"type":"integer","example":1908}}],"responses":{"200":{"description":"Rent index values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentIndexValue"},"example":{"city":"Springfield","as_of":"2025-01-01","net_rent_per_sqm_eur":{"low":9.4,"average":11.8,"high":14.6},"range_note":"Values apply to a typical residential location without adjustments."}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"apikey","description":"Every call carries an API key in the `apikey` header. You generate the\nkey in the Real Estate portal under \"My Apps\"; it's shown exactly once.\n\nEach key has the scopes it's allowed to use attached to it. If one is\nmissing, the API responds with `403` and `code: \"scope_missing\"`; the\nmissing scope is in `details[].field`.\n"}},"responses":{"NotAuthenticated":{"description":"Key is missing, revoked or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"The request doesn't match the schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit reached","headers":{"Retry-After":{"schema":{"type":"integer","example":12}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Page":{"type":"object","description":"Cursor-based pagination.","properties":{"count":{"type":"integer","example":25},"total":{"type":"integer","example":138},"next_cursor":{"type":"string","nullable":true,"example":"eyJzIjoyNX0"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","example":"basis.comparables_count"},"reason":{"type":"string","example":"missing"}}},"Error":{"type":"object","description":"Uniform error format across all Real Estate Agency APIs.","required":["code","message"],"properties":{"code":{"type":"string","example":"validation_failed"},"message":{"type":"string","example":"Too few comparable sales are available for this location."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"Reason":{"type":"string","enum":["initial_consultation","sale","rental","financing","inheritance"],"example":"sale"},"Characteristics":{"type":"object","description":"Freeform property description, used when no property record exists.","required":["type","postal_code","living_area_sqm"],"properties":{"type":{"type":"string","enum":["apartment","house","land","commercial"]},"postal_code":{"type":"string","pattern":"^[0-9]{5}$","example":"10001"},"living_area_sqm":{"type":"number","format":"float","example":86.5},"lot_size_sqm":{"type":"number","format":"float","example":412},"rooms":{"type":"number","format":"float","example":3},"year_built":{"type":"integer","example":1908},"condition":{"type":"string","enum":["needs_renovation","well_maintained","modernized","like_new"]},"finish_level":{"type":"string","enum":["basic","standard","upscale","luxury"]},"balcony":{"type":"boolean","example":true},"elevator":{"type":"boolean","example":false},"parking_space":{"type":"boolean","example":false}}},"ValuationRequest":{"type":"object","required":["reason"],"description":"Exactly one of `property_id` or `characteristics` must be set.","properties":{"property_id":{"type":"string","example":"prop_8f2c1a"},"reason":{"$ref":"#/components/schemas/Reason"},"characteristics":{"$ref":"#/components/schemas/Characteristics"}}},"Range":{"type":"object","properties":{"low":{"type":"integer","example":602000},"high":{"type":"integer","example":674000}}},"ValuationBasis":{"type":"object","description":"What the indication was derived from.","properties":{"comparables_count":{"type":"integer","example":23},"period_months":{"type":"integer","example":12},"radius_meters":{"type":"integer","example":1200}}},"ValuationResult":{"type":"object","properties":{"id":{"type":"string","example":"val_3e18"},"property_id":{"type":"string","nullable":true,"example":"prop_8f2c1a"},"reason":{"$ref":"#/components/schemas/Reason"},"market_value_eur":{"type":"integer","example":638000},"range_eur":{"$ref":"#/components/schemas/Range"},"price_per_sqm_eur":{"type":"integer","example":7376},"confidence":{"type":"string","description":"How reliable the indication is.","enum":["low","medium","high"]},"basis":{"$ref":"#/components/schemas/ValuationBasis"},"created_at":{"type":"string","format":"date-time","example":"2026-08-20T09:52:00Z"}}},"Comparable":{"type":"object","properties":{"street_rounded":{"type":"string","example":"Elm Street"},"living_area_sqm":{"type":"number","format":"float","example":82},"rooms":{"type":"number","format":"float","example":3},"year_built":{"type":"integer","example":1911},"sale_price_eur":{"type":"integer","example":615000},"price_per_sqm_eur":{"type":"integer","example":7500},"sale_month":{"type":"string","example":"2026-03"}}},"Metrics":{"type":"object","properties":{"count":{"type":"integer","example":23},"median_price_per_sqm_eur":{"type":"integer","example":7410},"lower_quartile_price_per_sqm_eur":{"type":"integer","example":6980},"upper_quartile_price_per_sqm_eur":{"type":"integer","example":7860}}},"RentIndexValue":{"type":"object","properties":{"city":{"type":"string","example":"Springfield"},"as_of":{"type":"string","format":"date","example":"2025-01-01"},"net_rent_per_sqm_eur":{"type":"object","properties":{"low":{"type":"number","format":"float","example":9.4},"average":{"type":"number","format":"float","example":11.8},"high":{"type":"number","format":"float","example":14.6}}},"range_note":{"type":"string","example":"Values apply to a typical residential location without adjustments."}}}}}}
```