{ "openapi": "3.1.0", "info": { "title": "Stream Estate API", "description": "# Getting started\n## Dates - Timezones\nAll date and time formats are in UTC. Always convert any DateTime instance to UTC.\n\n## Rate Limiting\nThe API implements rate limiting to ensure fair usage and protect against abuse.\n\n- 500 requests per minute per account (API key), across all IPs. Unauthenticated requests are limited per IP address.\n\nWhen the rate limit is exceeded, the API returns a `429 Too Many Requests` response with headers:\n- `X-RateLimit-Retry-After`: Unix timestamp indicating when the limit resets.\n- `X-RateLimit-Limit`: The maximum number of requests allowed in the current window.", "version": "2.0.0" }, "servers": [ { "url": "https://api-v2.stream.estate", "description": "" } ], "paths": { "/account/api-usage": { "get": { "operationId": "getApiUsage", "tags": [ "Account" ], "responses": { "200": { "description": "ApiUsage resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ApiUsage.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiUsage" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get billable API usage analytics", "description": "Returns billable API usage aggregates for the authenticated API customer.", "parameters": [ { "name": "startDate", "in": "query", "description": "Start of the reported period, included. A bare date such as 2026-08-01 means the start of that day in UTC. Cannot be in the future. Defaults to 30 days before the end.", "required": false, "deprecated": false, "schema": { "type": "string", "format": "date-time", "example": "2026-01-15T00:00:00Z", "examples": [ "2026-01-15T00:00:00Z" ] }, "style": "form", "explode": true }, { "name": "endDate", "in": "query", "description": "End of the reported period, excluded. A bare date such as 2026-08-31 covers that whole day in UTC. Never later than now. Defaults to now.", "required": false, "deprecated": false, "schema": { "type": "string", "format": "date-time", "example": "2026-02-15T00:00:00Z", "examples": [ "2026-02-15T00:00:00Z" ] }, "style": "form", "explode": true }, { "name": "apiKeyId", "in": "query", "description": "Filter by API key id owned by authenticated user.", "required": false, "deprecated": false, "schema": { "type": "string", "format": "uuid", "example": "7c1f0e8a-2b6d-4f3a-9e1c-5a8b2d4f6c10", "examples": [ "7c1f0e8a-2b6d-4f3a-9e1c-5a8b2d4f6c10" ] }, "style": "form", "explode": true }, { "name": "granularity", "in": "query", "description": "Time grouping granularity.", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "YEAR", "MONTH", "DAY" ], "default": "DAY" }, "style": "form", "explode": true }, { "name": "groupBy", "in": "query", "description": "Split each time series bucket by this dimension. Rows then carry the matching group fields.", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "API_KEY", "ROUTE", "CHANNEL" ], "example": "API_KEY", "examples": [ "API_KEY" ] }, "style": "form", "explode": true }, { "name": "channel", "in": "query", "description": "Only count calls issued through this channel.", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "DIRECT", "MCP" ], "example": "MCP", "examples": [ "MCP" ] }, "style": "form", "explode": true } ] } }, "/account/event-destinations": { "get": { "operationId": "listEventDestinations", "tags": [ "Account" ], "responses": { "200": { "description": "EventDestination collection", "content": { "application/vnd.api+json": { "schema": { "description": "EventDestination.jsonapi collection.", "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchema" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "EventDestination", "examples": [ "EventDestination" ] }, "attributes": { "type": "object", "properties": { "destinationType": { "description": "Destination type. Optional when your account has a single enabled channel, in which case it is inferred.", "example": "WEBHOOK", "type": "string", "enum": [ "WEBHOOK", "EMAIL" ], "nullable": true, "examples": [ "WEBHOOK" ] }, "url": { "description": "Webhook URL (required when type=webhook). Must be HTTPS. See the alertEvent webhook for the payload, signature and retry behaviour.", "example": "https://your-server.com/webhooks/stream", "type": [ "string", "null" ], "examples": [ "https://your-server.com/webhooks/stream" ] }, "email": { "format": "email", "description": "Email address (required when type=email)", "externalDocs": { "url": "https://schema.org/email" }, "example": "alerts@your-domain.com", "type": [ "string", "null" ], "examples": [ "alerts@your-domain.com" ] }, "isDefault": { "description": "Whether this is your account default destination. Pass true to promote as default; the previous default is automatically demoted. Your first destination becomes the default automatically.", "default": false, "example": true, "type": "boolean", "examples": [ true ] }, "status": { "readOnly": true, "description": "Circuit breaker status: active or suspended", "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "SUSPENDED" ], "nullable": false }, "signingKey": { "readOnly": true, "description": "HMAC signing key for webhook deliveries. Returned a single time: on the response of the POST that creates the first webhook destination of your account (it is not returned for later destinations and cannot be retrieved again — store it securely). Rotate it from your dashboard.", "example": "whsec_abc123...", "type": [ "string", "null" ], "examples": [ "whsec_abc123..." ] }, "signingKeyHint": { "readOnly": true, "description": "A short fingerprint of the signing key returned above (the first 8 hex characters of its sha256). Keep it: it is what identifies your active key later, and your dashboard shows the same value.", "example": "b75b1473", "type": [ "string", "null" ], "examples": [ "b75b1473" ] }, "_id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } } } }, "required": [ "type", "id" ] } } } } ] } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventDestination" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "List event destinations", "description": "List event destinations", "parameters": [ { "name": "page", "in": "query", "description": "The collection page number", "required": false, "deprecated": false, "schema": { "type": "integer", "default": 1 }, "style": "form", "explode": true } ] }, "post": { "operationId": "createEventDestination", "tags": [ "Account" ], "responses": { "201": { "description": "EventDestination resource created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EventDestination.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EventDestination" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "An error occurred", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} } }, "summary": "Create an event destination", "description": "Create an event destination", "parameters": [], "requestBody": { "description": "The new EventDestination resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EventDestination.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EventDestination" } } }, "required": true } } }, "/account/event-destinations/{id}": { "get": { "operationId": "getEventDestination", "tags": [ "Account" ], "responses": { "200": { "description": "EventDestination resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EventDestination.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EventDestination" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get an event destination", "description": "Get an event destination", "parameters": [ { "name": "id", "in": "path", "description": "EventDestination identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "delete": { "operationId": "deleteEventDestination", "tags": [ "Account" ], "responses": { "204": { "description": "EventDestination resource deleted" }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Delete an event destination", "description": "Delete an event destination", "parameters": [ { "name": "id", "in": "path", "description": "EventDestination identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/alerts": { "get": { "operationId": "listAlerts", "tags": [ "Alert" ], "responses": { "200": { "description": "Alert collection", "content": { "application/vnd.api+json": { "schema": { "description": "Alert.jsonapi collection.", "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchema" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "Alert", "examples": [ "Alert" ] }, "attributes": { "type": "object", "properties": { "name": { "description": "Alert name", "example": "2-bedroom apartments in Paris", "type": [ "string", "null" ], "examples": [ "2-bedroom apartments in Paris" ] }, "enabled": { "description": "Whether the alert is enabled. A disabled alert stops matching new listings and sends nothing, including notifications already queued for it.", "default": true, "type": "boolean" }, "criteria": { "description": "Search criteria tree (nested and/or groups with sets of property filters). Same shape as the POST /properties criteria. Absent when the alert has no criteria, which means it matches every property.", "example": { "and": [ { "property": { "type": { "in": [ "FLAT", "HOUSE" ] }, "transaction": { "type": "SELL" }, "pricing": { "displayed": { "gte": 200000, "lte": 450000 } }, "unit": { "bedrooms": { "gte": 2 } } } }, { "or": [ { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } } } }, { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "69123" ] } } } } ] } ] }, "type": "object", "additionalProperties": true, "examples": [ { "and": [ { "property": { "type": { "in": [ "FLAT", "HOUSE" ] }, "transaction": { "type": "SELL" }, "pricing": { "displayed": { "gte": 200000, "lte": 450000 } }, "unit": { "bedrooms": { "gte": 2 } } } }, { "or": [ { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } } } }, { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "69123" ] } } } } ] } ] } ] }, "notificationConfig": { "description": "Notification configuration. Omit it and the alert never notifies: it is what selects the event types you receive.", "anyOf": [ { "$ref": "#/components/schemas/AlertNotificationConfig" }, { "type": "null" } ] }, "signingKey": { "readOnly": true, "description": "Webhook signing key. Present only when this request created the first webhook destination of your account; store it securely, it cannot be retrieved again", "example": "whsec_abc123...", "type": [ "string", "null" ], "examples": [ "whsec_abc123..." ] }, "signingKeyHint": { "readOnly": true, "description": "A short fingerprint of the signing key returned above (the first 8 hex characters of its sha256). Keep it: it is what identifies your active key later, and your dashboard shows the same value.", "example": "b75b1473", "type": [ "string", "null" ], "examples": [ "b75b1473" ] }, "_id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } } }, "relationships": { "type": "object", "properties": { "eventDestination": { "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "example": "EventDestination", "examples": [ "EventDestination" ] }, "id": { "type": "string", "format": "iri-reference", "example": "/eventDestinations/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/eventDestinations/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } ], "example": { "type": "EventDestination", "id": "/eventDestinations/3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "examples": [ { "type": "EventDestination", "id": "/eventDestinations/3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } } } } } }, "required": [ "type", "id" ] } }, "included": { "description": "Related resources requested via the \"include\" query parameter.", "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/EventDestination.jsonapi" } ] }, "readOnly": true, "externalDocs": { "url": "https://jsonapi.org/format/#fetching-includes" } } } } ] } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "List alerts", "description": "List alerts", "parameters": [ { "name": "page", "in": "query", "description": "The collection page number", "required": false, "deprecated": false, "schema": { "type": "integer", "default": 1 }, "style": "form", "explode": true } ] }, "post": { "operationId": "createAlert", "tags": [ "Alert" ], "responses": { "201": { "description": "Alert resource created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Alert.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "An error occurred", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} } }, "summary": "Create alert", "description": "Create a new alert. The criteria tree combines and/or groups with sets of property filters.", "parameters": [], "requestBody": { "description": "The new Alert resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert.AlertRequestInput" }, "examples": { "defaultDestination": { "summary": "Use the account default destination", "description": "Omit notificationDestination entirely: alerts are delivered to the default event destination configured on your account. Returns 422 if you have no default destination yet.", "value": { "name": "2-bedroom rentals in Paris under €2,000/month", "enabled": true, "criteria": { "property": { "type": { "in": [ "FLAT" ] }, "transaction": { "type": "RENT" }, "pricing": { "displayed": { "lte": 2000 } }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } }, "unit": { "bedrooms": { "gte": 2 } } } }, "notificationConfig": { "rules": [ { "eventType": "NEW_MATCH" }, { "eventType": "PRICE_CHANGE", "variationPercent": [ { "lte": -5 }, { "gte": 5 } ] } ] } } }, "inlineWebhook": { "summary": "Create a webhook destination on the fly", "description": "Provide webhookUrl to create (or reuse) a webhook event destination and link it to the alert. The signing key is returned once, only when this creates the first webhook destination of your account.", "value": { "name": "2-bedroom rentals in Paris under €2,000/month", "enabled": true, "criteria": { "property": { "type": { "in": [ "FLAT" ] }, "transaction": { "type": "RENT" }, "pricing": { "displayed": { "lte": 2000 } }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } }, "unit": { "bedrooms": { "gte": 2 } } } }, "notificationConfig": { "rules": [ { "eventType": "NEW_MATCH" }, { "eventType": "PRICE_CHANGE", "variationPercent": [ { "lte": -5 }, { "gte": 5 } ] } ] }, "notificationDestination": { "webhookUrl": "https://your-server.com/webhooks/stream" } } }, "linkExisting": { "summary": "Link an existing event destination", "description": "Provide the id of an event destination you already created, to deliver this alert to it.", "value": { "name": "2-bedroom rentals in Paris under €2,000/month", "enabled": true, "criteria": { "property": { "type": { "in": [ "FLAT" ] }, "transaction": { "type": "RENT" }, "pricing": { "displayed": { "lte": 2000 } }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } }, "unit": { "bedrooms": { "gte": 2 } } } }, "notificationConfig": { "rules": [ { "eventType": "NEW_MATCH" }, { "eventType": "PRICE_CHANGE", "variationPercent": [ { "lte": -5 }, { "gte": 5 } ] } ] }, "notificationDestination": { "eventDestination": "/account/event-destinations/01926b8a-5d2c-7b1e-8a4f-9c3d2e1b7a05" } } } } } }, "required": false } } }, "/alerts/{id}": { "get": { "operationId": "getAlert", "tags": [ "Alert" ], "responses": { "200": { "description": "Alert resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Alert.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get an alert", "description": "Get an alert", "parameters": [ { "name": "id", "in": "path", "description": "Alert identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] }, "put": { "operationId": "updateAlert", "tags": [ "Alert" ], "responses": { "200": { "description": "Alert resource updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Alert.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "An error occurred", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} } }, "summary": "Update alert", "description": "Update an existing alert. Only the fields present in the body change: omit a field to keep its stored value, or send a nullable field as null to clear it. Same criteria tree shape as POST. Any update that would leave the alert enabled with no destination of its own returns 422 when your account has no default destination, whether or not the update is what enabled it. Sending notificationDestination as null returns 422 whenever your account has no default destination, for a disabled alert too.", "parameters": [ { "name": "id", "in": "path", "description": "Alert identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "requestBody": { "description": "The updated Alert resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert.AlertRequestInput" }, "examples": { "defaultDestination": { "summary": "Keep the current destination", "description": "Omit notificationDestination entirely and the alert keeps the destination it is already delivered to.", "value": { "name": "2-bedroom rentals in Paris under €2,000/month", "enabled": true, "criteria": { "property": { "type": { "in": [ "FLAT" ] }, "transaction": { "type": "RENT" }, "pricing": { "displayed": { "lte": 2000 } }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } }, "unit": { "bedrooms": { "gte": 2 } } } }, "notificationConfig": { "rules": [ { "eventType": "NEW_MATCH" }, { "eventType": "PRICE_CHANGE", "variationPercent": [ { "lte": -5 }, { "gte": 5 } ] } ] } } }, "inlineWebhook": { "summary": "Create a webhook destination on the fly", "description": "Provide webhookUrl to create (or reuse) a webhook event destination and link it to the alert. The signing key is returned once, only when this creates the first webhook destination of your account.", "value": { "name": "2-bedroom rentals in Paris under €2,000/month", "enabled": true, "criteria": { "property": { "type": { "in": [ "FLAT" ] }, "transaction": { "type": "RENT" }, "pricing": { "displayed": { "lte": 2000 } }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } }, "unit": { "bedrooms": { "gte": 2 } } } }, "notificationConfig": { "rules": [ { "eventType": "NEW_MATCH" }, { "eventType": "PRICE_CHANGE", "variationPercent": [ { "lte": -5 }, { "gte": 5 } ] } ] }, "notificationDestination": { "webhookUrl": "https://your-server.com/webhooks/stream" } } }, "inlineEmail": { "summary": "Create an email destination on the fly", "description": "Provide email to create (or reuse) an email event destination and link it to the alert.", "value": { "name": "2-bedroom rentals in Paris under €2,000/month", "enabled": true, "criteria": { "property": { "type": { "in": [ "FLAT" ] }, "transaction": { "type": "RENT" }, "pricing": { "displayed": { "lte": 2000 } }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } }, "unit": { "bedrooms": { "gte": 2 } } } }, "notificationConfig": { "rules": [ { "eventType": "NEW_MATCH" }, { "eventType": "PRICE_CHANGE", "variationPercent": [ { "lte": -5 }, { "gte": 5 } ] } ] }, "notificationDestination": { "email": "alerts@your-domain.com" } } }, "linkExisting": { "summary": "Link an existing event destination", "description": "Provide the id of an event destination you already created, to deliver this alert to it.", "value": { "name": "2-bedroom rentals in Paris under €2,000/month", "enabled": true, "criteria": { "property": { "type": { "in": [ "FLAT" ] }, "transaction": { "type": "RENT" }, "pricing": { "displayed": { "lte": 2000 } }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } }, "unit": { "bedrooms": { "gte": 2 } } } }, "notificationConfig": { "rules": [ { "eventType": "NEW_MATCH" }, { "eventType": "PRICE_CHANGE", "variationPercent": [ { "lte": -5 }, { "gte": 5 } ] } ] }, "notificationDestination": { "eventDestination": "/account/event-destinations/01926b8a-5d2c-7b1e-8a4f-9c3d2e1b7a05" } } } } } }, "required": false } }, "delete": { "operationId": "deleteAlert", "tags": [ "Alert" ], "responses": { "204": { "description": "Alert resource deleted" }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Delete an alert", "description": "Delete an alert", "parameters": [ { "name": "id", "in": "path", "description": "Alert identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/alerts/{alertId}/events": { "get": { "operationId": "listAlertEvents", "tags": [ "Alert" ], "responses": { "200": { "description": "AlertEvent collection", "content": { "application/vnd.api+json": { "schema": { "description": "AlertEvent.jsonapi collection.", "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchema" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "AlertEvent", "examples": [ "AlertEvent" ] }, "attributes": { "type": "object", "properties": { "eventType": { "description": "Event type that triggered notification", "example": "PRICE_CHANGE", "type": "string", "enum": [ "NEW_MATCH", "PRICE_CHANGE", "OTHER_CHANGE", "EXPIRED", "REACTIVATED" ], "nullable": false, "examples": [ "PRICE_CHANGE" ] }, "scope": { "description": "What this event is about, matching the scope of the rule that produced it. PROPERTY: the property did something. LISTING: one advert of it did. Both name a listing, so this is the only field that tells them apart.", "default": "PROPERTY", "example": "PROPERTY", "type": "string", "enum": [ "PROPERTY", "LISTING" ], "nullable": false, "examples": [ "PROPERTY" ] }, "notifiedAt": { "description": "Date this event was processed for delivery, null while it is still queued. A processed event has no notification when the alert is no longer active, or when no delivery destination could be resolved. Events matching none of the alert notification rules are never listed here.", "example": "2026-07-28T09:15:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-07-28T09:15:00+00:00" ] }, "_id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } } }, "relationships": { "type": "object", "properties": { "alert": { "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "example": "Alert", "examples": [ "Alert" ] }, "id": { "type": "string", "format": "iri-reference", "example": "/alerts/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/alerts/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } ], "example": { "type": "Alert", "id": "/alerts/3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "examples": [ { "type": "Alert", "id": "/alerts/3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } } }, "property": { "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "example": "Property", "examples": [ "Property" ] }, "id": { "type": "string", "format": "iri-reference", "example": "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } ], "example": { "type": "Property", "id": "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "examples": [ { "type": "Property", "id": "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } } } } } }, "required": [ "type", "id" ] } }, "included": { "description": "Related resources requested via the \"include\" query parameter.", "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Alert.jsonapi" }, { "$ref": "#/components/schemas/PropertySearchResult.jsonapi" } ] }, "readOnly": true, "externalDocs": { "url": "https://jsonapi.org/format/#fetching-includes" } } } } ] } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AlertEvent" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "List alert events", "description": "List alert events", "parameters": [ { "name": "alertId", "in": "path", "description": "Resource identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "name": "page", "in": "query", "description": "The collection page number", "required": false, "deprecated": false, "schema": { "type": "integer", "default": 1 }, "style": "form", "explode": true }, { "name": "order[createdAt]", "in": "query", "description": "Sort events by creation date. Accepts asc or desc.", "required": false, "deprecated": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] }, "style": "form", "explode": false }, { "name": "createdAt[before]", "in": "query", "description": "Only events created on or before this date.", "required": false, "deprecated": false, "schema": { "type": "string" }, "style": "form", "explode": false, "example": "2026-01-31" }, { "name": "createdAt[strictly_before]", "in": "query", "description": "Only events created strictly before this date.", "required": false, "deprecated": false, "schema": { "type": "string" }, "style": "form", "explode": false, "example": "2026-01-31" }, { "name": "createdAt[after]", "in": "query", "description": "Only events created on or after this date.", "required": false, "deprecated": false, "schema": { "type": "string" }, "style": "form", "explode": false, "example": "2026-01-01" }, { "name": "createdAt[strictly_after]", "in": "query", "description": "Only events created strictly after this date.", "required": false, "deprecated": false, "schema": { "type": "string" }, "style": "form", "explode": false, "example": "2026-01-01" } ] } }, "/alerts/{alertId}/events/{id}": { "get": { "operationId": "getAlertEvent", "tags": [ "Alert" ], "responses": { "200": { "description": "AlertEvent resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AlertEvent.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/AlertEvent" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get an alert event", "description": "Get an alert event", "parameters": [ { "name": "alertId", "in": "path", "description": "Resource identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "name": "id", "in": "path", "description": "Event identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/alerts/forecast": { "post": { "operationId": "forecastAlert", "tags": [ "Alert" ], "responses": { "200": { "description": "The estimate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertForecast" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "The criteria are invalid, or use a filter alerts do not support", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} }, "503": { "description": "The estimate could not be computed; retry later" } }, "summary": "Estimate the volume of an alert", "description": "Estimates the notifications an alert with these criteria would send per day and per hour once running, from the matching properties that arrived over the last 30 days. A newly saved alert also notifies, in its first days, the matching properties already on the market; this estimate leaves them out. A rough figure that counts new properties only. Not billed.", "parameters": [], "requestBody": { "description": "The criteria of the alert to estimate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertForecast.AlertForecastInput" }, "examples": { "default": { "summary": "Rental flats in Paris under €2,000/month", "value": { "criteria": { "property": { "type": { "in": [ "FLAT" ] }, "transaction": { "type": "RENT" }, "pricing": { "displayed": { "lte": 2000 } }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } } } } } } } } }, "required": false } } }, "/analytics/listings": { "get": { "operationId": "getListingAnalytics", "tags": [ "Analytics" ], "responses": { "200": { "description": "ListingAnalytics resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListingAnalytics.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ListingAnalytics" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get aggregated listing warehouse analytics", "description": "Query immutable market warehouse data with filters, grouping, time buckets, and aggregate metrics.", "parameters": [ { "name": "property_type", "in": "query", "description": "Property type filter (multi-value).", "required": false, "deprecated": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "FLAT", "HOUSE", "BUILDING", "PARKING", "OFFICE", "LAND", "SHOP", "COMMERCIAL_PREMISES" ] } }, "style": "form", "explode": true }, { "name": "transaction_type", "in": "query", "description": "Transaction type filter.", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "SELL", "RENT" ] }, "style": "form", "explode": true }, { "name": "city_id", "in": "query", "description": "City IDs filter (multi-value).", "required": false, "deprecated": false, "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 75056 ], "examples": [ [ 75056 ] ] }, "style": "form", "explode": true }, { "name": "district_id", "in": "query", "description": "District IDs filter (multi-value).", "required": false, "deprecated": false, "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 75118 ], "examples": [ [ 75118 ] ] }, "style": "form", "explode": true }, { "name": "neighborhood_id", "in": "query", "description": "Neighborhood IDs filter (multi-value).", "required": false, "deprecated": false, "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 750180 ], "examples": [ [ 750180 ] ] }, "style": "form", "explode": true }, { "name": "event_type", "in": "query", "description": "Warehouse event type filter (multi-value).", "required": false, "deprecated": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "CREATED", "UPDATED", "EXPIRED", "REACTIVATED" ] } }, "style": "form", "explode": true }, { "name": "event_at_from", "in": "query", "description": "Inclusive start date for event_at.", "required": false, "deprecated": false, "schema": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z", "examples": [ "2026-01-01T00:00:00Z" ] }, "style": "form", "explode": true }, { "name": "event_at_to", "in": "query", "description": "Inclusive end date for event_at.", "required": false, "deprecated": false, "schema": { "type": "string", "format": "date-time", "example": "2026-03-31T23:59:59Z", "examples": [ "2026-03-31T23:59:59Z" ] }, "style": "form", "explode": true }, { "name": "price_min", "in": "query", "description": "Minimum displayed price filter.", "required": false, "deprecated": false, "schema": { "type": "number", "example": 200000, "examples": [ 200000 ] }, "style": "form", "explode": true }, { "name": "price_max", "in": "query", "description": "Maximum displayed price filter.", "required": false, "deprecated": false, "schema": { "type": "number", "example": 750000, "examples": [ 750000 ] }, "style": "form", "explode": true }, { "name": "area_min", "in": "query", "description": "Minimum displayed area filter.", "required": false, "deprecated": false, "schema": { "type": "number", "example": 30, "examples": [ 30 ] }, "style": "form", "explode": true }, { "name": "area_max", "in": "query", "description": "Maximum displayed area filter.", "required": false, "deprecated": false, "schema": { "type": "number", "example": 120, "examples": [ 120 ] }, "style": "form", "explode": true }, { "name": "rooms_min", "in": "query", "description": "Minimum rooms filter.", "required": false, "deprecated": false, "schema": { "type": "integer", "example": 2, "examples": [ 2 ] }, "style": "form", "explode": true }, { "name": "rooms_max", "in": "query", "description": "Maximum rooms filter.", "required": false, "deprecated": false, "schema": { "type": "integer", "example": 5, "examples": [ 5 ] }, "style": "form", "explode": true }, { "name": "bedrooms_min", "in": "query", "description": "Minimum bedrooms filter.", "required": false, "deprecated": false, "schema": { "type": "integer", "example": 1, "examples": [ 1 ] }, "style": "form", "explode": true }, { "name": "bedrooms_max", "in": "query", "description": "Maximum bedrooms filter.", "required": false, "deprecated": false, "schema": { "type": "integer", "example": 3, "examples": [ 3 ] }, "style": "form", "explode": true }, { "name": "dpe_energy_rating", "in": "query", "description": "DPE energy rating filter (multi-value).", "required": false, "deprecated": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G" ] } }, "style": "form", "explode": true }, { "name": "publisher_type", "in": "query", "description": "Publisher type filter (multi-value).", "required": false, "deprecated": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "PRIVATE_INDIVIDUAL", "REAL_ESTATE_AGENCY", "COMMERCIAL_AGENT", "MANDATED_AGENT" ] } }, "style": "form", "explode": true }, { "name": "lat_min", "in": "query", "description": "Bounding box minimum latitude.", "required": false, "deprecated": false, "schema": { "type": "number", "example": 48.815, "examples": [ 48.815 ] }, "style": "form", "explode": true }, { "name": "lat_max", "in": "query", "description": "Bounding box maximum latitude.", "required": false, "deprecated": false, "schema": { "type": "number", "example": 48.902, "examples": [ 48.902 ] }, "style": "form", "explode": true }, { "name": "lng_min", "in": "query", "description": "Bounding box minimum longitude.", "required": false, "deprecated": false, "schema": { "type": "number", "example": 2.224, "examples": [ 2.224 ] }, "style": "form", "explode": true }, { "name": "lng_max", "in": "query", "description": "Bounding box maximum longitude.", "required": false, "deprecated": false, "schema": { "type": "number", "example": 2.47, "examples": [ 2.47 ] }, "style": "form", "explode": true }, { "name": "group_by", "in": "query", "description": "Categorical columns to group by (max 10 fields). Allowed fields: property_type, transaction_type, event_type, city_id, district_id, neighborhood_id, dpe_energy_rating, dpe_ghg_rating, publisher_type, price_currency, transaction_status, sale_type, mandate_type, condition, location_accuracy, heating_system, energy_carrier, source_id.", "required": false, "deprecated": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "city_id", "property_type" ], "examples": [ [ "city_id", "property_type" ] ] }, "style": "form", "explode": true }, { "name": "time_bucket", "in": "query", "description": "Optional event_at time bucket.", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ], "default": "day" }, "style": "form", "explode": true }, { "name": "metrics", "in": "query", "description": "Aggregation metrics (max 20 metrics). Available functions: count, avg, median, min, max, percentile. Available fields for avg|median|min|max|percentile: price, price_displayed, price_per_sqm, area, area_displayed, rooms, bedrooms, days_between_events. Format: count | : | percentile::

(0 < p <= 100).", "required": false, "deprecated": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "count", "avg:price", "percentile:price_per_sqm:90" ], "examples": [ [ "count", "avg:price", "percentile:price_per_sqm:90" ] ] }, "style": "form", "explode": true } ] } }, "/event-notifications": { "get": { "operationId": "listEventNotifications", "tags": [ "EventNotification" ], "responses": { "200": { "description": "EventNotification collection", "content": { "application/vnd.api+json": { "schema": { "description": "EventNotification.jsonapi collection.", "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchema" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "EventNotification", "examples": [ "EventNotification" ] }, "attributes": { "type": "object", "properties": { "channel": { "type": "string", "description": "Delivery channel used for this notification.", "example": "WEBHOOK", "enum": [ "EMAIL", "WEBHOOK" ], "nullable": false, "examples": [ "WEBHOOK" ] }, "destinationAddress": { "readOnly": true, "description": "Destination URL or address the notification was sent to.", "example": "https://your-server.com/webhooks/stream", "type": "string", "examples": [ "https://your-server.com/webhooks/stream" ] }, "status": { "type": "string", "description": "Current delivery status.", "example": "DELIVERED", "enum": [ "PENDING", "DELIVERED", "FAILED", "SUSPENDED", "SKIPPED" ], "nullable": false, "examples": [ "DELIVERED" ] }, "attemptNumber": { "readOnly": true, "description": "Number of delivery attempts made so far (including retries).", "example": 1, "type": "integer", "examples": [ 1 ] }, "deliveredAt": { "readOnly": true, "description": "Timestamp of the successful delivery; null while pending or when permanently failed.", "example": "2026-06-03T14:32:10+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-06-03T14:32:10+00:00" ] }, "lastErrorMessage": { "readOnly": true, "description": "Error message from the last failed attempt; null when successfully delivered.", "example": "Connection timed out after 5000ms", "type": [ "string", "null" ], "examples": [ "Connection timed out after 5000ms" ] }, "_id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } } } }, "required": [ "type", "id" ] } } } } ] } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventNotification" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "List event notifications", "description": "List event notifications", "parameters": [ { "name": "page", "in": "query", "description": "The collection page number", "required": false, "deprecated": false, "schema": { "type": "integer", "default": 1 }, "style": "form", "explode": true }, { "name": "createdAt[before]", "in": "query", "description": "Only notifications created at or before this time. A date alone means 00:00 UTC that day.", "required": false, "deprecated": false, "schema": { "type": "string" }, "style": "form", "explode": false, "example": "2026-01-31T23:59:59Z" }, { "name": "createdAt[strictly_before]", "in": "query", "description": "Only notifications created before this time. A date alone means 00:00 UTC that day.", "required": false, "deprecated": false, "schema": { "type": "string" }, "style": "form", "explode": false, "example": "2026-02-01T00:00:00Z" }, { "name": "createdAt[after]", "in": "query", "description": "Only notifications created at or after this time. A date alone means 00:00 UTC that day.", "required": false, "deprecated": false, "schema": { "type": "string" }, "style": "form", "explode": false, "example": "2026-01-01T00:00:00Z" }, { "name": "createdAt[strictly_after]", "in": "query", "description": "Only notifications created after this time. A date alone means 00:00 UTC that day.", "required": false, "deprecated": false, "schema": { "type": "string" }, "style": "form", "explode": false, "example": "2026-01-01T00:00:00Z" }, { "name": "status", "in": "query", "description": "Restrict to notifications in this delivery status.", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "PENDING", "DELIVERED", "FAILED", "SUSPENDED", "SKIPPED" ], "example": "FAILED", "examples": [ "FAILED" ] }, "style": "form", "explode": true } ] } }, "/event-notifications/{id}": { "get": { "operationId": "getEventNotification", "tags": [ "EventNotification" ], "responses": { "200": { "description": "EventNotification resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EventNotification.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EventNotification" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get an event notification", "description": "Get an event notification", "parameters": [ { "name": "id", "in": "path", "description": "EventNotification identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/favorite-properties": { "get": { "operationId": "listFavoriteProperties", "tags": [ "FavoriteProperty" ], "responses": { "200": { "description": "FavoriteProperty collection", "content": { "application/vnd.api+json": { "schema": { "description": "FavoriteProperty.jsonapi collection.", "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchema" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "FavoriteProperty", "examples": [ "FavoriteProperty" ] }, "attributes": { "type": "object", "properties": { "propertyId": { "format": "uuid", "description": "Property id", "externalDocs": { "url": "https://schema.org/identifier" }, "example": "550e8400-e29b-41d4-a716-446655440000", "type": [ "string", "null" ], "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "_id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "required": [ "type", "id" ] } } } } ] } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FavoriteProperty" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "List favorite properties", "description": "List favorite properties", "parameters": [ { "name": "page", "in": "query", "description": "The collection page number", "required": false, "deprecated": false, "schema": { "type": "integer", "default": 1 }, "style": "form", "explode": true } ] }, "post": { "operationId": "createFavoriteProperty", "tags": [ "FavoriteProperty" ], "responses": { "201": { "description": "FavoriteProperty resource created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/FavoriteProperty.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteProperty" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "An error occurred", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} } }, "summary": "Create a favorite property", "description": "Create a favorite property", "parameters": [], "requestBody": { "description": "The new FavoriteProperty resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/FavoriteProperty.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteProperty" } } }, "required": true } } }, "/favorite-properties/{id}": { "delete": { "operationId": "deleteFavoriteProperty", "tags": [ "FavoriteProperty" ], "responses": { "204": { "description": "FavoriteProperty resource deleted" }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Delete a favorite property", "description": "Delete a favorite property", "parameters": [ { "name": "id", "in": "path", "description": "FavoriteProperty identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/geo/administrative-divisions/{id}": { "get": { "operationId": "getAdministrativeDivision", "tags": [ "Geo" ], "responses": { "200": { "description": "AdministrativeDivision resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AdministrativeDivision.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/AdministrativeDivision" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get an administrative division", "description": "Get an administrative division", "parameters": [ { "name": "id", "in": "path", "description": "AdministrativeDivision identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/geo/administrative-divisions/{id}/ancestors": { "get": { "operationId": "listAdministrativeDivisionAncestors", "tags": [ "Geo" ], "responses": { "200": { "description": "AdministrativeDivision collection", "content": { "application/vnd.api+json": { "schema": { "description": "AdministrativeDivision.jsonapi collection.", "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchemaNoPagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "AdministrativeDivision", "examples": [ "AdministrativeDivision" ] }, "attributes": { "type": "object", "properties": { "name": { "description": "Human-readable display name.", "example": "Paris", "type": "string", "examples": [ "Paris" ] }, "uniqueCode": { "description": "National unique code (INSEE code in France).", "example": "75056", "type": [ "string", "null" ], "examples": [ "75056" ] }, "locationType": { "description": "Administrative type.", "example": "MUNICIPALITY", "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ], "nullable": true, "examples": [ "MUNICIPALITY" ] }, "countryCode": { "description": "Country the division belongs to.", "example": "FR", "type": "string", "enum": [ "FR", "BE" ], "nullable": true, "examples": [ "FR" ] }, "postalCodes": { "description": "Postal codes attached to this division.", "example": [ "75001", "75002", "75003" ], "type": [ "array", "null" ], "items": { "type": "string" }, "examples": [ [ "75001", "75002", "75003" ] ] }, "centroid": { "description": "GeoJSON (RFC 7946) Point (centroid).", "example": { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] }, "anyOf": [ { "$ref": "#/components/schemas/GeoJsonGeometry" }, { "type": "null" } ], "examples": [ { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] } ] }, "_id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "required": [ "type", "id" ] } } } } ] } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AdministrativeDivision" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "List the ancestors of an administrative division (breadcrumb / drill-up)", "description": "Returns the parent chain of the given division up to the country root — for example a neighborhood, its arrondissement, commune, department, region and country. By default the division itself is excluded and the chain is ordered root first (country first). Use order=NODE_FIRST for immediate-parent first, and includeSelf=true to prepend the division for a ready-to-render breadcrumb.", "parameters": [ { "name": "order", "in": "query", "description": "Ordering of the chain: ROOT_FIRST (country first, the default) or NODE_FIRST (immediate parent first).", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "ROOT_FIRST", "NODE_FIRST" ] }, "style": "form", "explode": true, "example": "ROOT_FIRST" }, { "name": "includeSelf", "in": "query", "description": "Include the division itself in the chain. Defaults to false.", "required": false, "deprecated": false, "schema": { "type": "boolean" }, "style": "form", "explode": true, "example": false }, { "name": "id", "in": "path", "description": "Administrative division id.", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/geo/administrative-divisions/{id}/descendants": { "get": { "operationId": "listAdministrativeDivisionDescendants", "tags": [ "Geo" ], "responses": { "200": { "description": "AdministrativeDivision collection", "content": { "application/vnd.api+json": { "schema": { "description": "AdministrativeDivision.jsonapi collection.", "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchema" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "AdministrativeDivision", "examples": [ "AdministrativeDivision" ] }, "attributes": { "type": "object", "properties": { "name": { "description": "Human-readable display name.", "example": "Paris", "type": "string", "examples": [ "Paris" ] }, "uniqueCode": { "description": "National unique code (INSEE code in France).", "example": "75056", "type": [ "string", "null" ], "examples": [ "75056" ] }, "locationType": { "description": "Administrative type.", "example": "MUNICIPALITY", "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ], "nullable": true, "examples": [ "MUNICIPALITY" ] }, "countryCode": { "description": "Country the division belongs to.", "example": "FR", "type": "string", "enum": [ "FR", "BE" ], "nullable": true, "examples": [ "FR" ] }, "postalCodes": { "description": "Postal codes attached to this division.", "example": [ "75001", "75002", "75003" ], "type": [ "array", "null" ], "items": { "type": "string" }, "examples": [ [ "75001", "75002", "75003" ] ] }, "centroid": { "description": "GeoJSON (RFC 7946) Point (centroid).", "example": { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] }, "anyOf": [ { "$ref": "#/components/schemas/GeoJsonGeometry" }, { "type": "null" } ], "examples": [ { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] } ] }, "_id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "required": [ "type", "id" ] } } } } ] } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AdministrativeDivision" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "List the descendants of an administrative division, at any depth", "description": "Returns every division below the given one, across intermediate levels, optionally filtered by type and bounded by maxDepth. maxDepth of 1 returns only the direct children. Use this to list, for example, every neighborhood of a city — including Paris, Lyon and Marseille, whose neighborhoods sit under an arrondissement. Set includeSelf=true to also return the division itself (its full scope: the division and everything below).", "parameters": [ { "name": "locationType", "in": "query", "description": "Filter the descendants by type. Supports a single value (?locationType=NEIGHBORHOOD) or array syntax (?locationType[]=MUNICIPAL_DISTRICT&locationType[]=NEIGHBORHOOD).", "required": false, "deprecated": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ] }, { "type": "array", "items": { "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ] }, "uniqueItems": true } ] }, "style": "form", "explode": true, "example": "NEIGHBORHOOD" }, { "name": "maxDepth", "in": "query", "description": "Limit how many levels below the division to include. 1 returns only the direct children; omit for any depth.", "required": false, "deprecated": false, "schema": { "type": "integer", "minimum": 1 }, "style": "form", "explode": true, "example": 1 }, { "name": "includeSelf", "in": "query", "description": "Include the division itself alongside its descendants. The division is always included when set, regardless of type or maxDepth. Defaults to false.", "required": false, "deprecated": false, "schema": { "type": "boolean" }, "style": "form", "explode": true, "example": false }, { "name": "size", "in": "query", "description": "Number of items per page, from 1 to 100. A value outside that range is brought back to the nearest bound.", "required": false, "deprecated": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "style": "form", "explode": true, "example": 30 }, { "name": "id", "in": "path", "description": "Ancestor administrative division id.", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "name": "page", "in": "query", "description": "The collection page number", "required": false, "deprecated": false, "schema": { "type": "integer", "default": 1 }, "style": "form", "explode": true } ] } }, "/geo/administrative-divisions/{id}/geometry": { "get": { "operationId": "getAdministrativeDivisionGeometry", "tags": [ "Geo" ], "responses": { "200": { "description": "AdministrativeDivisionGeometry resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AdministrativeDivisionGeometry.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/AdministrativeDivisionGeometry" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get the boundary of an administrative division", "description": "Returns the administrative boundary as GeoJSON, ready to draw on a map. The outline is simplified to a level of detail suited to the division size, so a large region stays a small response. Contours change only when location data is reimported, so the response can be cached by the client.", "parameters": [ { "name": "id", "in": "path", "description": "AdministrativeDivisionGeometry identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/geo/autocomplete": { "get": { "operationId": "autocompleteLocations", "tags": [ "Geo" ], "responses": { "200": { "description": "LocationAutocomplete collection", "content": { "application/vnd.api+json": { "schema": { "description": "LocationAutocomplete.LocationSuggestionResource.jsonapi collection.", "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchema" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "LocationAutocomplete", "examples": [ "LocationAutocomplete" ] }, "attributes": { "type": "object", "properties": { "name": { "description": "Human-readable display name.", "example": "Paris", "type": "string", "examples": [ "Paris" ] }, "locationType": { "description": "Administrative type.", "example": "MUNICIPALITY", "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ], "nullable": true, "examples": [ "MUNICIPALITY" ] }, "parentName": { "description": "Immediate parent name (e.g. department for a city).", "example": "Paris", "type": [ "string", "null" ], "examples": [ "Paris" ] }, "regionName": { "description": "Region name, for disambiguation.", "example": "Île-de-France", "type": [ "string", "null" ], "examples": [ "Île-de-France" ] }, "countryCode": { "description": "Country the division belongs to.", "example": "FR", "type": "string", "enum": [ "FR", "BE" ], "nullable": true, "examples": [ "FR" ] }, "postalCode": { "description": "Primary postal code.", "example": "75001", "type": [ "string", "null" ], "examples": [ "75001" ] }, "centroid": { "description": "GeoJSON (RFC 7946) Point for map marker placement.", "example": { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] }, "anyOf": [ { "$ref": "#/components/schemas/GeoJsonGeometry" }, { "type": "null" } ], "examples": [ { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] } ] }, "metadata": { "description": "Additional data (population, hierarchy depth, postal codes, uniqueCode, …).", "example": { "depth": 3, "population": 2102650, "postalCodes": [ "75001", "75002", "75003" ], "uniqueCode": "75056" }, "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "examples": [ { "depth": 3, "population": 2102650, "postalCodes": [ "75001", "75002", "75003" ], "uniqueCode": "75056" } ] }, "_id": { "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "required": [ "type", "id" ] } } } } ] } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LocationAutocomplete.LocationSuggestion" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Location autocomplete suggestions", "description": "Returns location suggestions based on search query. Supports typo-tolerant search, postal code prefixes, administrative subregion codes (French department numbers), usual abbreviations, and filtering by administrative type.", "parameters": [ { "name": "query", "in": "query", "description": "Search query string (minimum 1 character): a name, a postal code prefix, the code of an administrative subregion (a French department number such as 83), or a usual abbreviation such as PACA.", "required": true, "deprecated": false, "schema": { "type": "string", "minLength": 1 }, "style": "form", "explode": true, "example": "paris" }, { "name": "type", "in": "query", "description": "Administrative type filter. Supports a single value (?type=MUNICIPALITY) or array syntax (?type[]=MUNICIPALITY&type[]=MUNICIPAL_DISTRICT).", "required": false, "deprecated": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ] }, { "type": "array", "items": { "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ] }, "uniqueItems": true } ] }, "style": "form", "explode": true, "example": "MUNICIPALITY" }, { "name": "limit", "in": "query", "description": "Maximum number of results.", "required": false, "deprecated": false, "schema": { "type": "integer", "minimum": 0, "maximum": 30, "default": 30 }, "style": "form", "explode": true, "example": 10 }, { "name": "page", "in": "query", "description": "The collection page number", "required": false, "deprecated": false, "schema": { "type": "integer", "default": 1 }, "style": "form", "explode": true } ] } }, "/properties": { "post": { "operationId": "searchProperties", "tags": [ "Property" ], "responses": { "200": { "description": "Search results matching the criteria", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PropertySearch.PropertySearchResponse.jsonapi" } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PropertySearchResult" } } } }, "headers": { "X-Credits-Charged": { "description": "Credits this call cost, one per result returned. A search that matches nothing costs nothing and reports 0. Absent when the account is not billed in credits.", "schema": { "type": "string", "example": "12" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "402": { "description": "Credit balance exhausted. The call was not served and was not charged; top up to resume." }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "An error occurred", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} } }, "summary": "Search properties", "description": "Search properties using flat filters or a nested AND/OR criteria tree, with page-based or cursor-based pagination — all selected via the request body.", "parameters": [], "requestBody": { "description": "Property search request. The criteria field is a recursive tree — see the examples below, from a flat filter bag to a composed tree.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertySearch.PropertySearchRequestInput" }, "examples": { "flat": { "summary": "Recherche simple avec filtres directs", "description": "Appartements ou maisons à vendre à Paris hors 18ᵉ, entre 350 et 750 k€, au moins 45 m², avec balcon et orientés sud.", "value": { "paginationType": "PAGE", "page": 1, "size": 20, "criteria": { "property": { "type": { "in": [ "FLAT", "HOUSE" ] }, "transaction": { "type": "SELL" }, "pricing": { "displayed": { "gte": 350000, "lte": 750000 }, "pricePerArea": { "gte": 8000, "lte": 14000 }, "sale": { "netPrice": { "gte": 300000, "orMissing": true }, "fees": { "agency": { "paidBy": "SELLER", "includedInPrice": true } } } }, "areas": { "displayed": { "gte": 45 } }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] }, "nin": { "uniqueCodes": [ "75118" ] }, "accuracy": [ "PRECISE", "STREET" ] }, "unit": { "features": { "in": [ "BALCONY" ], "nin": [ "GROUND_FLOOR" ], "inOrMissing": [ "FURNISHED" ] }, "rooms": { "gte": 2, "lte": 5, "orMissing": false }, "bedrooms": { "gte": 1, "orMissing": true }, "orientation": { "inOrMissing": [ "SOUTH", "SOUTH_WEST" ] }, "condition": { "nin": [ "TO_RENOVATE" ] }, "energy": { "heating": { "energyCarrier": { "nin": [ "OIL" ] }, "collective": false } } }, "building": { "constructionYear": { "gte": 1900, "lte": 2024, "orMissing": true }, "constructionType": { "in": [ "HAUSSMANNIAN", "STONE" ] }, "condition": { "inOrMissing": [ "GOOD", "NEW" ] } }, "body": { "title": { "in": [ "lumineux balcon" ] } } }, "publisher": { "type": { "in": [ "PROFESSIONAL" ] }, "mandate": { "in": [ "EXCLUSIVE", "SEMI_EXCLUSIVE" ] }, "hasEmail": true, "hasPhone": true }, "listings": { "marketing": { "urgent": true } }, "dates": { "updatedAt": { "from": "2026-01-01T00:00:00Z" } } } } }, "oneOr": { "summary": "Plusieurs cibles dans une seule requête", "description": "Studios à Paris ou lofts à Lyon, publiés par des professionnels et mis à jour depuis mars 2026.", "value": { "paginationType": "PAGE", "page": 1, "size": 20, "criteria": { "and": [ { "publisher": { "type": { "in": [ "PROFESSIONAL" ] }, "hasPhone": true }, "dates": { "updatedAt": { "from": "2026-03-01T00:00:00Z" } } }, { "or": [ { "property": { "type": { "in": [ "FLAT" ] }, "unit": { "rooms": { "gte": 1, "lte": 1 } }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } } } }, { "property": { "type": { "in": [ "HOUSE" ] }, "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "69123" ] } } } } ] } ] } } }, "composed": { "summary": "Recherche avancée avec pagination curseur", "description": "Appartements meublés à Paris ou Lyon, à vendre 200-500 k€ avec mandat exclusif ou à louer moins de 2 000 €/mois avec mention « urgent ».", "value": { "paginationType": "CURSOR", "size": 20, "criteria": { "and": [ { "property": { "type": { "in": [ "FLAT" ] }, "unit": { "features": { "inOrMissing": [ "FURNISHED" ] }, "condition": { "nin": [ "TO_RENOVATE" ] } }, "building": { "energy": { "heating": { "energyCarrier": { "nin": [ "OIL" ] } } } } } }, { "or": [ { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } } } }, { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "69123" ] } } } } ] }, { "or": [ { "property": { "transaction": { "type": "SELL" }, "pricing": { "displayed": { "gte": 200000, "lte": 500000 }, "sale": { "fees": { "agency": { "paidBy": "SELLER" } } } } }, "publisher": { "type": { "in": [ "PROFESSIONAL" ] }, "mandate": { "in": [ "EXCLUSIVE" ] } } }, { "property": { "transaction": { "type": "RENT" }, "pricing": { "displayed": { "lte": 2000 }, "rental": { "fees": { "agency": { "amount": { "lte": 1500, "orMissing": true } } } } } }, "listings": { "marketing": { "urgent": true } } } ] } ] } } }, "revisionChanges": { "summary": "Biens ayant baissé de prix récemment", "description": "Biens dont le prix a baissé d'au moins 5 % ces 7 derniers jours. Le bloc changes cible un seul changement à la fois : l'attribut, sa variation signée (une baisse est négative) et sa date portent sur le même changement.", "value": { "paginationType": "PAGE", "page": 1, "size": 20, "criteria": { "changes": { "attribute": { "in": [ "DISPLAYED_PRICE" ] }, "variationPercent": { "lte": -5 }, "occurredAt": { "from": "2026-07-22T00:00:00Z" } } } } } } } }, "required": true } } }, "/properties/{id}": { "get": { "operationId": "getProperty", "tags": [ "Property" ], "responses": { "200": { "description": "The property", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PropertySearchResultDocument.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PropertySearchResult" } } }, "headers": { "X-Credits-Charged": { "description": "Credits this call cost. A flat price per property read. Absent when the account is not billed in credits.", "schema": { "type": "string", "example": "1" } } } }, "402": { "description": "Credit balance exhausted. The call was not served and was not charged; top up to resume." }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get property", "description": "Retrieve a single property by its id.", "parameters": [ { "name": "id", "in": "path", "description": "PropertySearch identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/properties/lookup-by-url": { "post": { "operationId": "lookupPropertyByUrl", "tags": [ "Property" ], "responses": { "200": { "description": "The property published at the URL", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PropertyUrlLookup.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PropertyUrlLookup" } } }, "headers": { "X-Credits-Charged": { "description": "Credits this call cost: one credit for a match, while a URL we do not know answers 404 and costs nothing. Absent when the account is not billed in credits.", "schema": { "type": "string", "example": "1" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "402": { "description": "Credit balance exhausted. The call was not served and was not charged; top up to resume." }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "No property is known at this URL. Not charged." }, "422": { "description": "The url is missing or is not a valid http or https URL. Not charged.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} } }, "summary": "Look up a property by a listing URL", "description": "Tells whether we hold the property published at a URL, and where to fetch it.", "parameters": [], "requestBody": { "description": "The listing URL to look up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyUrlLookup.PropertyUrlLookupInput" } } }, "required": true } } }, "/properties/{id}/resolve-address": { "post": { "operationId": "resolvePropertyAddress", "tags": [ "Property" ], "responses": { "200": { "description": "The resolution, found or not", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyAddressResolution" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Unknown property" }, "422": { "description": "The property is outside the countries covered", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} }, "429": { "description": "This account resolved too many addresses in the last minute; retry after the delay given" }, "503": { "description": "A source did not answer; retry later" } }, "summary": "Resolve the address of a property", "description": "Finds the exact postal address of a property from the data its listings carry: the energy certificate registry first, then the national address base around a precise location. Beta: the matching is being tuned and the confidence bands may move. A result is returned whatever the outcome; read the confidence before showing the address. EXACT and HIGH can be shown as the address, MEDIUM and LOW as a probable address, NONE means nothing was found. Covers properties located in France; other countries are refused.", "parameters": [ { "name": "id", "in": "path", "description": "Property id", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "x-stability": "beta" } }, "/publishers/{id}": { "get": { "operationId": "getPublisher", "tags": [ "Property" ], "responses": { "200": { "description": "Publisher resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PublisherDocument.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Publisher" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get a publisher", "description": "Get a publisher", "parameters": [ { "name": "id", "in": "path", "description": "Publisher identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/source-categories": { "get": { "operationId": "listSourceCategories", "tags": [ "Property" ], "responses": { "200": { "description": "SourceCategory collection", "content": { "application/vnd.api+json": { "schema": { "description": "SourceCategory.jsonapi collection.", "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchema" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "SourceCategory", "examples": [ "SourceCategory" ] }, "attributes": { "type": "object", "properties": { "name": { "description": "Human-readable category name.", "example": "Real Estate Networks", "type": "string", "examples": [ "Real Estate Networks" ] }, "_id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "required": [ "type", "id" ] } } } } ] } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SourceCategory" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "List source categories", "description": "List source categories", "parameters": [ { "name": "page", "in": "query", "description": "The collection page number", "required": false, "deprecated": false, "schema": { "type": "integer", "default": 1 }, "style": "form", "explode": true } ] } }, "/source-categories/{id}": { "get": { "operationId": "getSourceCategory", "tags": [ "Property" ], "responses": { "200": { "description": "SourceCategory resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SourceCategory.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SourceCategory" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get a source category", "description": "Get a source category", "parameters": [ { "name": "id", "in": "path", "description": "SourceCategory identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/sources": { "get": { "operationId": "listSources", "tags": [ "Property" ], "responses": { "200": { "description": "Source collection", "content": { "application/vnd.api+json": { "schema": { "description": "Source.jsonapi collection.", "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchema" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "Source", "examples": [ "Source" ] }, "attributes": { "type": "object", "properties": { "name": { "example": "Realty Portal", "type": "string", "examples": [ "Realty Portal" ] }, "domain": { "example": "realty-portal.com", "type": "string", "examples": [ "realty-portal.com" ] }, "_id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "required": [ "type", "id" ] } } } } ] } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "List sources", "description": "List sources", "parameters": [ { "name": "page", "in": "query", "description": "The collection page number", "required": false, "deprecated": false, "schema": { "type": "integer", "default": 1 }, "style": "form", "explode": true }, { "name": "name", "in": "query", "description": "Filter sources by name (partial match).", "required": false, "deprecated": false, "schema": { "type": "string" }, "style": "form", "explode": false, "example": "realty" } ] } }, "/sources/{id}": { "get": { "operationId": "getSource", "tags": [ "Property" ], "responses": { "200": { "description": "Source resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Source.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get a source", "description": "Get a source", "parameters": [ { "name": "id", "in": "path", "description": "Source identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/transactions/{id}": { "get": { "operationId": "getTransaction", "tags": [ "Transaction" ], "responses": { "200": { "description": "Transaction resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Transaction.TransactionResult.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResult" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} } }, "summary": "Get transaction", "description": "Retrieve a single transaction by its id.", "parameters": [ { "name": "id", "in": "path", "description": "Transaction identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "/transactions/search": { "post": { "operationId": "searchTransactions", "tags": [ "Transaction" ], "responses": { "200": { "description": "Transactions matching the search", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Transaction.TransactionSearchResponse.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Transaction.TransactionSearchResponse" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "An error occurred", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation.jsonapi" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} } }, "summary": "Search transactions", "description": "Search closed real-estate transactions with optional filters (date, property type, price, location ids, and a GeoJSON polygon), cursor-paginated. Overlapping records from different sources are reconciled on the fly: a duplicate is suppressed and merged into the surviving row, which then carries a matched block. Filters are sent in the request body rather than the query string so a large geoshape polygon is not constrained by URL length.", "parameters": [], "requestBody": { "description": "The new Transaction resource", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Transaction.TransactionSearchRequestInput.jsonapi" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Transaction.TransactionSearchRequestInput" } } }, "required": true } } } }, "components": { "schemas": { "AdministrativeDivision": { "type": "object", "properties": { "name": { "description": "Human-readable display name.", "example": "Paris", "type": "string", "examples": [ "Paris" ] }, "uniqueCode": { "description": "National unique code (INSEE code in France).", "example": "75056", "type": [ "string", "null" ], "examples": [ "75056" ] }, "locationType": { "description": "Administrative type.", "example": "MUNICIPALITY", "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ], "nullable": true, "examples": [ "MUNICIPALITY" ] }, "countryCode": { "description": "Country the division belongs to.", "example": "FR", "type": "string", "enum": [ "FR", "BE" ], "nullable": true, "examples": [ "FR" ] }, "postalCodes": { "description": "Postal codes attached to this division.", "example": [ "75001", "75002", "75003" ], "type": [ "array", "null" ], "items": { "type": "string" }, "examples": [ [ "75001", "75002", "75003" ] ] }, "centroid": { "description": "GeoJSON (RFC 7946) Point (centroid).", "example": { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] }, "anyOf": [ { "$ref": "#/components/schemas/GeoJsonGeometry" }, { "type": "null" } ], "examples": [ { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] } ] }, "id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } }, "AdministrativeDivision.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "AdministrativeDivision", "examples": [ "AdministrativeDivision" ] }, "attributes": { "type": "object", "properties": { "name": { "description": "Human-readable display name.", "example": "Paris", "type": "string", "examples": [ "Paris" ] }, "uniqueCode": { "description": "National unique code (INSEE code in France).", "example": "75056", "type": [ "string", "null" ], "examples": [ "75056" ] }, "locationType": { "description": "Administrative type.", "example": "MUNICIPALITY", "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ], "nullable": true, "examples": [ "MUNICIPALITY" ] }, "countryCode": { "description": "Country the division belongs to.", "example": "FR", "type": "string", "enum": [ "FR", "BE" ], "nullable": true, "examples": [ "FR" ] }, "postalCodes": { "description": "Postal codes attached to this division.", "example": [ "75001", "75002", "75003" ], "type": [ "array", "null" ], "items": { "type": "string" }, "examples": [ [ "75001", "75002", "75003" ] ] }, "centroid": { "description": "GeoJSON (RFC 7946) Point (centroid).", "example": { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] }, "anyOf": [ { "$ref": "#/components/schemas/GeoJsonGeometry" }, { "type": "null" } ], "examples": [ { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] } ] } } } }, "required": [ "type", "id" ] }, "AdministrativeDivisionReference": { "type": "object", "properties": { "iri": { "description": "Canonical IRI of the AdministrativeDivision resource.", "default": "", "example": "/geo/administrative-divisions/019dedb1-fdf4-714c-8392-5b9cfd63cde3", "type": "string", "examples": [ "/geo/administrative-divisions/019dedb1-fdf4-714c-8392-5b9cfd63cde3" ] }, "id": { "description": "Public Id of the AdministrativeDivision.", "default": "", "example": "019dedb1-fdf4-714c-8392-5b9cfd63cde3", "type": "string", "examples": [ "019dedb1-fdf4-714c-8392-5b9cfd63cde3" ] }, "name": { "description": "Display name.", "example": "Paris", "type": [ "string", "null" ], "examples": [ "Paris" ] }, "type": { "description": "Generic administrative type.", "example": "MUNICIPALITY", "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ], "nullable": true, "examples": [ "MUNICIPALITY" ] }, "uniqueCode": { "description": "Country-specific unique code (e.g. INSEE for FR, postal-derived elsewhere). Set on the city slot only.", "example": "75056", "type": [ "string", "null" ], "examples": [ "75056" ] }, "postalCodes": { "description": "Postal codes attached to this division. Set on the city slot only.", "example": [ "75018" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "75018" ] ] } } }, "AdministrativeDivisionGeometry": { "type": "object", "description": "Contours of an administrative division, split out of the division resource (#44): the raw boundary of a\nlarge region dominated that payload (seconds, megabytes), while most callers only need the metadata.\nThe boundary served here is the simplified copy precomputed at import, read as GeoJSON from the database\nso no boundary is ever hydrated into PHP geometry objects.", "properties": { "geometry": { "description": "GeoJSON (RFC 7946) Polygon or MultiPolygon of the administrative boundary.", "example": { "type": "Polygon", "coordinates": [ [ [ 2.224, 48.815 ], [ 2.47, 48.815 ], [ 2.47, 48.902 ], [ 2.224, 48.902 ], [ 2.224, 48.815 ] ] ] }, "anyOf": [ { "$ref": "#/components/schemas/GeoJsonGeometry" }, { "type": "null" } ], "examples": [ { "type": "Polygon", "coordinates": [ [ [ 2.224, 48.815 ], [ 2.47, 48.815 ], [ 2.47, 48.902 ], [ 2.224, 48.902 ], [ 2.224, 48.815 ] ] ] } ] }, "id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } }, "AdministrativeDivisionGeometry.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "AdministrativeDivisionGeometry", "examples": [ "AdministrativeDivisionGeometry" ] }, "attributes": { "type": "object", "properties": { "geometry": { "description": "GeoJSON (RFC 7946) Polygon or MultiPolygon of the administrative boundary.", "example": { "type": "Polygon", "coordinates": [ [ [ 2.224, 48.815 ], [ 2.47, 48.815 ], [ 2.47, 48.902 ], [ 2.224, 48.902 ], [ 2.224, 48.815 ] ] ] }, "anyOf": [ { "$ref": "#/components/schemas/GeoJsonGeometry" }, { "type": "null" } ], "examples": [ { "type": "Polygon", "coordinates": [ [ [ 2.224, 48.815 ], [ 2.47, 48.815 ], [ 2.47, 48.902 ], [ 2.224, 48.902 ], [ 2.224, 48.815 ] ] ] } ] } } } }, "required": [ "type", "id" ] }, "AgencyFee": { "type": "object", "properties": { "amount": { "description": "Fee amount.", "example": 24000, "type": [ "number", "null" ], "examples": [ 24000 ] }, "percentage": { "description": "Fee percentage of the sale price.", "example": 7.5, "type": [ "number", "null" ], "examples": [ 7.5 ] }, "currency": { "description": "Currency of the fee.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "paidBy": { "description": "Who pays the fee.", "example": "SELLER", "type": "string", "enum": [ "BUYER", "SELLER", "OWNER", "TENANT" ], "nullable": true, "examples": [ "SELLER" ] }, "includedInPrice": { "description": "Whether the fee is already included in the displayed sale price.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] } } }, "Alert": { "type": "object", "properties": { "name": { "description": "Alert name", "example": "2-bedroom apartments in Paris", "type": [ "string", "null" ], "examples": [ "2-bedroom apartments in Paris" ] }, "enabled": { "description": "Whether the alert is enabled. A disabled alert stops matching new listings and sends nothing, including notifications already queued for it.", "default": true, "type": "boolean" }, "criteria": { "description": "Search criteria tree (nested and/or groups with sets of property filters). Same shape as the POST /properties criteria. Absent when the alert has no criteria, which means it matches every property.", "example": { "and": [ { "property": { "type": { "in": [ "FLAT", "HOUSE" ] }, "transaction": { "type": "SELL" }, "pricing": { "displayed": { "gte": 200000, "lte": 450000 } }, "unit": { "bedrooms": { "gte": 2 } } } }, { "or": [ { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } } } }, { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "69123" ] } } } } ] } ] }, "type": "object", "additionalProperties": true, "examples": [ { "and": [ { "property": { "type": { "in": [ "FLAT", "HOUSE" ] }, "transaction": { "type": "SELL" }, "pricing": { "displayed": { "gte": 200000, "lte": 450000 } }, "unit": { "bedrooms": { "gte": 2 } } } }, { "or": [ { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } } } }, { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "69123" ] } } } } ] } ] } ] }, "notificationConfig": { "description": "Notification configuration. Omit it and the alert never notifies: it is what selects the event types you receive.", "anyOf": [ { "$ref": "#/components/schemas/AlertNotificationConfig" }, { "type": "null" } ] }, "eventDestination": { "readOnly": true, "description": "Event destination notifications are delivered to. Set it on create or update through notificationDestination.", "type": [ "string", "null" ], "format": "iri-reference", "example": "https://example.com/", "examples": [ "https://example.com/" ] }, "signingKey": { "readOnly": true, "description": "Webhook signing key. Present only when this request created the first webhook destination of your account; store it securely, it cannot be retrieved again", "example": "whsec_abc123...", "type": [ "string", "null" ], "examples": [ "whsec_abc123..." ] }, "signingKeyHint": { "readOnly": true, "description": "A short fingerprint of the signing key returned above (the first 8 hex characters of its sha256). Keep it: it is what identifies your active key later, and your dashboard shows the same value.", "example": "b75b1473", "type": [ "string", "null" ], "examples": [ "b75b1473" ] }, "id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } } }, "Alert.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "Alert", "examples": [ "Alert" ] }, "attributes": { "type": "object", "properties": { "name": { "description": "Alert name", "example": "2-bedroom apartments in Paris", "type": [ "string", "null" ], "examples": [ "2-bedroom apartments in Paris" ] }, "enabled": { "description": "Whether the alert is enabled. A disabled alert stops matching new listings and sends nothing, including notifications already queued for it.", "default": true, "type": "boolean" }, "criteria": { "description": "Search criteria tree (nested and/or groups with sets of property filters). Same shape as the POST /properties criteria. Absent when the alert has no criteria, which means it matches every property.", "example": { "and": [ { "property": { "type": { "in": [ "FLAT", "HOUSE" ] }, "transaction": { "type": "SELL" }, "pricing": { "displayed": { "gte": 200000, "lte": 450000 } }, "unit": { "bedrooms": { "gte": 2 } } } }, { "or": [ { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } } } }, { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "69123" ] } } } } ] } ] }, "type": "object", "additionalProperties": true, "examples": [ { "and": [ { "property": { "type": { "in": [ "FLAT", "HOUSE" ] }, "transaction": { "type": "SELL" }, "pricing": { "displayed": { "gte": 200000, "lte": 450000 } }, "unit": { "bedrooms": { "gte": 2 } } } }, { "or": [ { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "75056" ] } } } }, { "property": { "locations": { "countryCode": "FR", "in": { "uniqueCodes": [ "69123" ] } } } } ] } ] } ] }, "notificationConfig": { "description": "Notification configuration. Omit it and the alert never notifies: it is what selects the event types you receive.", "anyOf": [ { "$ref": "#/components/schemas/AlertNotificationConfig" }, { "type": "null" } ] }, "signingKey": { "readOnly": true, "description": "Webhook signing key. Present only when this request created the first webhook destination of your account; store it securely, it cannot be retrieved again", "example": "whsec_abc123...", "type": [ "string", "null" ], "examples": [ "whsec_abc123..." ] }, "signingKeyHint": { "readOnly": true, "description": "A short fingerprint of the signing key returned above (the first 8 hex characters of its sha256). Keep it: it is what identifies your active key later, and your dashboard shows the same value.", "example": "b75b1473", "type": [ "string", "null" ], "examples": [ "b75b1473" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } } }, "relationships": { "type": "object", "properties": { "eventDestination": { "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "example": "EventDestination", "examples": [ "EventDestination" ] }, "id": { "type": "string", "format": "iri-reference", "example": "/eventDestinations/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/eventDestinations/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } ], "example": { "type": "EventDestination", "id": "/eventDestinations/3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "examples": [ { "type": "EventDestination", "id": "/eventDestinations/3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } } } } } }, "required": [ "type", "id" ] }, "AlertEvent": { "type": "object", "properties": { "alert": { "description": "Alert", "type": "string", "format": "iri-reference", "example": "https://example.com/", "examples": [ "https://example.com/" ] }, "property": { "description": "Property matched by this event", "type": "string", "format": "iri-reference", "example": "https://example.com/", "examples": [ "https://example.com/" ] }, "eventType": { "description": "Event type that triggered notification", "example": "PRICE_CHANGE", "type": "string", "enum": [ "NEW_MATCH", "PRICE_CHANGE", "OTHER_CHANGE", "EXPIRED", "REACTIVATED" ], "nullable": false, "examples": [ "PRICE_CHANGE" ] }, "scope": { "description": "What this event is about, matching the scope of the rule that produced it. PROPERTY: the property did something. LISTING: one advert of it did. Both name a listing, so this is the only field that tells them apart.", "default": "PROPERTY", "example": "PROPERTY", "type": "string", "enum": [ "PROPERTY", "LISTING" ], "nullable": false, "examples": [ "PROPERTY" ] }, "notifiedAt": { "description": "Date this event was processed for delivery, null while it is still queued. A processed event has no notification when the alert is no longer active, or when no delivery destination could be resolved. Events matching none of the alert notification rules are never listed here.", "example": "2026-07-28T09:15:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-07-28T09:15:00+00:00" ] }, "id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } }, "description": "Data is retained for 12 months, after which it is permanently deleted." }, "AlertEvent.jsonapi": { "type": "object", "description": "Data is retained for 12 months, after which it is permanently deleted.", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "AlertEvent", "examples": [ "AlertEvent" ] }, "attributes": { "type": "object", "properties": { "eventType": { "description": "Event type that triggered notification", "example": "PRICE_CHANGE", "type": "string", "enum": [ "NEW_MATCH", "PRICE_CHANGE", "OTHER_CHANGE", "EXPIRED", "REACTIVATED" ], "nullable": false, "examples": [ "PRICE_CHANGE" ] }, "scope": { "description": "What this event is about, matching the scope of the rule that produced it. PROPERTY: the property did something. LISTING: one advert of it did. Both name a listing, so this is the only field that tells them apart.", "default": "PROPERTY", "example": "PROPERTY", "type": "string", "enum": [ "PROPERTY", "LISTING" ], "nullable": false, "examples": [ "PROPERTY" ] }, "notifiedAt": { "description": "Date this event was processed for delivery, null while it is still queued. A processed event has no notification when the alert is no longer active, or when no delivery destination could be resolved. Events matching none of the alert notification rules are never listed here.", "example": "2026-07-28T09:15:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-07-28T09:15:00+00:00" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } } }, "relationships": { "type": "object", "properties": { "alert": { "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "example": "Alert", "examples": [ "Alert" ] }, "id": { "type": "string", "format": "iri-reference", "example": "/alerts/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/alerts/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } ], "example": { "type": "Alert", "id": "/alerts/3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "examples": [ { "type": "Alert", "id": "/alerts/3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } } }, "property": { "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "example": "Property", "examples": [ "Property" ] }, "id": { "type": "string", "format": "iri-reference", "example": "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } ], "example": { "type": "Property", "id": "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "examples": [ { "type": "Property", "id": "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } } } } } }, "required": [ "type", "id" ] }, "AlertForecast": { "type": "object", "description": "How many new matches alert criteria would have sent over the last days, so a client can size an alert\nbefore saving it. Computed on every call; writes nothing and is not billed.", "properties": { "windowDays": { "description": "Number of whole days the estimate is computed over.", "example": 30, "type": "integer", "examples": [ 30 ] }, "total": { "description": "New matches over the whole window.", "example": 2520, "type": "integer", "examples": [ 2520 ] }, "perDay": { "description": "New matches per day: the average, and the range most days fall in.", "example": { "average": 84, "low": 61, "high": 112 }, "$ref": "#/components/schemas/AlertVolumeRange", "examples": [ { "average": 84, "low": 61, "high": 112 } ] }, "perHour": { "description": "New matches per hour: the average, and the range most hours fall in. Arrivals come in bursts, so the high end can sit well above the average when matches are frequent.", "example": { "average": 3.5, "low": 0, "high": 9 }, "$ref": "#/components/schemas/AlertVolumeRange", "examples": [ { "average": 3.5, "low": 0, "high": 9 } ] } } }, "AlertNotificationConfig": { "type": "object", "properties": { "rules": { "minItems": 1, "description": "Notification rules, combined as independent subscriptions: each rule fires on its own. Only PRICE_CHANGE rules take a variationPercent window; the other event types notify on every occurrence.", "type": "array", "items": { "$ref": "#/components/schemas/AlertNotificationRule" } } } }, "AlertNotificationRule": { "type": "object", "required": [ "eventType" ], "properties": { "eventType": { "description": "Which event notifies. NEW_MATCH: the subject enters your search perimeter. PRICE_CHANGE: its price changes. OTHER_CHANGE: another attribute changes. EXPIRED: it leaves the market. REACTIVATED: it returns. An event type with no rule never notifies, so add a rule for every event you want to receive. OTHER_CHANGE covers every watched attribute except how precisely we placed the property: a coordinate moving inside the same commune is not a change to the advert.", "example": "PRICE_CHANGE", "type": "string", "enum": [ "NEW_MATCH", "PRICE_CHANGE", "OTHER_CHANGE", "EXPIRED", "REACTIVATED" ], "nullable": true, "examples": [ "PRICE_CHANGE" ] }, "scope": { "description": "What the notification talks about, and therefore how it will be grouped. PROPERTY (default): one notification per property — an identical change published on several listings of the same property notifies once. LISTING: one notification per listing, including cross-posts.", "default": "PROPERTY", "example": "PROPERTY", "type": "string", "enum": [ "PROPERTY", "LISTING" ], "nullable": false, "examples": [ "PROPERTY" ] }, "variationPercent": { "type": "array", "description": "Only for eventType PRICE_CHANGE: the signed variation windows that will trigger a notification, in percent — a drop is negative. A movement notifies when it falls in any one of them. Examples: a drop of at least 5% is one window with lte -5; a move of 5% either way is two windows, lte -5 and gte 5; a drop between 20% and 40% is one window with gte -40 and lte -20. Omit, or send an empty list, for every price change.", "items": { "$ref": "#/components/schemas/SignedFloatRange" } } } }, "AlertVolumeRange": { "type": "object", "properties": { "average": { "description": "Average number of new matches per period over the window, periods with none included.", "example": 13.7, "type": "number", "examples": [ 13.7 ] }, "low": { "description": "Low end of the usual range: at most one period in ten had fewer new matches.", "example": 6, "type": "integer", "examples": [ 6 ] }, "high": { "description": "High end of the usual range: at most one period in ten had more new matches.", "example": 24, "type": "integer", "examples": [ 24 ] } } }, "AmenitiesParking": { "type": "object", "properties": { "type": { "description": "Parking facility type (covered, garage, outdoor, …).", "example": "COVERED", "type": "string", "enum": [ "GARAGE", "OUTDOOR", "UNDERGROUND", "COVERED" ], "nullable": true, "examples": [ "COVERED" ] }, "spaces": { "description": "Total number of parking spaces in the facility.", "example": 25, "type": [ "integer", "null" ], "examples": [ 25 ] } } }, "AmenitiesSection": { "type": "object", "properties": { "parking": { "description": "Building-wide parking facility — distinct from unit.parking.", "anyOf": [ { "$ref": "#/components/schemas/AmenitiesParking" }, { "type": "null" } ] }, "elevator": { "description": "Building has an elevator.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "intercom": { "description": "Intercom (parlophone) at the entrance.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "digicode": { "description": "Keypad code at the entrance.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "caretaker": { "description": "Caretaker / concierge on site.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "bikeRoom": { "description": "Bicycle storage room.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "disabledAccess": { "description": "Residence-level disabled access.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "gym": { "description": "Shared gym.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "playground": { "description": "Children playground.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "partyHall": { "description": "Shared party hall.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "sportCourt": { "description": "Sport court (tennis, basketball, …).", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "adultGameRoom": { "description": "Adult game room (pool, billiards, …).", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "gatedCommunity": { "description": "Gated community.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "barbecueGrill": { "description": "Shared barbecue grill area.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "swimmingPool": { "description": "Shared swimming pool.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "connectivity": { "description": "Available connectivity options (cable, fiber).", "example": [ "FIBER" ], "type": "array", "items": { "type": "string", "enum": [ "CABLE", "FIBER" ] }, "examples": [ [ "FIBER" ] ] } } }, "AnnexesArea": { "type": "object", "properties": { "unit": { "description": "Override for the annexes unit. Present only when it diverges from area.unit; otherwise inherit the headline.", "example": "SQM", "type": "string", "enum": [ "SQM", "SQFT", "HECTARE", "ACRE" ], "nullable": true, "examples": [ "SQM" ] }, "basement": { "description": "Basement area (value most listings report).", "example": 10, "type": [ "number", "null" ], "examples": [ 10 ] }, "parking": { "description": "Parking area (value most listings report).", "example": 12, "type": [ "number", "null" ], "examples": [ 12 ] } } }, "ApiUsage": { "type": "object", "properties": { "period": { "$ref": "#/components/schemas/ApiUsagePeriod" }, "totals": { "$ref": "#/components/schemas/ApiUsageTotals" }, "timeSeries": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUsageTimeSeriesItem" } }, "byApiKey": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUsageByApiKeyItem" } }, "byRoute": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUsageByRouteItem" } }, "byChannel": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUsageByChannelItem" } }, "byAlert": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUsageByAlertItem" } } } }, "ApiUsage.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "ApiUsage", "examples": [ "ApiUsage" ] }, "attributes": { "type": "object", "properties": { "period": { "$ref": "#/components/schemas/ApiUsagePeriod" }, "totals": { "$ref": "#/components/schemas/ApiUsageTotals" }, "timeSeries": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUsageTimeSeriesItem" } }, "byApiKey": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUsageByApiKeyItem" } }, "byRoute": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUsageByRouteItem" } }, "byChannel": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUsageByChannelItem" } }, "byAlert": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUsageByAlertItem" } } } } }, "required": [ "type", "id" ] }, "ApiUsageByAlertItem": { "type": "object", "properties": { "alertId": { "description": "Id of the alert these notifications came from. Null for notifications sent before the alert was recorded against them; those arrive as a single row.", "example": "4f2e1a7c-9b3d-4e8a-8c1f-2d6b4a8e0c93", "type": [ "string", "null" ], "examples": [ "4f2e1a7c-9b3d-4e8a-8c1f-2d6b4a8e0c93" ] }, "alertName": { "description": "Name of the alert these notifications came from. Empty when the alert is not known.", "example": "Paris 2-bedroom under 500k", "type": "string", "examples": [ "Paris 2-bedroom under 500k" ] }, "channel": { "description": "Channel these notifications were sent over.", "example": "WEBHOOK", "type": "string", "enum": [ "EMAIL", "WEBHOOK" ], "nullable": false, "examples": [ "WEBHOOK" ] }, "notifications": { "description": "Notifications this alert produced over the period.", "example": 1840, "type": "integer", "examples": [ 1840 ] }, "delivered": { "description": "Of those, the ones your endpoint accepted.", "example": 1828, "type": "integer", "examples": [ 1828 ] }, "failed": { "description": "Of those, the ones not accepted within the period.", "example": 12, "type": "integer", "examples": [ 12 ] }, "attempts": { "description": "Delivery attempts made for this alert, retries included.", "example": 1853, "type": "integer", "examples": [ 1853 ] } } }, "ApiUsageByApiKeyItem": { "type": "object", "properties": { "apiKeyId": { "description": "Id of the API key these usage figures belong to. Null for calls made without an API key.", "example": "7c1f0e8a-2b6d-4f3a-9e1c-5a8b2d4f6c10", "type": [ "string", "null" ], "examples": [ "7c1f0e8a-2b6d-4f3a-9e1c-5a8b2d4f6c10" ] }, "apiKeyName": { "description": "Human-readable name of the API key. Null for calls made without an API key.", "example": "Production backend", "type": [ "string", "null" ], "examples": [ "Production backend" ] }, "status": { "description": "Current status of the API key. Null for calls made without an API key.", "example": "active", "type": [ "string", "null" ], "examples": [ "active" ] }, "calls": { "description": "Number of API calls made with this key over the period.", "example": 31540, "type": "integer", "examples": [ 31540 ] }, "results": { "description": "Number of results returned to this key over the period.", "example": 820460, "type": "integer", "examples": [ 820460 ] } } }, "ApiUsageByChannelItem": { "type": "object", "properties": { "channel": { "description": "How the calls were issued: directly against the API, or through the MCP server.", "example": "DIRECT", "type": "string", "enum": [ "DIRECT", "MCP" ], "nullable": false, "examples": [ "DIRECT" ] }, "calls": { "description": "Number of API calls issued through this channel over the period.", "example": 26310, "type": "integer", "examples": [ 26310 ] }, "results": { "description": "Number of results returned through this channel over the period.", "example": 701920, "type": "integer", "examples": [ 701920 ] } } }, "ApiUsageByRouteItem": { "type": "object", "properties": { "route": { "description": "API route these usage figures belong to.", "example": "/properties", "type": "string", "examples": [ "/properties" ] }, "routeType": { "description": "Category of the route. Reported as other for a route that was charged in a period it made no recorded calls in.", "example": "search", "type": "string", "enum": [ "search", "analytics", "admin", "mcp", "other" ], "examples": [ "search" ] }, "calls": { "description": "Number of API calls made to this route over the period.", "example": 26310, "type": "integer", "examples": [ 26310 ] }, "results": { "description": "Number of results returned by this route over the period.", "example": 701920, "type": "integer", "examples": [ 701920 ] }, "credits": { "description": "Credits this route cost over the period. Absent when the account is not billed in credits, and when the report is filtered by API key or channel. A route whose calls fall into more than one category carries the whole cost on its first row and zero on the others, so the column still adds up to the total. A row showing no calls is a charge posted in this period for a call made before it.", "example": 26310, "type": [ "integer", "null" ], "examples": [ 26310 ] } } }, "ApiUsageNotificationCounts": { "type": "object", "properties": { "notifications": { "description": "Notifications sent over the period. Counted once each, however many delivery attempts they took.", "example": 1840, "type": "integer", "examples": [ 1840 ] }, "delivered": { "description": "Notifications your endpoint accepted. A notification retried after a failure counts here once it succeeds, not in both figures.", "example": 1828, "type": "integer", "examples": [ 1828 ] }, "failed": { "description": "Notifications not accepted within the period. A notification still being retried when the period ends counts here until an attempt succeeds.", "example": 12, "type": "integer", "examples": [ 12 ] }, "attempts": { "description": "Delivery attempts made, retries included. Higher than the number of notifications whenever an attempt had to be repeated.", "example": 1853, "type": "integer", "examples": [ 1853 ] } } }, "ApiUsagePeriod": { "type": "object", "properties": { "start": { "description": "Start of the reported period, included.", "example": "2026-01-15T00:00:00Z", "type": "string", "examples": [ "2026-01-15T00:00:00Z" ] }, "end": { "description": "End of the reported period, excluded.", "example": "2026-02-15T00:00:00Z", "type": "string", "examples": [ "2026-02-15T00:00:00Z" ] }, "granularity": { "description": "Time granularity the usage is bucketed by.", "example": "DAY", "type": "string", "enum": [ "YEAR", "QUARTER", "MONTH", "WEEK", "DAY" ], "nullable": false, "examples": [ "DAY" ] }, "notificationsFrom": { "description": "Start of the period the notification figures cover, when notifications are kept for less time than the period asked for. Absent when they cover the whole period.", "example": "2026-01-15T00:00:00Z", "type": [ "string", "null" ], "examples": [ "2026-01-15T00:00:00Z" ] } } }, "ApiUsageTimeSeriesItem": { "type": "object", "properties": { "period": { "description": "Time bucket these figures cover.", "example": "2026-01-15", "type": "string", "examples": [ "2026-01-15" ] }, "calls": { "description": "Number of API calls made during this bucket.", "example": 1620, "type": "integer", "examples": [ 1620 ] }, "results": { "description": "Number of results returned during this bucket.", "example": 42180, "type": "integer", "examples": [ 42180 ] }, "apiKeyId": { "description": "Id of the API key this row covers. Set when groupBy is apiKey; null for calls made without an API key.", "example": "7c1f0e8a-2b6d-4f3a-9e1c-5a8b2d4f6c10", "type": [ "string", "null" ], "examples": [ "7c1f0e8a-2b6d-4f3a-9e1c-5a8b2d4f6c10" ] }, "apiKeyName": { "description": "Name of the API key this row covers. Set when groupBy is apiKey.", "example": "Production backend", "type": [ "string", "null" ], "examples": [ "Production backend" ] }, "route": { "description": "Route this row covers. Set when groupBy is route.", "example": "/properties", "type": [ "string", "null" ], "examples": [ "/properties" ] }, "routeType": { "description": "Type of operation the route performs. Set when groupBy is route.", "example": "search", "type": [ "string", "null" ], "enum": [ "search", "analytics", "admin", "mcp", "other", null ], "examples": [ "search" ] }, "channel": { "description": "Channel the calls were issued through. Set when groupBy is channel.", "example": "DIRECT", "type": "string", "enum": [ "DIRECT", "MCP" ], "nullable": true, "examples": [ "DIRECT" ] }, "webhooks": { "description": "Webhook notifications during this bucket. Absent when groupBy is set, or when the report is filtered by API key or channel, because a notification carries none of those.", "anyOf": [ { "$ref": "#/components/schemas/ApiUsageNotificationCounts" }, { "type": "null" } ] }, "emails": { "description": "Email notifications during this bucket. Absent when groupBy is set, or when the report is filtered by API key or channel, because a notification carries none of those.", "anyOf": [ { "$ref": "#/components/schemas/ApiUsageNotificationCounts" }, { "type": "null" } ] } } }, "ApiUsageTotals": { "type": "object", "properties": { "calls": { "description": "Total number of API calls over the period.", "example": 48230, "type": "integer", "examples": [ 48230 ] }, "results": { "description": "Total number of results returned over the period.", "example": 1264870, "type": "integer", "examples": [ 1264870 ] }, "credits": { "description": "Credits these calls cost over the period. Absent when the account is not billed in credits, and when the report is filtered by API key or channel, because a charge is recorded against the account and not against either.", "example": 48230, "type": [ "integer", "null" ], "examples": [ 48230 ] }, "webhooks": { "description": "Webhook notifications over the period. Absent when the report is filtered by API key or channel, because a notification is recorded against neither.", "anyOf": [ { "$ref": "#/components/schemas/ApiUsageNotificationCounts" }, { "type": "null" } ] }, "emails": { "description": "Email notifications over the period. Absent when the report is filtered by API key or channel, because a notification is recorded against neither.", "anyOf": [ { "$ref": "#/components/schemas/ApiUsageNotificationCounts" }, { "type": "null" } ] } } }, "AreaSection": { "type": "object", "properties": { "displayed": { "description": "Headline surface for the property. Per-dimension value most listings report, surfaces within 2 % counting as one (recency tie-break, largest when no two listings agree): living, total, terrace, balcony, garden, basement, parking, land. displayed is the headline surface — indoor living, fallback to indoor total.", "example": 56, "type": [ "number", "null" ], "examples": [ 56 ] }, "unit": { "description": "Headline unit system for every surface under area. Sub-sections only carry their own unit when it diverges (typical case: SQM building + HECTARE land).", "example": "SQM", "type": "string", "enum": [ "SQM", "SQFT", "HECTARE", "ACRE" ], "nullable": true, "examples": [ "SQM" ] }, "indoor": { "description": "Indoor areas breakdown (living, total, legal).", "anyOf": [ { "$ref": "#/components/schemas/IndoorArea" }, { "type": "null" } ] }, "outdoor": { "description": "Outdoor areas breakdown (terrace, balcony, garden).", "anyOf": [ { "$ref": "#/components/schemas/OutdoorArea" }, { "type": "null" } ] }, "annexes": { "description": "Annexes breakdown (basement, parking).", "anyOf": [ { "$ref": "#/components/schemas/AnnexesArea" }, { "type": "null" } ] }, "land": { "description": "Land area.", "anyOf": [ { "$ref": "#/components/schemas/LandArea" }, { "type": "null" } ] } } }, "BodySection": { "type": "object", "properties": { "title": { "description": "Canonical listing title. Canonical title/description: longest text in the largest hash-cluster of normalized texts across listings; recency tie-break. Sparse per-listing variants only when a listing's text doesn't match the canonical hash.", "example": "Beautiful flat in Paris", "type": [ "string", "null" ], "examples": [ "Beautiful flat in Paris" ] }, "description": { "description": "Canonical listing description. Canonical title/description: longest text in the largest hash-cluster of normalized texts across listings; recency tie-break. Sparse per-listing variants only when a listing's text doesn't match the canonical hash.", "example": "Renovated flat on a quiet street, close to transit and shops.", "type": [ "string", "null" ], "examples": [ "Renovated flat on a quiet street, close to transit and shops." ] } } }, "Building.LegalStatus": { "type": "object", "properties": { "underLegalProceedings": { "description": "Whether the building is currently under legal proceedings.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] } } }, "BuildingSection": { "type": "object", "properties": { "constructionYear": { "description": "Year the building was constructed (value most listings report, else the earliest).", "example": 1980, "type": [ "integer", "null" ], "examples": [ 1980 ] }, "renovationYear": { "description": "Year of the most recent major renovation (value most listings report).", "example": 2020, "type": [ "integer", "null" ], "examples": [ 2020 ] }, "constructionType": { "description": "Building construction type (Haussmannian, modern, …). Most-frequent + recency tie-break.", "example": "HAUSSMANNIAN", "type": "string", "enum": [ "HAUSSMANNIAN", "MODERN", "CONTEMPORARY", "TRADITIONAL", "STONE", "BRICK", "CONCRETE", "WOOD", "MIXED", "OTHER" ], "nullable": true, "examples": [ "HAUSSMANNIAN" ] }, "condition": { "description": "Building condition (structure / common parts). Distinct from unit.condition.", "example": "GOOD", "type": "string", "enum": [ "NEW", "GOOD", "TO_RENOVATE" ], "nullable": true, "examples": [ "GOOD" ] }, "floors": { "description": "Total number of floors in the building (value most listings report).", "example": 6, "type": [ "integer", "null" ], "examples": [ 6 ] }, "numberOfLots": { "description": "Number of lots in the building / copropriété.", "example": 45, "type": [ "integer", "null" ], "examples": [ 45 ] }, "legalStatus": { "description": "Legal status facet (nested so future legal states can be added without a breaking change).", "anyOf": [ { "$ref": "#/components/schemas/Building.LegalStatus" }, { "type": "null" } ] }, "energy": { "description": "Building-level energy equipment (collective heating systems typically). Distinct from unit.energy which describes the apartment-level equipment.", "anyOf": [ { "$ref": "#/components/schemas/UnitEnergy" }, { "type": "null" } ] } } }, "ChangeSection": { "type": "object", "properties": { "attribute": { "description": "The attribute that changed.", "example": "DISPLAYED_PRICE", "type": "string", "enum": [ "DISPLAYED_PRICE", "DISPLAYED_AREA", "DESCRIPTION", "TITLE", "FEATURES", "ROOMS", "BEDROOMS", "ADDRESS", "GEO_POINT", "CITY", "DISTRICT", "NEIGHBORHOOD", "LOCATION_ACCURACY", "PICTURES", "MARKET_PRESENCE" ], "nullable": true, "examples": [ "DISPLAYED_PRICE" ] }, "occurredAt": { "description": "When the change occurred (ISO 8601).", "default": "", "example": "2026-07-20T09:30:00+00:00", "type": "string", "examples": [ "2026-07-20T09:30:00+00:00" ] }, "listingId": { "description": "Id of the listing that carried the change.", "default": "", "example": "019dedb1-fdf4-714c-8392-5b9cfd63cde3", "type": "string", "examples": [ "019dedb1-fdf4-714c-8392-5b9cfd63cde3" ] }, "revisionId": { "description": "Id of the revision the change belongs to. Changes sharing this id were captured together in the same update.", "default": "", "example": "019dedb1-fe02-72a1-9d70-4a1b2c3d4e5f", "type": "string", "examples": [ "019dedb1-fe02-72a1-9d70-4a1b2c3d4e5f" ] }, "variationPercent": { "description": "Signed variation percent for numeric changes such as price or area; a drop is negative. Absent for other attributes.", "example": -5.2, "type": [ "number", "null" ], "examples": [ -5.2 ] }, "numericOld": { "description": "Previous value for numeric changes.", "example": 100000, "type": [ "number", "null" ], "examples": [ 100000 ] }, "numericNew": { "description": "New value for numeric changes.", "example": 90000, "type": [ "number", "null" ], "examples": [ 90000 ] } } }, "Charges": { "type": "object", "properties": { "amount": { "description": "Total charges amount.", "example": 120, "type": [ "number", "null" ], "examples": [ 120 ] }, "currency": { "description": "Currency of the total.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "frequency": { "description": "Billing frequency.", "example": "MONTHLY", "type": "string", "enum": [ "WEEKLY", "MONTHLY", "YEARLY" ], "nullable": true, "examples": [ "MONTHLY" ] }, "details": { "description": "Per-category breakdown deduplicated across listings.", "type": "array", "items": { "$ref": "#/components/schemas/Pricing.ChargeDetail" } } } }, "Condominium": { "type": "object", "properties": { "total": { "description": "Total condominium fee.", "example": 1020, "type": [ "number", "null" ], "examples": [ 1020 ] }, "currency": { "description": "Currency of the total.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "frequency": { "description": "Billing frequency.", "example": "MONTHLY", "type": "string", "enum": [ "WEEKLY", "MONTHLY", "YEARLY" ], "nullable": true, "examples": [ "MONTHLY" ] }, "breakdown": { "description": "Per-category breakdown deduplicated across listings.", "type": "array", "items": { "$ref": "#/components/schemas/CondominiumFee" } } } }, "CondominiumFee": { "type": "object", "properties": { "type": { "description": "Condominium fee category (heating, water, caretaker, …).", "example": "MAINTENANCE", "type": "string", "enum": [ "HEATING", "WATER", "CARETAKER", "MAINTENANCE", "OTHER" ], "nullable": true, "examples": [ "MAINTENANCE" ] }, "amount": { "description": "Fee amount.", "example": 85, "type": [ "number", "null" ], "examples": [ 85 ] }, "currency": { "description": "Currency of the fee.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "frequency": { "description": "Billing frequency.", "example": "MONTHLY", "type": "string", "enum": [ "WEEKLY", "MONTHLY", "YEARLY" ], "nullable": true, "examples": [ "MONTHLY" ] } } }, "ConstraintViolation": { "type": "object", "description": "Unprocessable entity", "properties": { "status": { "default": 422, "type": "integer", "example": 422, "description": "HTTP status code applicable to this problem.", "examples": [ 422 ] }, "detail": { "readOnly": true, "type": "string", "example": "name: This value should not be blank.", "description": "Human-readable explanation specific to this occurrence.", "examples": [ "name: This value should not be blank." ] }, "type": { "readOnly": true, "type": "string", "example": "/validation_errors/c1051bb4-d103-4f74-8988-acbcafc7fdc3", "description": "URI reference identifying the problem type.", "examples": [ "/validation_errors/c1051bb4-d103-4f74-8988-acbcafc7fdc3" ] }, "title": { "readOnly": true, "type": [ "string", "null" ], "example": "Validation Failed", "description": "Short, human-readable summary of the problem.", "examples": [ "Validation Failed" ] }, "instance": { "readOnly": true, "type": [ "string", "null" ], "example": "/alerts", "description": "URI reference identifying the specific occurrence.", "examples": [ "/alerts" ] } } }, "ConstraintViolation.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "ConstraintViolation", "examples": [ "ConstraintViolation" ] }, "attributes": { "type": "object", "properties": { "status": { "default": 422, "type": "integer", "description": "HTTP status code applicable to this problem.", "example": 422, "examples": [ 422 ] }, "detail": { "readOnly": true, "type": "string", "description": "Human-readable explanation specific to this occurrence.", "example": "name: This value should not be blank.", "examples": [ "name: This value should not be blank." ] }, "_type": { "readOnly": true, "type": "string", "description": "URI reference identifying the problem type.", "example": "/validation_errors/c1051bb4-d103-4f74-8988-acbcafc7fdc3", "examples": [ "/validation_errors/c1051bb4-d103-4f74-8988-acbcafc7fdc3" ] }, "title": { "readOnly": true, "type": [ "string", "null" ], "description": "Short, human-readable summary of the problem.", "example": "Validation Failed", "examples": [ "Validation Failed" ] }, "instance": { "readOnly": true, "type": [ "string", "null" ], "description": "URI reference identifying the specific occurrence.", "example": "/alerts", "examples": [ "/alerts" ] } } } }, "required": [ "type", "id" ] }, "DateMutationRange": { "type": "object", "properties": { "after": { "description": "Only transactions on or after this date (YYYY-MM-DD).", "example": "2024-01-01", "type": [ "string", "null" ], "examples": [ "2024-01-01" ] }, "before": { "description": "Only transactions on or before this date (YYYY-MM-DD).", "example": "2024-12-31", "type": [ "string", "null" ], "examples": [ "2024-12-31" ] } } }, "Deposit": { "type": "object", "properties": { "amount": { "description": "Security deposit amount.", "example": 1450, "type": [ "number", "null" ], "examples": [ 1450 ] }, "currency": { "description": "Currency of the deposit.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "months": { "description": "Deposit duration expressed in rent months.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "paidBy": { "description": "Who pays the deposit.", "example": "TENANT", "type": "string", "enum": [ "BUYER", "SELLER", "OWNER", "TENANT" ], "nullable": true, "examples": [ "TENANT" ] } } }, "Error": { "type": "object", "description": "A representation of common errors.", "properties": { "id": { "type": [ "string", "null" ], "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "Unique identifier of this error occurrence.", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "title": { "readOnly": true, "description": "A short, human-readable summary of the problem.", "type": [ "string", "null" ], "example": "Not Found", "examples": [ "Not Found" ] }, "detail": { "readOnly": true, "description": "A human-readable explanation specific to this occurrence of the problem.", "type": [ "string", "null" ], "example": "The requested resource could not be found.", "examples": [ "The requested resource could not be found." ] }, "status": { "type": [ "integer", "null" ], "examples": [ 404 ], "default": 400, "description": "HTTP status code applicable to this problem." }, "instance": { "readOnly": true, "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", "type": [ "string", "null" ], "example": "/properties/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/properties/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "readOnly": true, "description": "A URI reference that identifies the problem type", "type": "string", "example": "/errors/404", "examples": [ "/errors/404" ] }, "meta": { "type": "object", "description": "Non-standard meta-information about the error." }, "source": { "type": "object", "properties": { "pointer": { "type": "string", "example": "/data/attributes/name", "description": "JSON Pointer to the request body element that caused the error.", "examples": [ "/data/attributes/name" ] }, "parameter": { "type": "string", "example": "page", "description": "Query parameter that caused the error.", "examples": [ "page" ] }, "header": { "type": "string", "example": "Authorization", "description": "Request header that caused the error.", "examples": [ "Authorization" ] } }, "description": "References to the request element that caused the error." } } }, "Error.jsonapi": { "properties": { "errors": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "source": { "type": "object", "description": "References to the request element that caused the error." }, "status": { "type": [ "string", "integer", "null" ], "example": 404, "description": "HTTP status code applicable to this problem.", "examples": [ 404 ] } } } ] } } } }, "EventDestination": { "type": "object", "properties": { "url": { "description": "Webhook URL (required when type=webhook). Must be HTTPS. See the alertEvent webhook for the payload, signature and retry behaviour.", "example": "https://your-server.com/webhooks/stream", "type": [ "string", "null" ], "examples": [ "https://your-server.com/webhooks/stream" ] }, "isDefault": { "description": "Whether this is your account default destination. Pass true to promote as default; the previous default is automatically demoted. Your first destination becomes the default automatically.", "default": false, "example": true, "type": "boolean", "examples": [ true ] }, "status": { "readOnly": true, "description": "Circuit breaker status: active or suspended", "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "SUSPENDED" ], "nullable": false }, "signingKey": { "readOnly": true, "description": "HMAC signing key for webhook deliveries. Returned a single time: on the response of the POST that creates the first webhook destination of your account (it is not returned for later destinations and cannot be retrieved again — store it securely). Rotate it from your dashboard.", "example": "whsec_abc123...", "type": [ "string", "null" ], "examples": [ "whsec_abc123..." ] }, "signingKeyHint": { "readOnly": true, "description": "A short fingerprint of the signing key returned above (the first 8 hex characters of its sha256). Keep it: it is what identifies your active key later, and your dashboard shows the same value.", "example": "b75b1473", "type": [ "string", "null" ], "examples": [ "b75b1473" ] }, "id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } } }, "EventDestination.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "EventDestination", "examples": [ "EventDestination" ] }, "attributes": { "type": "object", "properties": { "url": { "description": "Webhook URL (required when type=webhook). Must be HTTPS. See the alertEvent webhook for the payload, signature and retry behaviour.", "example": "https://your-server.com/webhooks/stream", "type": [ "string", "null" ], "examples": [ "https://your-server.com/webhooks/stream" ] }, "isDefault": { "description": "Whether this is your account default destination. Pass true to promote as default; the previous default is automatically demoted. Your first destination becomes the default automatically.", "default": false, "example": true, "type": "boolean", "examples": [ true ] }, "status": { "readOnly": true, "description": "Circuit breaker status: active or suspended", "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "SUSPENDED" ], "nullable": false }, "signingKey": { "readOnly": true, "description": "HMAC signing key for webhook deliveries. Returned a single time: on the response of the POST that creates the first webhook destination of your account (it is not returned for later destinations and cannot be retrieved again — store it securely). Rotate it from your dashboard.", "example": "whsec_abc123...", "type": [ "string", "null" ], "examples": [ "whsec_abc123..." ] }, "signingKeyHint": { "readOnly": true, "description": "A short fingerprint of the signing key returned above (the first 8 hex characters of its sha256). Keep it: it is what identifies your active key later, and your dashboard shows the same value.", "example": "b75b1473", "type": [ "string", "null" ], "examples": [ "b75b1473" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } } } }, "required": [ "type", "id" ] }, "EventNotification": { "type": "object", "properties": { "channel": { "type": "string", "description": "Delivery channel used for this notification.", "example": "WEBHOOK", "enum": [ "EMAIL", "WEBHOOK" ], "nullable": false, "examples": [ "WEBHOOK" ] }, "destinationAddress": { "readOnly": true, "description": "Destination URL or address the notification was sent to.", "example": "https://your-server.com/webhooks/stream", "type": "string", "examples": [ "https://your-server.com/webhooks/stream" ] }, "status": { "type": "string", "description": "Current delivery status.", "example": "DELIVERED", "enum": [ "PENDING", "DELIVERED", "FAILED", "SUSPENDED", "SKIPPED" ], "nullable": false, "examples": [ "DELIVERED" ] }, "attemptNumber": { "readOnly": true, "description": "Number of delivery attempts made so far (including retries).", "example": 1, "type": "integer", "examples": [ 1 ] }, "deliveredAt": { "readOnly": true, "description": "Timestamp of the successful delivery; null while pending or when permanently failed.", "example": "2026-06-03T14:32:10+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-06-03T14:32:10+00:00" ] }, "lastErrorMessage": { "readOnly": true, "description": "Error message from the last failed attempt; null when successfully delivered.", "example": "Connection timed out after 5000ms", "type": [ "string", "null" ], "examples": [ "Connection timed out after 5000ms" ] }, "id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } }, "description": "Data is retained for 12 months, after which it is permanently deleted." }, "EventNotification.jsonapi": { "type": "object", "description": "Data is retained for 12 months, after which it is permanently deleted.", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "EventNotification", "examples": [ "EventNotification" ] }, "attributes": { "type": "object", "properties": { "channel": { "type": "string", "description": "Delivery channel used for this notification.", "example": "WEBHOOK", "enum": [ "EMAIL", "WEBHOOK" ], "nullable": false, "examples": [ "WEBHOOK" ] }, "destinationAddress": { "readOnly": true, "description": "Destination URL or address the notification was sent to.", "example": "https://your-server.com/webhooks/stream", "type": "string", "examples": [ "https://your-server.com/webhooks/stream" ] }, "status": { "type": "string", "description": "Current delivery status.", "example": "DELIVERED", "enum": [ "PENDING", "DELIVERED", "FAILED", "SUSPENDED", "SKIPPED" ], "nullable": false, "examples": [ "DELIVERED" ] }, "attemptNumber": { "readOnly": true, "description": "Number of delivery attempts made so far (including retries).", "example": 1, "type": "integer", "examples": [ 1 ] }, "deliveredAt": { "readOnly": true, "description": "Timestamp of the successful delivery; null while pending or when permanently failed.", "example": "2026-06-03T14:32:10+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-06-03T14:32:10+00:00" ] }, "lastErrorMessage": { "readOnly": true, "description": "Error message from the last failed attempt; null when successfully delivered.", "example": "Connection timed out after 5000ms", "type": [ "string", "null" ], "examples": [ "Connection timed out after 5000ms" ] }, "createdAt": { "readOnly": true, "description": "Creation date.", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "readOnly": true, "description": "Last update date.", "example": "2026-05-20T14:45:00+00:00", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2026-05-20T14:45:00+00:00" ] } } } }, "required": [ "type", "id" ] }, "FavoriteProperty": { "type": "object", "required": [ "propertyId" ], "properties": { "propertyId": { "format": "uuid", "description": "Property id", "externalDocs": { "url": "https://schema.org/identifier" }, "example": "550e8400-e29b-41d4-a716-446655440000", "type": [ "string", "null" ], "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } }, "FavoriteProperty.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "FavoriteProperty", "examples": [ "FavoriteProperty" ] }, "attributes": { "type": "object", "properties": { "propertyId": { "format": "uuid", "description": "Property id", "externalDocs": { "url": "https://schema.org/identifier" }, "example": "550e8400-e29b-41d4-a716-446655440000", "type": [ "string", "null" ], "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] } }, "required": [ "propertyId" ] } }, "required": [ "type", "id" ] }, "GeoJsonGeometry": { "type": "object", "properties": { "type": { "description": "GeoJSON geometry type, spelled exactly as in RFC 7946 and case-sensitive: Point, Polygon or MultiPolygon.", "example": "Point", "type": "string", "enum": [ "Point", "Polygon", "MultiPolygon" ], "nullable": true, "examples": [ "Point" ] }, "coordinates": { "description": "GeoJSON (RFC 7946) coordinates. A position [lon, lat] for Point, an array of linear rings for Polygon, an array of polygons for MultiPolygon.", "type": "array", "items": { "oneOf": [ { "type": "number" }, { "type": "array" } ] }, "example": [ 2.3522, 48.8566 ], "examples": [ [ 2.3522, 48.8566 ] ] } } }, "HousingTax": { "type": "object", "properties": { "amount": { "description": "Tax amount.", "example": 800, "type": [ "number", "null" ], "examples": [ 800 ] }, "currency": { "description": "Currency of the tax.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "frequency": { "description": "Billing frequency.", "example": "YEARLY", "type": "string", "enum": [ "WEEKLY", "MONTHLY", "YEARLY" ], "nullable": true, "examples": [ "YEARLY" ] }, "paidBy": { "description": "Who pays the tax.", "example": "TENANT", "type": "string", "enum": [ "BUYER", "SELLER", "OWNER", "TENANT" ], "nullable": true, "examples": [ "TENANT" ] }, "includedInCharges": { "description": "Whether the tax is already covered by the rental charges.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] } } }, "IndoorArea": { "type": "object", "properties": { "unit": { "description": "Override for the indoor unit. Present only when it diverges from area.unit; otherwise inherit the headline.", "example": "SQM", "type": "string", "enum": [ "SQM", "SQFT", "HECTARE", "ACRE" ], "nullable": true, "examples": [ "SQM" ] }, "legal": { "description": "Legal indoor area (Carrez / Boutin / RERA).", "anyOf": [ { "$ref": "#/components/schemas/IndoorLegalArea" }, { "type": "null" } ] }, "living": { "description": "Living area in the indoor unit (value most listings report).", "example": 56, "type": [ "number", "null" ], "examples": [ 56 ] }, "total": { "description": "Total indoor area in the indoor unit (value most listings report).", "example": 72, "type": [ "number", "null" ], "examples": [ 72 ] } } }, "IndoorLegalArea": { "type": "object", "properties": { "value": { "description": "Legal area value in the indoor unit.", "example": 35, "type": [ "number", "null" ], "examples": [ 35 ] }, "law": { "description": "Legal area framework (Carrez, Boutin, RERA, …).", "example": "CARREZ", "type": "string", "enum": [ "CARREZ", "BOUTIN", "RERA" ], "nullable": true, "examples": [ "CARREZ" ] } } }, "JsonApiCollectionBaseSchema": { "allOf": [ { "$ref": "#/components/schemas/JsonApiCollectionBaseSchemaNoPagination" }, { "type": "object", "properties": { "links": { "type": "object", "properties": { "first": { "type": "string", "format": "iri-reference", "example": "/sources?page=1", "examples": [ "/sources?page=1" ] }, "prev": { "type": "string", "format": "iri-reference", "example": "/sources?page=2", "examples": [ "/sources?page=2" ] }, "next": { "type": "string", "format": "iri-reference", "example": "/sources?page=4", "examples": [ "/sources?page=4" ] }, "last": { "type": "string", "format": "iri-reference", "example": "/sources?page=12", "examples": [ "/sources?page=12" ] } }, "example": { "first": "/sources?page=1", "prev": "/sources?page=2", "next": "/sources?page=4", "last": "/sources?page=12" }, "examples": [ { "first": "/sources?page=1", "prev": "/sources?page=2", "next": "/sources?page=4", "last": "/sources?page=12" } ] }, "meta": { "type": "object", "properties": { "itemsPerPage": { "type": "integer", "minimum": 0, "example": 30, "examples": [ 30 ] }, "currentPage": { "type": "integer", "minimum": 0, "example": 3, "examples": [ 3 ] } } } } } ] }, "JsonApiCollectionBaseSchemaNoPagination": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string", "format": "iri-reference", "example": "/sources?page=3", "examples": [ "/sources?page=3" ] } }, "example": { "self": "/sources?page=3" }, "examples": [ { "self": "/sources?page=3" } ] }, "meta": { "type": "object", "properties": { "totalItems": { "type": "integer", "minimum": 0, "example": 240, "examples": [ 240 ] } } }, "data": { "type": "array" } }, "required": [ "data" ] }, "LandArea": { "type": "object", "properties": { "unit": { "description": "Override for the land unit. Present only when it diverges from area.unit — typical case for properties with land (HECTARE/ACRE while the building is SQM/SQFT).", "example": "HECTARE", "type": "string", "enum": [ "SQM", "SQFT", "HECTARE", "ACRE" ], "nullable": true, "examples": [ "HECTARE" ] }, "value": { "description": "Land area in the land unit (value most listings report).", "example": 320, "type": [ "number", "null" ], "examples": [ 320 ] } } }, "LegalFee": { "type": "object", "properties": { "type": { "description": "Legal fee category (notary, registration, …).", "example": "NOTARY", "type": "string", "enum": [ "NOTARY", "REGISTRATION", "OTHER" ], "nullable": true, "examples": [ "NOTARY" ] }, "currency": { "description": "Currency of the fee.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "amount": { "description": "Fee amount.", "example": 7500, "type": [ "number", "null" ], "examples": [ 7500 ] }, "percentage": { "description": "Fee percentage of the sale price.", "example": 2.5, "type": [ "number", "null" ], "examples": [ 2.5 ] }, "paidBy": { "description": "Who pays the fee.", "example": "BUYER", "type": "string", "enum": [ "BUYER", "SELLER", "OWNER", "TENANT" ], "nullable": true, "examples": [ "BUYER" ] } } }, "Listing.Picture": { "type": "object", "properties": { "url": { "description": "Picture URL.", "default": "", "example": "https://cdn.stream.estate/storage/properties/2026/10/14/01/0199a4c2-7a2b-7f3c-9d5e-4a0b8f6e3c12.webp", "type": "string", "examples": [ "https://cdn.stream.estate/storage/properties/2026/10/14/01/0199a4c2-7a2b-7f3c-9d5e-4a0b8f6e3c12.webp" ] } } }, "ListingAnalytics": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ListingAnalyticsMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListingAnalyticsDataItem" } } } }, "ListingAnalytics.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "ListingAnalytics", "examples": [ "ListingAnalytics" ] }, "attributes": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ListingAnalyticsMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListingAnalyticsDataItem" } } } } }, "required": [ "type", "id" ] }, "ListingAnalyticsDataItem": { "type": "object", "properties": { "group": { "description": "Grouping dimensions this row is aggregated by.", "example": { "city_id": 75056, "property_type": "FLAT" }, "type": "object", "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "string" }, { "type": "null" } ] }, "examples": [ { "city_id": 75056, "property_type": "FLAT" } ] }, "metrics": { "description": "Aggregated metric values for this group.", "example": { "count": 1284, "avg:price": 612500, "avg:price_per_sqm": 11240.5 }, "type": "object", "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "null" } ] }, "examples": [ { "count": 1284, "avg:price": 612500, "avg:price_per_sqm": 11240.5 } ] } } }, "ListingAnalyticsMeta": { "type": "object", "properties": { "sample_size": { "description": "Number of events the aggregation is computed from.", "example": 18452, "type": "integer", "examples": [ 18452 ] }, "min_event_at": { "description": "Earliest event timestamp included in the sample.", "example": "2026-01-01T00:00:00Z", "type": [ "string", "null" ], "examples": [ "2026-01-01T00:00:00Z" ] }, "max_event_at": { "description": "Latest event timestamp included in the sample.", "example": "2026-03-31T23:59:59Z", "type": [ "string", "null" ], "examples": [ "2026-03-31T23:59:59Z" ] } } }, "ListingMarketing": { "type": "object", "properties": { "favorites": { "description": "Number of times the listing was favorited on its source.", "example": 12, "type": [ "integer", "null" ], "examples": [ 12 ] }, "urgent": { "description": "Flagged as urgent by the publisher.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "boosted": { "description": "Boosted ad slot on the source.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "highlighted": { "description": "Highlighted ad slot on the source.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] } } }, "ListingSection": { "type": "object", "properties": { "id": { "description": "Id of the Listing.", "default": "", "example": "019dedb1-ff41-7e5a-bd16-6900cbd8c004", "type": "string", "examples": [ "019dedb1-ff41-7e5a-bd16-6900cbd8c004" ] }, "url": { "description": "URL to the original listing. Absent when the listing comes from a protected source the caller is not allowed to see.", "example": "https://www.example-realestate.com/listings/019dedb1", "type": [ "string", "null" ], "examples": [ "https://www.example-realestate.com/listings/019dedb1" ] }, "source": { "description": "Source the listing comes from.", "anyOf": [ { "$ref": "#/components/schemas/SourceReference" }, { "type": "null" } ] }, "publishedAt": { "description": "Date the listing was first published (ISO 8601).", "example": "2026-04-15T09:00:00+00:00", "type": [ "string", "null" ], "examples": [ "2026-04-15T09:00:00+00:00" ] }, "expiredAt": { "description": "Date the listing expired (ISO 8601).", "example": "2026-07-15T09:00:00+00:00", "type": [ "string", "null" ], "examples": [ "2026-07-15T09:00:00+00:00" ] }, "lastSeenAt": { "description": "Last date the listing was observed alive at the source (ISO 8601). Surfaces listing freshness for clients.", "example": "2026-05-12T08:30:00+00:00", "type": [ "string", "null" ], "examples": [ "2026-05-12T08:30:00+00:00" ] }, "title": { "description": "Variant title, present only when it diverges from property.body.title (different normalized hash).", "example": "Bright 3-room apartment with balcony", "type": [ "string", "null" ], "examples": [ "Bright 3-room apartment with balcony" ] }, "description": { "description": "Variant description, present only when it diverges from property.body.description (different normalized hash).", "example": "Renovated flat on a quiet street, close to transit and shops.", "type": [ "string", "null" ], "examples": [ "Renovated flat on a quiet street, close to transit and shops." ] }, "createdAt": { "description": "Crawl creation date (ISO 8601).", "default": "", "example": "2026-04-15T09:05:00+00:00", "type": "string", "examples": [ "2026-04-15T09:05:00+00:00" ] }, "updatedAt": { "description": "Crawl last-update date (ISO 8601).", "default": "", "example": "2026-05-12T08:30:00+00:00", "type": "string", "examples": [ "2026-05-12T08:30:00+00:00" ] }, "area": { "description": "Variant displayed area, present only when it differs from property.area.displayed.", "example": 54, "type": [ "number", "null" ], "examples": [ 54 ] }, "rooms": { "description": "Variant rooms count, present only when it differs from property.unit.rooms.", "example": 3, "type": [ "integer", "null" ], "examples": [ 3 ] }, "bedrooms": { "description": "Variant bedrooms count, present only when it differs from property.unit.bedrooms.", "example": 2, "type": [ "integer", "null" ], "examples": [ 2 ] }, "bathrooms": { "description": "Variant bathrooms count, present only when it differs from property.unit.bathrooms.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "showerRooms": { "description": "Variant shower-rooms count.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "wc": { "description": "Variant WC count.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "livingRooms": { "description": "Variant living-rooms count.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "kitchens": { "description": "Variant kitchens count.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "floor": { "description": "Variant floor number.", "example": 2, "type": [ "integer", "null" ], "examples": [ 2 ] }, "lastFloor": { "description": "Variant last-floor flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "groundFloor": { "description": "Variant ground-floor flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "gardenFloor": { "description": "Variant garden-floor flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "condition": { "description": "Variant condition, present only when it differs from property.unit.condition.", "example": "TO_RENOVATE", "type": "string", "enum": [ "NEW", "GOOD", "TO_RENOVATE" ], "nullable": true, "examples": [ "TO_RENOVATE" ] }, "furnished": { "description": "Variant furnished flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "disabledAccess": { "description": "Variant disabled-access flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "equippedKitchen": { "description": "Variant equipped-kitchen flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "fireplace": { "description": "Variant fireplace flag.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "airConditioning": { "description": "Variant air-conditioning flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "doubleGlazing": { "description": "Variant double-glazing flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "parquet": { "description": "Variant parquet flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "balcony": { "description": "Variant balcony flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "terrace": { "description": "Variant terrace flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "garden": { "description": "Variant garden flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "dressing": { "description": "Variant dressing-room flag.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "crossing": { "description": "Variant crossing-apartment flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "quiet": { "description": "Variant quiet flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "cellar": { "description": "Variant cellar flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "basement": { "description": "Variant basement flag.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "storage": { "description": "Variant storage-room flag.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "transactionStatus": { "description": "Variant transaction status, present only when it differs from property.transactionStatus.", "example": "SOLD", "type": "string", "enum": [ "AVAILABLE", "UNDER_OFFER", "SOLD", "RENTED", "WITHDRAWN" ], "nullable": true, "examples": [ "SOLD" ] }, "displayedPrice": { "description": "Variant displayed price, present only when it differs from property.pricing.displayed.", "example": 420000, "type": [ "number", "null" ], "examples": [ 420000 ] }, "propertyType": { "description": "Variant property type (rare, indicates upstream data quality issue).", "example": "FLAT", "type": "string", "enum": [ "FLAT", "HOUSE", "BUILDING", "PARKING", "OFFICE", "LAND", "SHOP", "COMMERCIAL_PREMISES" ], "nullable": true, "examples": [ "FLAT" ] }, "transactionType": { "description": "Variant transaction type (rare, indicates upstream data quality issue).", "example": "SELL", "type": "string", "enum": [ "SELL", "RENT" ], "nullable": true, "examples": [ "SELL" ] }, "marketing": { "description": "Source-side marketing signals (favorite count, urgent/boosted/highlighted flags).", "anyOf": [ { "$ref": "#/components/schemas/ListingMarketing" }, { "type": "null" } ] } } }, "LocationAutocomplete.LocationSuggestion": { "type": "object", "description": "API Platform resource for location autocomplete.", "properties": { "name": { "description": "Human-readable display name.", "example": "Paris", "type": "string", "examples": [ "Paris" ] }, "locationType": { "description": "Administrative type.", "example": "MUNICIPALITY", "type": "string", "enum": [ "COUNTRY", "ADMINISTRATIVE_REGION", "ADMINISTRATIVE_SUBREGION", "MUNICIPALITY_GROUP", "MUNICIPALITY", "MUNICIPAL_DISTRICT", "NEIGHBORHOOD", "SUB_MUNICIPALITY", "SUB_NEIGHBOURHOOD" ], "nullable": true, "examples": [ "MUNICIPALITY" ] }, "parentName": { "description": "Immediate parent name (e.g. department for a city).", "example": "Paris", "type": [ "string", "null" ], "examples": [ "Paris" ] }, "regionName": { "description": "Region name, for disambiguation.", "example": "Île-de-France", "type": [ "string", "null" ], "examples": [ "Île-de-France" ] }, "countryCode": { "description": "Country the division belongs to.", "example": "FR", "type": "string", "enum": [ "FR", "BE" ], "nullable": true, "examples": [ "FR" ] }, "postalCode": { "description": "Primary postal code.", "example": "75001", "type": [ "string", "null" ], "examples": [ "75001" ] }, "centroid": { "description": "GeoJSON (RFC 7946) Point for map marker placement.", "example": { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] }, "anyOf": [ { "$ref": "#/components/schemas/GeoJsonGeometry" }, { "type": "null" } ], "examples": [ { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] } ] }, "metadata": { "description": "Additional data (population, hierarchy depth, postal codes, uniqueCode, …).", "example": { "depth": 3, "population": 2102650, "postalCodes": [ "75001", "75002", "75003" ], "uniqueCode": "75056" }, "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "examples": [ { "depth": 3, "population": 2102650, "postalCodes": [ "75001", "75002", "75003" ], "uniqueCode": "75056" } ] }, "id": { "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } }, "LocationSection": { "type": "object", "properties": { "geometry": { "description": "GeoJSON (RFC 7946) point. null when no coordinates are known.", "anyOf": [ { "$ref": "#/components/schemas/GeoJsonGeometry" }, { "type": "null" } ] }, "accuracy": { "description": "Localization accuracy of the coordinates.", "example": "NEIGHBORHOOD", "type": "string", "enum": [ "PRECISE", "STREET", "CITY", "UNKNOWN", "NEIGHBORHOOD", "DISTRICT" ], "nullable": true, "examples": [ "NEIGHBORHOOD" ] }, "address": { "description": "Free-form street address (canonical listing).", "example": "10 rue Eugène Sue", "type": [ "string", "null" ], "examples": [ "10 rue Eugène Sue" ] }, "countryCode": { "description": "ISO 3166-1 alpha-2 country code applying to every administrative slot below.", "example": "FR", "type": "string", "enum": [ "FR", "BE" ], "nullable": true, "examples": [ "FR" ] }, "city": { "description": "Most specific municipality-level division (commune or arrondissement when known).", "anyOf": [ { "$ref": "#/components/schemas/AdministrativeDivisionReference" }, { "type": "null" } ] }, "neighborhood": { "description": "Neighborhood-level division when the listing is qualified down to it.", "anyOf": [ { "$ref": "#/components/schemas/AdministrativeDivisionReference" }, { "type": "null" } ] }, "subNeighborhood": { "description": "Sub-neighborhood-level division (e.g. IRIS in France) when known.", "anyOf": [ { "$ref": "#/components/schemas/AdministrativeDivisionReference" }, { "type": "null" } ] } } }, "OutdoorArea": { "type": "object", "properties": { "unit": { "description": "Override for the outdoor unit. Present only when it diverges from area.unit; otherwise inherit the headline.", "example": "SQM", "type": "string", "enum": [ "SQM", "SQFT", "HECTARE", "ACRE" ], "nullable": true, "examples": [ "SQM" ] }, "terrace": { "description": "Terrace area (value most listings report).", "example": 12, "type": [ "number", "null" ], "examples": [ 12 ] }, "balcony": { "description": "Balcony area (value most listings report).", "example": 4.5, "type": [ "number", "null" ], "examples": [ 4.5 ] }, "garden": { "description": "Garden area (value most listings report).", "example": 80, "type": [ "number", "null" ], "examples": [ 80 ] } } }, "PriceAmountRange": { "type": "object", "properties": { "gte": { "minimum": 0, "description": "Minimum sale price, in cents (greater than or equal).", "example": 20000000, "type": [ "integer", "null" ], "examples": [ 20000000 ] }, "lte": { "minimum": 0, "description": "Maximum sale price, in cents (less than or equal).", "example": 80000000, "type": [ "integer", "null" ], "examples": [ 80000000 ] } } }, "Pricing.ChargeDetail": { "type": "object", "properties": { "type": { "description": "Charge category (heating, water, …).", "example": "HEATING", "type": "string", "enum": [ "HEATING", "WATER", "MAINTENANCE", "GARBAGE", "ELECTRICITY", "GAS", "INTERNET", "OTHER" ], "nullable": true, "examples": [ "HEATING" ] }, "amount": { "description": "Charge amount.", "example": 35, "type": [ "number", "null" ], "examples": [ 35 ] }, "currency": { "description": "Currency of the charge.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] } } }, "Pricing.Rent": { "type": "object", "properties": { "amount": { "description": "Rent amount.", "example": 1450, "type": [ "number", "null" ], "examples": [ 1450 ] }, "currency": { "description": "Currency of the rent.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "frequency": { "description": "Billing frequency.", "example": "MONTHLY", "type": "string", "enum": [ "WEEKLY", "MONTHLY", "YEARLY" ], "nullable": true, "examples": [ "MONTHLY" ] }, "includesCharges": { "description": "Whether charges (utilities, condominium) are included in the rent.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] } } }, "Pricing.RentalFee": { "type": "object", "properties": { "amount": { "description": "Fee amount.", "example": 150, "type": [ "number", "null" ], "examples": [ 150 ] }, "percentage": { "description": "Fee percentage.", "example": 5, "type": [ "number", "null" ], "examples": [ 5 ] }, "currency": { "description": "Currency of the fee.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "paidBy": { "description": "Who pays the fee.", "example": "TENANT", "type": "string", "enum": [ "BUYER", "SELLER", "OWNER", "TENANT" ], "nullable": true, "examples": [ "TENANT" ] } } }, "Pricing.RentalFees": { "type": "object", "properties": { "charges": { "description": "Rental charges (utilities, condominium share).", "anyOf": [ { "$ref": "#/components/schemas/Charges" }, { "type": "null" } ] }, "deposit": { "description": "Security deposit.", "anyOf": [ { "$ref": "#/components/schemas/Deposit" }, { "type": "null" } ] }, "taxes": { "description": "Rental-side taxes.", "anyOf": [ { "$ref": "#/components/schemas/Pricing.RentalTaxes" }, { "type": "null" } ] }, "inventory": { "description": "Inventory fee (move-in/move-out inventory of fixtures).", "anyOf": [ { "$ref": "#/components/schemas/Pricing.RentalFee" }, { "type": "null" } ] }, "agency": { "description": "Agency fee for the rental.", "anyOf": [ { "$ref": "#/components/schemas/Pricing.RentalFee" }, { "type": "null" } ] } } }, "Pricing.RentalPricing": { "type": "object", "properties": { "rent": { "description": "Rent amount + cadence.", "anyOf": [ { "$ref": "#/components/schemas/Pricing.Rent" }, { "type": "null" } ] }, "fees": { "description": "Rental-side fees breakdown.", "anyOf": [ { "$ref": "#/components/schemas/Pricing.RentalFees" }, { "type": "null" } ] } } }, "Pricing.RentalTaxes": { "type": "object", "properties": { "housingTax": { "description": "Housing tax (taxe d'habitation in FR).", "anyOf": [ { "$ref": "#/components/schemas/HousingTax" }, { "type": "null" } ] } } }, "Pricing.SaleFees": { "type": "object", "properties": { "agency": { "description": "Agency fee.", "anyOf": [ { "$ref": "#/components/schemas/AgencyFee" }, { "type": "null" } ] }, "legal": { "description": "Legal fee (notary, registration, …).", "anyOf": [ { "$ref": "#/components/schemas/LegalFee" }, { "type": "null" } ] }, "condominium": { "description": "Condominium charges (charges de copropriété).", "anyOf": [ { "$ref": "#/components/schemas/Condominium" }, { "type": "null" } ] }, "taxes": { "description": "Sale-side taxes.", "anyOf": [ { "$ref": "#/components/schemas/Pricing.SaleTaxes" }, { "type": "null" } ] } } }, "Pricing.SalePricing": { "type": "object", "properties": { "netPrice": { "description": "Net sale price (excluding agency / legal fees).", "example": 320000, "type": [ "number", "null" ], "examples": [ 320000 ] }, "fees": { "description": "Sale-side fees breakdown.", "anyOf": [ { "$ref": "#/components/schemas/Pricing.SaleFees" }, { "type": "null" } ] } } }, "Pricing.SaleTaxes": { "type": "object", "properties": { "propertyTax": { "description": "Annual property tax (taxe foncière in FR).", "anyOf": [ { "$ref": "#/components/schemas/PropertyTax" }, { "type": "null" } ] } } }, "PricingSection": { "type": "object", "properties": { "displayed": { "description": "Canonical displayed price. Headline price (most frequent, recency tie-break) plus full sale/rental fee breakdowns. Each fee is the one most listings report (recency tie-break); breakdown arrays deduplicated by (type, amount).", "example": 400000, "type": [ "number", "null" ], "examples": [ 400000 ] }, "currency": { "description": "Majority currency across listings.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "sale": { "description": "Full sale-side pricing tree (only emitted when transaction.type is SELL).", "anyOf": [ { "$ref": "#/components/schemas/Pricing.SalePricing" }, { "type": "null" } ] }, "rental": { "description": "Full rental-side pricing tree (only emitted when transaction.type is RENT).", "anyOf": [ { "$ref": "#/components/schemas/Pricing.RentalPricing" }, { "type": "null" } ] } } }, "PropertyAddressResolution": { "type": "object", "description": "Beta. Resolves the exact postal address of a property from what its listings carry, through an\nordered chain of sources per country. France only for now.", "properties": { "confidence": { "description": "How sure the resolution is. EXACT: the certificate reference was found in the registry. HIGH: a certificate matches the characteristics and a coincidence is unlikely. MEDIUM and LOW: a probable address. NONE: no address; address and method are null.", "example": "HIGH", "type": "string", "enum": [ "NONE", "LOW", "MEDIUM", "HIGH", "EXACT" ], "nullable": false, "examples": [ "HIGH" ] }, "method": { "description": "The kind of source the address comes from. Null when the confidence is NONE.", "example": "ENERGY_CERTIFICATE_CHARACTERISTICS", "type": "string", "enum": [ "ENERGY_CERTIFICATE_REFERENCE", "ENERGY_CERTIFICATE_CHARACTERISTICS", "CADASTRAL_PARCEL", "REVERSE_GEOCODING" ], "nullable": true, "examples": [ "ENERGY_CERTIFICATE_CHARACTERISTICS" ] }, "address": { "description": "The resolved address. Null when the confidence is NONE.", "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/ResolvedAddress" }, { "type": "null" } ] }, "energyCertificateNumber": { "description": "Reference of the energy certificate the address comes from, to check on the public registry. Present for the certificate methods only.", "example": "2611E0031228S", "type": [ "string", "null" ], "nullable": true, "examples": [ "2611E0031228S" ] }, "algorithmVersion": { "description": "Version of the address resolution logic that produced this answer. Changes to what it answers are listed in the changelog of the API documentation.", "example": 4, "type": "integer", "examples": [ 4 ] } } }, "PropertySearch.PropertySearchResponse.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PropertySearchResult.jsonapi" } }, "meta": { "type": "object", "properties": { "totalItems": { "description": "Total number of matching properties", "default": 0, "example": 1500, "type": "integer", "examples": [ 1500 ] }, "hasNextPage": { "description": "Whether there are more results available", "default": false, "example": true, "type": "boolean", "examples": [ true ] }, "cursor": { "type": "string", "nullable": true, "description": "Opaque continuation token for the next cursor page; null when no more results.", "example": "eyJsYXN0SWQiOjQyMDAwMCwib2Zmc2V0IjoyMH0=", "examples": [ "eyJsYXN0SWQiOjQyMDAwMCwib2Zmc2V0IjoyMH0=" ] }, "pagination": { "type": "object", "additionalProperties": true } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ], "example": "/properties", "examples": [ "/properties" ] } } }, "included": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ListingSection.jsonapi" }, { "$ref": "#/components/schemas/PublisherSection.jsonapi" }, { "$ref": "#/components/schemas/PropertyPublisher.jsonapi" }, { "$ref": "#/components/schemas/SourceSection.jsonapi" } ] }, "example": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Listing", "attributes": { "url": "https://www.example-realestate.com/listings/019dedb1", "publishedAt": "2026-04-15T09:00:00+00:00", "expiredAt": "2026-07-15T09:00:00+00:00", "lastSeenAt": "2026-05-12T08:30:00+00:00", "title": "Bright 3-room apartment with balcony", "description": "Renovated flat on a quiet street, close to transit and shops.", "createdAt": "2026-04-15T09:05:00+00:00", "updatedAt": "2026-05-12T08:30:00+00:00", "area": 54, "rooms": 3, "bedrooms": 2, "bathrooms": 1, "showerRooms": 1, "wc": 1, "livingRooms": 1, "kitchens": 1, "floor": 2, "lastFloor": false, "groundFloor": false, "gardenFloor": false, "condition": "TO_RENOVATE", "furnished": false, "disabledAccess": false, "equippedKitchen": true, "fireplace": true, "airConditioning": false, "doubleGlazing": true, "parquet": true, "balcony": true, "terrace": false, "garden": false, "dressing": true, "crossing": true, "quiet": true, "cellar": true, "basement": true, "storage": true, "transactionStatus": "SOLD", "displayedPrice": 420000, "propertyType": "FLAT", "transactionType": "SELL", "marketing": { "favorites": 12, "urgent": false, "boosted": true, "highlighted": true } }, "relationships": { "publisher": { "data": { "type": "Publisher", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "source": { "data": { "type": "Source", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Publisher", "attributes": { "publisherType": "REAL_ESTATE_AGENCY", "agencyName": "Foncia Paris 18", "professionalCardNumber": "12345", "website": "https://www.foncia-paris18.example.com" }, "links": { "self": "/publishers/3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "PropertyPublisher", "attributes": { "mandate": "EXCLUSIVE", "reference": "REF-AB42", "contact": { "email": "contact@foncia-paris18.example.com", "phone": "+33123456789", "profileUrl": "https://www.example-realestate.com/agencies/foncia-paris18" } }, "relationships": { "property": { "data": { "type": "Property", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "publisher": { "data": { "type": "Publisher", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Source", "attributes": { "slug": "realty-portal" }, "links": { "self": "/sources/3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "examples": [ [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Listing", "attributes": { "url": "https://www.example-realestate.com/listings/019dedb1", "publishedAt": "2026-04-15T09:00:00+00:00", "expiredAt": "2026-07-15T09:00:00+00:00", "lastSeenAt": "2026-05-12T08:30:00+00:00", "title": "Bright 3-room apartment with balcony", "description": "Renovated flat on a quiet street, close to transit and shops.", "createdAt": "2026-04-15T09:05:00+00:00", "updatedAt": "2026-05-12T08:30:00+00:00", "area": 54, "rooms": 3, "bedrooms": 2, "bathrooms": 1, "showerRooms": 1, "wc": 1, "livingRooms": 1, "kitchens": 1, "floor": 2, "lastFloor": false, "groundFloor": false, "gardenFloor": false, "condition": "TO_RENOVATE", "furnished": false, "disabledAccess": false, "equippedKitchen": true, "fireplace": true, "airConditioning": false, "doubleGlazing": true, "parquet": true, "balcony": true, "terrace": false, "garden": false, "dressing": true, "crossing": true, "quiet": true, "cellar": true, "basement": true, "storage": true, "transactionStatus": "SOLD", "displayedPrice": 420000, "propertyType": "FLAT", "transactionType": "SELL", "marketing": { "favorites": 12, "urgent": false, "boosted": true, "highlighted": true } }, "relationships": { "publisher": { "data": { "type": "Publisher", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "source": { "data": { "type": "Source", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Publisher", "attributes": { "publisherType": "REAL_ESTATE_AGENCY", "agencyName": "Foncia Paris 18", "professionalCardNumber": "12345", "website": "https://www.foncia-paris18.example.com" }, "links": { "self": "/publishers/3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "PropertyPublisher", "attributes": { "mandate": "EXCLUSIVE", "reference": "REF-AB42", "contact": { "email": "contact@foncia-paris18.example.com", "phone": "+33123456789", "profileUrl": "https://www.example-realestate.com/agencies/foncia-paris18" } }, "relationships": { "property": { "data": { "type": "Property", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "publisher": { "data": { "type": "Publisher", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Source", "attributes": { "slug": "realty-portal" }, "links": { "self": "/sources/3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ] ] } }, "required": [ "data", "meta", "links" ] }, "PropertySearchResult": { "type": "object", "properties": { "id": { "description": "Id of the property.", "default": "", "example": "019dedb1-fdf4-714c-8392-5b9cfd63cde3", "type": "string", "examples": [ "019dedb1-fdf4-714c-8392-5b9cfd63cde3" ] }, "property": { "description": "Aggregated canonical view of the property (carries the property timestamps).", "$ref": "#/components/schemas/PropertySection" }, "publishers": { "description": "Deduplicated publishers across all listings of the property.", "type": "array", "items": { "$ref": "#/components/schemas/PublisherSection" } }, "listings": { "description": "Per-listing entries, with variants only when they differ from the aggregated property.", "type": "array", "items": { "$ref": "#/components/schemas/ListingSection" } } } }, "PropertySection": { "type": "object", "properties": { "createdAt": { "description": "Crawl creation date (ISO 8601).", "default": "", "example": "2025-01-15T10:30:00+00:00", "type": "string", "examples": [ "2025-01-15T10:30:00+00:00" ] }, "updatedAt": { "description": "Crawl last-update date (ISO 8601).", "default": "", "example": "2025-06-15T12:00:00+00:00", "type": "string", "examples": [ "2025-06-15T12:00:00+00:00" ] }, "expired": { "description": "True when every listing of this property is no longer online. Expired properties are hidden from search results unless explicitly requested.", "default": false, "example": false, "type": "boolean", "examples": [ false ] }, "propertyType": { "description": "Property type. Most frequent property type across listings; ties resolved by the most recently created listing.", "example": "FLAT", "type": "string", "enum": [ "FLAT", "HOUSE", "BUILDING", "PARKING", "OFFICE", "LAND", "SHOP", "COMMERCIAL_PREMISES" ], "nullable": true, "examples": [ "FLAT" ] }, "constructionStatus": { "description": "Construction status of the property. Most frequent construction status across listings; ties resolved by the most recently created listing.", "example": "OLD", "type": "string", "enum": [ "OLD", "NEW", "UNDER_CONSTRUCTION" ], "nullable": true, "examples": [ "OLD" ] }, "transaction": { "description": "Transaction summary (type, status, mandate, saleType, availableAt). Bundles transaction type (most frequent), status (strongest by precedence), saleType (most-frequent + recency) and availableAt (most recent).", "anyOf": [ { "$ref": "#/components/schemas/TransactionSection" }, { "type": "null" } ] }, "area": { "description": "Aggregated area breakdown — headline displayed surface plus indoor / outdoor / annexes / land sub-sections. Per-dimension value most listings report, surfaces within 2 % counting as one (recency tie-break, largest when no two listings agree): living, total, terrace, balcony, garden, basement, parking, land. displayed is the headline surface — indoor living, fallback to indoor total.", "anyOf": [ { "$ref": "#/components/schemas/AreaSection" }, { "type": "null" } ] }, "unit": { "description": "Unit-level facets (counters, floor flags, condition, orientation, feature booleans, parking). Counters take the value most listings report (recency tie-break, max when no two listings agree), logical OR for booleans, union for orientation, most-frequent + recency tie-break for condition.", "anyOf": [ { "$ref": "#/components/schemas/UnitSection" }, { "type": "null" } ] }, "building": { "description": "Building-level facets (construction year, condition, floors, legal status). Value most listings report for constructionYear / renovationYear / floors / numberOfLots (recency tie-break; min for constructionYear and max for the others when no two listings agree), most-frequent + recency for constructionType / condition / energy, logical OR for legalStatus.underLegalProceedings.", "anyOf": [ { "$ref": "#/components/schemas/BuildingSection" }, { "type": "null" } ] }, "amenities": { "description": "Residence-level amenities (elevator, pool, caretaker, parking facility, connectivity). Logical OR for boolean amenities, most-frequent + recency for parking.type, value most listings report for parking.spaces (recency tie-break, max when no two listings agree), deduplicated union for connectivity.", "anyOf": [ { "$ref": "#/components/schemas/AmenitiesSection" }, { "type": "null" } ] }, "body": { "description": "Canonical body (title + description). Canonical title/description: longest text in the largest hash-cluster of normalized texts across listings; recency tie-break. Sparse per-listing variants only when a listing's text doesn't match the canonical hash.", "anyOf": [ { "$ref": "#/components/schemas/BodySection" }, { "type": "null" } ] }, "pricing": { "description": "Pricing summary. Headline price (most frequent, recency tie-break) plus full sale/rental fee breakdowns. Each fee is the one most listings report (recency tie-break); breakdown arrays deduplicated by (type, amount).", "anyOf": [ { "$ref": "#/components/schemas/PricingSection" }, { "type": "null" } ] }, "location": { "description": "Location summary (geometry + administrative slots). Location built from the most precisely localized listing. Coordinates are the listing geo-point when accuracy is PRECISE or STREET, otherwise the centroid of the deepest qualified administrative division. The administrativeDivisions list reflects that division's root→leaf hierarchy.", "anyOf": [ { "$ref": "#/components/schemas/LocationSection" }, { "type": "null" } ] }, "pictures": { "description": "Deduplicated pictures across all listings of the property. Union of all listings' pictures, collapsed via perceptual-hash Hamming distance (≤ 10 bits). Canonical per cluster: lowest position, then earliest createdAt.", "type": "array", "items": { "$ref": "#/components/schemas/Listing.Picture" } }, "changes": { "description": "Recent attribute changes across the property listings (price drops, area changes, update markers), newest first.", "type": "array", "items": { "$ref": "#/components/schemas/ChangeSection" } } } }, "PropertyTax": { "type": "object", "properties": { "amount": { "description": "Tax amount.", "example": 1200, "type": [ "number", "null" ], "examples": [ 1200 ] }, "currency": { "description": "Currency of the tax.", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": true, "examples": [ "EUR" ] }, "frequency": { "description": "Billing frequency.", "example": "YEARLY", "type": "string", "enum": [ "WEEKLY", "MONTHLY", "YEARLY" ], "nullable": true, "examples": [ "YEARLY" ] }, "paidBy": { "description": "Who pays the tax.", "example": "OWNER", "type": "string", "enum": [ "BUYER", "SELLER", "OWNER", "TENANT" ], "nullable": true, "examples": [ "OWNER" ] } } }, "PropertyUrlLookup": { "type": "object", "description": "Points at the property a listing URL belongs to, without its data: reading the property is a second,\nseparately priced call. A match costs one result; a URL we do not know answers 404 and costs nothing.", "properties": { "id": { "description": "Id of the property published at the URL.", "example": "019dedb1-ff41-7e5a-bd16-6900cbd8c000", "type": "string", "examples": [ "019dedb1-ff41-7e5a-bd16-6900cbd8c000" ] }, "property": { "description": "The property published at the URL. Fetch it to read its data.", "example": "/properties/019dedb1-ff41-7e5a-bd16-6900cbd8c000", "type": "string", "format": "iri-reference", "examples": [ "/properties/019dedb1-ff41-7e5a-bd16-6900cbd8c000" ] } } }, "PropertyUrlLookup.PropertyUrlLookupInput": { "type": "object", "description": "Points at the property a listing URL belongs to, without its data: reading the property is a second,\nseparately priced call. A match costs one result; a URL we do not know answers 404 and costs nothing.", "required": [ "url" ], "properties": { "url": { "format": "uri", "maxLength": 2083, "description": "URL of the listing, as published by its source.", "externalDocs": { "url": "https://schema.org/url" }, "example": "https://www.example-realestate.com/listings/019dedb1", "type": "string", "examples": [ "https://www.example-realestate.com/listings/019dedb1" ] } } }, "PropertyUrlLookup.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "PropertyUrlLookup", "examples": [ "PropertyUrlLookup" ] }, "attributes": { "type": "object", "properties": [] }, "relationships": { "type": "object", "properties": { "property": { "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "example": "Property", "examples": [ "Property" ] }, "id": { "type": "string", "format": "iri-reference", "example": "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } ], "example": { "type": "Property", "id": "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "examples": [ { "type": "Property", "id": "/propertys/3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } } } } } }, "required": [ "type", "id" ] }, "Publisher": { "type": "object", "properties": { "publisherType": { "readOnly": true, "description": "Kind of publisher (private individual, agency, etc.).", "example": "REAL_ESTATE_AGENCY", "type": "string", "enum": [ "PRIVATE_INDIVIDUAL", "REAL_ESTATE_AGENCY", "COMMERCIAL_AGENT", "MANDATED_AGENT", "PROFESSIONAL_UNKNOWN" ], "nullable": true, "examples": [ "REAL_ESTATE_AGENCY" ] }, "agencyName": { "readOnly": true, "description": "Display name of the agency.", "example": "Foncia Paris 18", "type": [ "string", "null" ], "examples": [ "Foncia Paris 18" ] }, "professionalCardNumber": { "readOnly": true, "description": "Professional card number (e.g. \"carte T\" in France).", "example": "12345", "type": [ "string", "null" ], "examples": [ "12345" ] }, "website": { "readOnly": true, "description": "Public website of the publisher.", "example": "https://www.foncia-paris18.example.com", "type": [ "string", "null" ], "examples": [ "https://www.foncia-paris18.example.com" ] }, "id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } }, "Publisher.Contact": { "type": "object", "properties": { "email": { "description": "Contact email.", "example": "contact@foncia-paris18.example.com", "type": [ "string", "null" ], "examples": [ "contact@foncia-paris18.example.com" ] }, "phone": { "description": "Contact phone number.", "example": "+33123456789", "type": [ "string", "null" ], "examples": [ "+33123456789" ] }, "profileUrl": { "description": "Public profile URL on the source platform.", "example": "https://www.example-realestate.com/agencies/foncia-paris18", "type": [ "string", "null" ], "examples": [ "https://www.example-realestate.com/agencies/foncia-paris18" ] } } }, "Publisher.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "Publisher", "examples": [ "Publisher" ] }, "attributes": { "type": "object", "properties": { "publisherType": { "readOnly": true, "description": "Kind of publisher (private individual, agency, etc.).", "example": "REAL_ESTATE_AGENCY", "type": "string", "enum": [ "PRIVATE_INDIVIDUAL", "REAL_ESTATE_AGENCY", "COMMERCIAL_AGENT", "MANDATED_AGENT", "PROFESSIONAL_UNKNOWN" ], "nullable": true, "examples": [ "REAL_ESTATE_AGENCY" ] }, "agencyName": { "readOnly": true, "description": "Display name of the agency.", "example": "Foncia Paris 18", "type": [ "string", "null" ], "examples": [ "Foncia Paris 18" ] }, "professionalCardNumber": { "readOnly": true, "description": "Professional card number (e.g. \"carte T\" in France).", "example": "12345", "type": [ "string", "null" ], "examples": [ "12345" ] }, "website": { "readOnly": true, "description": "Public website of the publisher.", "example": "https://www.foncia-paris18.example.com", "type": [ "string", "null" ], "examples": [ "https://www.foncia-paris18.example.com" ] } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ], "example": "/publishers/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/publishers/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "required": [ "type", "id" ] }, "PublisherSection": { "type": "object", "properties": { "id": { "description": "Id of the Publisher.", "default": "", "example": "019d0000-0000-7000-8000-000000000001", "type": "string", "examples": [ "019d0000-0000-7000-8000-000000000001" ] }, "publisherType": { "description": "Publisher type.", "example": "REAL_ESTATE_AGENCY", "type": "string", "enum": [ "PRIVATE_INDIVIDUAL", "REAL_ESTATE_AGENCY", "COMMERCIAL_AGENT", "MANDATED_AGENT", "PROFESSIONAL_UNKNOWN" ], "nullable": true, "examples": [ "REAL_ESTATE_AGENCY" ] }, "agencyName": { "description": "Agency name (when applicable).", "example": "Foncia Paris 18", "type": [ "string", "null" ], "examples": [ "Foncia Paris 18" ] }, "professionalCardNumber": { "description": "Professional card number (FR: carte T).", "example": "12345", "type": [ "string", "null" ], "examples": [ "12345" ] }, "website": { "description": "Publisher website.", "example": "https://www.foncia-paris18.example.com", "type": [ "string", "null" ], "examples": [ "https://www.foncia-paris18.example.com" ] }, "mandate": { "description": "Canonical mandate the publisher uses on this property. Publishers grouped by id; mandate and publishing reference are single canonical values (most frequent + tie-break by most recent listing); contact is the most recently verified one.", "example": "EXCLUSIVE", "type": "string", "enum": [ "NON_EXCLUSIVE", "EXCLUSIVE", "SEMI_EXCLUSIVE" ], "nullable": true, "examples": [ "EXCLUSIVE" ] }, "reference": { "description": "Canonical reference the publisher uses on this property (the agency's internal listing reference, \"publishing reference\" in legacy parlance).", "example": "REF-AB42", "type": [ "string", "null" ], "examples": [ "REF-AB42" ] }, "contact": { "description": "Most recently verified contact information for this publisher.", "anyOf": [ { "$ref": "#/components/schemas/Publisher.Contact" }, { "type": "null" } ] } } }, "ResolvedAddress": { "type": "object", "properties": { "label": { "description": "Full address on one line.", "example": "12 Rue des Lilas 69003 Lyon", "type": "string", "examples": [ "12 Rue des Lilas 69003 Lyon" ] }, "houseNumber": { "description": "House number, when the address has one.", "example": "12", "type": [ "string", "null" ], "examples": [ "12" ] }, "street": { "description": "Street name.", "example": "Rue des Lilas", "type": [ "string", "null" ], "examples": [ "Rue des Lilas" ] }, "postcode": { "description": "Postal code.", "example": "69003", "type": [ "string", "null" ], "examples": [ "69003" ] }, "cityCode": { "description": "National city code (INSEE code in France).", "example": "69383", "type": [ "string", "null" ], "examples": [ "69383" ] }, "city": { "description": "City name.", "example": "Lyon", "type": [ "string", "null" ], "examples": [ "Lyon" ] }, "country": { "description": "Country of the address.", "example": "FR", "type": "string", "enum": [ "FR", "BE" ], "nullable": false, "examples": [ "FR" ] }, "latitude": { "description": "Latitude of the address.", "example": 45.7578, "type": [ "number", "null" ], "examples": [ 45.7578 ] }, "longitude": { "description": "Longitude of the address.", "example": 4.852, "type": [ "number", "null" ], "examples": [ 4.852 ] } } }, "Source": { "type": "object", "properties": { "name": { "example": "Realty Portal", "type": "string", "description": "Display name of the source the listing was crawled from.", "examples": [ "Realty Portal" ] }, "domain": { "example": "realty-portal.com", "type": "string", "description": "Primary domain of the source.", "examples": [ "realty-portal.com" ] }, "id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } }, "Source.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "Source", "examples": [ "Source" ] }, "attributes": { "type": "object", "properties": { "name": { "example": "Realty Portal", "type": "string", "description": "Display name of the source the listing was crawled from.", "examples": [ "Realty Portal" ] }, "domain": { "example": "realty-portal.com", "type": "string", "description": "Primary domain of the source.", "examples": [ "realty-portal.com" ] } } } }, "required": [ "type", "id" ] }, "SourceCategory": { "type": "object", "properties": { "name": { "description": "Human-readable category name.", "example": "Real Estate Networks", "type": "string", "examples": [ "Real Estate Networks" ] }, "id": { "readOnly": true, "description": "Public unique identifier (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string", "format": "uuid", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } }, "SourceCategory.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "SourceCategory", "examples": [ "SourceCategory" ] }, "attributes": { "type": "object", "properties": { "name": { "description": "Human-readable category name.", "example": "Real Estate Networks", "type": "string", "examples": [ "Real Estate Networks" ] } } } }, "required": [ "type", "id" ] }, "SourceReference": { "type": "object", "properties": { "iri": { "description": "Canonical IRI of the Source resource.", "default": "", "example": "/sources/019d0000-0000-7000-8000-000000000001", "type": "string", "examples": [ "/sources/019d0000-0000-7000-8000-000000000001" ] }, "uuid": { "description": "Source id.", "default": "", "example": "019d0000-0000-7000-8000-000000000001", "type": "string", "examples": [ "019d0000-0000-7000-8000-000000000001" ] }, "slug": { "description": "Source slug.", "default": "", "example": "leboncoin", "type": "string", "examples": [ "leboncoin" ] } } }, "Transaction.TransactionResult.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "Transaction.TransactionResult", "examples": [ "Transaction.TransactionResult" ] }, "attributes": { "type": "object", "properties": { "source": { "description": "Source the transaction was collected from.", "default": "FR_DVF", "example": "FR_DVF", "type": "string", "enum": [ "FR_DVF", "FR_NOTARIES" ], "nullable": false, "examples": [ "FR_DVF" ] }, "externalRef": { "description": "Stable reference of the transaction in its originating source.", "default": "", "example": "2024-123456", "type": "string", "examples": [ "2024-123456" ] }, "dateMutation": { "description": "Date the mutation was recorded (YYYY-MM-DD).", "default": "", "example": "2024-03-15", "type": "string", "examples": [ "2024-03-15" ] }, "nature": { "description": "Legal nature of the mutation.", "default": "SALE", "example": "SALE", "type": "string", "enum": [ "SALE", "OFF_PLAN_SALE", "AUCTION", "EXPROPRIATION", "EXCHANGE", "OTHER" ], "nullable": false, "examples": [ "SALE" ] }, "propertyType": { "description": "Canonical property type of the transaction.", "default": "FLAT", "example": "FLAT", "type": "string", "enum": [ "FLAT", "HOUSE", "BUILDING", "PARKING", "OFFICE", "LAND", "SHOP", "COMMERCIAL_PREMISES" ], "nullable": false, "examples": [ "FLAT" ] }, "price": { "description": "Price block.", "$ref": "#/components/schemas/TransactionPrice" }, "areas": { "description": "Area block.", "$ref": "#/components/schemas/TransactionAreas" }, "location": { "description": "Location block.", "$ref": "#/components/schemas/TransactionLocation" }, "address": { "description": "Structured address parts, when known.", "example": { "streetNumber": "10", "streetName": "Rue de Rivoli" }, "type": "object", "additionalProperties": true, "examples": [ { "streetNumber": "10", "streetName": "Rue de Rivoli" } ] }, "cadastralRef": { "description": "Cadastral parcel reference, when known.", "example": "75101000AB0001", "type": [ "string", "null" ], "examples": [ "75101000AB0001" ] }, "lots": { "description": "Breakdown of the lots that make up the mutation.", "example": [ { "role": "MAIN", "kind": "FLAT" } ], "type": "array", "items": { "type": "object", "additionalProperties": true }, "examples": [ [ { "role": "MAIN", "kind": "FLAT" } ] ] }, "building": { "description": "Building-level characteristics, when known.", "example": { "constructionEra": "1948-1974", "elevator": true }, "type": "object", "additionalProperties": true, "examples": [ { "constructionEra": "1948-1974", "elevator": true } ] }, "amenities": { "description": "Amenity flags, when known.", "example": { "balcony": true, "cellar": true }, "type": "object", "additionalProperties": true, "examples": [ { "balcony": true, "cellar": true } ] }, "createdAt": { "description": "Creation timestamp (ISO 8601).", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "description": "Last update timestamp (ISO 8601).", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "examples": [ "2026-01-15T10:30:00+00:00" ] }, "matched": { "description": "Present when a duplicate from another source was reconciled into this row.", "anyOf": [ { "$ref": "#/components/schemas/TransactionMatch" }, { "type": "null" } ] }, "sourcePayload": { "description": "Raw source payload. Returned on the item endpoint only, and only to authorized service accounts.", "example": { "id_mutation": "2024-123456", "type_local": "Appartement" }, "type": "object", "additionalProperties": true, "examples": [ { "id_mutation": "2024-123456", "type_local": "Appartement" } ] } } } }, "required": [ "type", "id" ] }, "Transaction.TransactionSearchRequestInput": { "type": "object", "description": "Public API for closed real-estate transactions.", "properties": { "dateMutation": { "description": "Filter by mutation date range (inclusive).", "anyOf": [ { "$ref": "#/components/schemas/DateMutationRange" }, { "type": "null" } ] }, "propertyType": { "description": "Property types the transaction must match (any of the listed types).", "example": [ "FLAT", "HOUSE" ], "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "FLAT", "HOUSE", "BUILDING", "PARKING", "OFFICE", "LAND", "SHOP", "COMMERCIAL_PREMISES" ] }, "examples": [ [ "FLAT", "HOUSE" ] ] }, "priceAmount": { "description": "Filter by sale price range, in cents.", "anyOf": [ { "$ref": "#/components/schemas/PriceAmountRange" }, { "type": "null" } ] }, "city": { "format": "uuid", "description": "City id to restrict results to.", "externalDocs": { "url": "https://schema.org/identifier" }, "example": "019476e2-8d1f-7a3c-9b2e-1f6a2c4e8b90", "type": [ "string", "null" ], "examples": [ "019476e2-8d1f-7a3c-9b2e-1f6a2c4e8b90" ] }, "district": { "format": "uuid", "description": "District id to restrict results to.", "externalDocs": { "url": "https://schema.org/identifier" }, "example": "019476e2-9a2b-7c4d-8e5f-2a3b4c5d6e7f", "type": [ "string", "null" ], "examples": [ "019476e2-9a2b-7c4d-8e5f-2a3b4c5d6e7f" ] }, "neighborhood": { "format": "uuid", "description": "Neighborhood id to restrict results to.", "externalDocs": { "url": "https://schema.org/identifier" }, "example": "019476e2-ab3c-7d5e-9f60-3b4c5d6e7f80", "type": [ "string", "null" ], "examples": [ "019476e2-ab3c-7d5e-9f60-3b4c5d6e7f80" ] }, "geoshape": { "description": "GeoJSON polygon; only transactions whose point falls inside the polygon are returned.", "example": { "type": "Polygon", "coordinates": [ [ [ 2.32, 48.85 ], [ 2.36, 48.85 ], [ 2.36, 48.87 ], [ 2.32, 48.87 ], [ 2.32, 48.85 ] ] ] }, "type": "object", "additionalProperties": true, "examples": [ { "type": "Polygon", "coordinates": [ [ [ 2.32, 48.85 ], [ 2.36, 48.85 ], [ 2.36, 48.87 ], [ 2.32, 48.87 ], [ 2.32, 48.85 ] ] ] } ] }, "page": { "description": "Cursor pagination controls.", "anyOf": [ { "$ref": "#/components/schemas/TransactionPage" }, { "type": "null" } ] } } }, "Transaction.TransactionSearchRequestInput.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "Transaction.TransactionSearchRequestInput", "examples": [ "Transaction.TransactionSearchRequestInput" ] }, "attributes": { "type": "object", "properties": { "dateMutation": { "description": "Filter by mutation date range (inclusive).", "anyOf": [ { "$ref": "#/components/schemas/DateMutationRange" }, { "type": "null" } ] }, "propertyType": { "description": "Property types the transaction must match (any of the listed types).", "example": [ "FLAT", "HOUSE" ], "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "FLAT", "HOUSE", "BUILDING", "PARKING", "OFFICE", "LAND", "SHOP", "COMMERCIAL_PREMISES" ] }, "examples": [ [ "FLAT", "HOUSE" ] ] }, "priceAmount": { "description": "Filter by sale price range, in cents.", "anyOf": [ { "$ref": "#/components/schemas/PriceAmountRange" }, { "type": "null" } ] }, "city": { "format": "uuid", "description": "City id to restrict results to.", "externalDocs": { "url": "https://schema.org/identifier" }, "example": "019476e2-8d1f-7a3c-9b2e-1f6a2c4e8b90", "type": [ "string", "null" ], "examples": [ "019476e2-8d1f-7a3c-9b2e-1f6a2c4e8b90" ] }, "district": { "format": "uuid", "description": "District id to restrict results to.", "externalDocs": { "url": "https://schema.org/identifier" }, "example": "019476e2-9a2b-7c4d-8e5f-2a3b4c5d6e7f", "type": [ "string", "null" ], "examples": [ "019476e2-9a2b-7c4d-8e5f-2a3b4c5d6e7f" ] }, "neighborhood": { "format": "uuid", "description": "Neighborhood id to restrict results to.", "externalDocs": { "url": "https://schema.org/identifier" }, "example": "019476e2-ab3c-7d5e-9f60-3b4c5d6e7f80", "type": [ "string", "null" ], "examples": [ "019476e2-ab3c-7d5e-9f60-3b4c5d6e7f80" ] }, "geoshape": { "description": "GeoJSON polygon; only transactions whose point falls inside the polygon are returned.", "example": { "type": "Polygon", "coordinates": [ [ [ 2.32, 48.85 ], [ 2.36, 48.85 ], [ 2.36, 48.87 ], [ 2.32, 48.87 ], [ 2.32, 48.85 ] ] ] }, "type": "object", "additionalProperties": true, "examples": [ { "type": "Polygon", "coordinates": [ [ [ 2.32, 48.85 ], [ 2.36, 48.85 ], [ 2.36, 48.87 ], [ 2.32, 48.87 ], [ 2.32, 48.85 ] ] ] } ] }, "page": { "description": "Cursor pagination controls.", "anyOf": [ { "$ref": "#/components/schemas/TransactionPage" }, { "type": "null" } ] } } } }, "required": [ "type" ] }, "Transaction.TransactionSearchResponse": { "type": "object", "description": "Public API for closed real-estate transactions.", "properties": { "data": { "description": "Transactions matching the search on this page.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionResult" } }, "meta": { "description": "Pagination metadata.", "$ref": "#/components/schemas/TransactionSearchMeta" } } }, "Transaction.TransactionSearchResponse.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "example": "Transaction.TransactionSearchResponse", "examples": [ "Transaction.TransactionSearchResponse" ] }, "attributes": { "type": "object", "properties": { "data": { "description": "Transactions matching the search on this page.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionResult" } }, "meta": { "description": "Pagination metadata.", "$ref": "#/components/schemas/TransactionSearchMeta" } } } }, "required": [ "type", "id" ] }, "TransactionAreas": { "type": "object", "properties": { "livingAreaSqm": { "description": "Living area of the main lot, in square metres.", "example": 65, "type": [ "integer", "null" ], "examples": [ 65 ] }, "landAreaSqm": { "description": "Land area, in square metres.", "example": 200, "type": [ "integer", "null" ], "examples": [ 200 ] }, "roomsCount": { "description": "Number of rooms.", "example": 3, "type": [ "integer", "null" ], "examples": [ 3 ] } } }, "TransactionGeoPoint": { "type": "object", "properties": { "lon": { "description": "Longitude in decimal degrees.", "default": 0, "example": 2.3522, "type": "number", "examples": [ 2.3522 ] }, "lat": { "description": "Latitude in decimal degrees.", "default": 0, "example": 48.8566, "type": "number", "examples": [ 48.8566 ] } } }, "TransactionLocation": { "type": "object", "properties": { "cityId": { "description": "City id, when resolved.", "example": "019476e2-8d1f-7a3c-9b2e-1f6a2c4e8b90", "type": [ "string", "null" ], "examples": [ "019476e2-8d1f-7a3c-9b2e-1f6a2c4e8b90" ] }, "districtId": { "description": "District id, when resolved.", "example": "019476e2-9a2b-7c4d-8e5f-2a3b4c5d6e7f", "type": [ "string", "null" ], "examples": [ "019476e2-9a2b-7c4d-8e5f-2a3b4c5d6e7f" ] }, "neighborhoodId": { "description": "Neighborhood id, when resolved.", "example": "019476e2-ab3c-7d5e-9f60-3b4c5d6e7f80", "type": [ "string", "null" ], "examples": [ "019476e2-ab3c-7d5e-9f60-3b4c5d6e7f80" ] }, "geoPoint": { "description": "Geographic point, when known.", "anyOf": [ { "$ref": "#/components/schemas/TransactionGeoPoint" }, { "type": "null" } ] } } }, "TransactionMatch": { "type": "object", "properties": { "withTransactionId": { "description": "Id of the suppressed duplicate transaction this row was reconciled with.", "default": "", "example": "019476e2-cd4e-7f70-a180-4c5d6e7f8091", "type": "string", "examples": [ "019476e2-cd4e-7f70-a180-4c5d6e7f8091" ] }, "score": { "description": "Confidence score of the match, from 0 to 1.", "default": 0, "example": 0.95, "type": "number", "examples": [ 0.95 ] }, "mergedFields": { "description": "Fields that were filled from the suppressed duplicate.", "example": [ "building", "amenities" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "building", "amenities" ] ] } } }, "TransactionPage": { "type": "object", "properties": { "cursor": { "description": "Opaque cursor returned as meta.nextCursor by the previous response. Omit for the first page.", "example": "eyJ1dWlkIjoiMDE5NDc2ZTItOGQxZi03YTNjLTliMmUtMWY2YTJjNGU4YjkwIiwiZGF0ZSI6IjIwMjQtMDMtMTUifQ==", "type": [ "string", "null" ], "examples": [ "eyJ1dWlkIjoiMDE5NDc2ZTItOGQxZi03YTNjLTliMmUtMWY2YTJjNGU4YjkwIiwiZGF0ZSI6IjIwMjQtMDMtMTUifQ==" ] }, "size": { "minimum": 1, "description": "Number of items per page, from 1 to 100. Defaults to 20.", "example": 20, "type": [ "integer", "null" ], "examples": [ 20 ] } } }, "TransactionPrice": { "type": "object", "properties": { "amountCents": { "description": "Sale price in the smallest currency unit (cents for euros).", "default": 0, "example": 45000000, "type": "integer", "examples": [ 45000000 ] }, "currency": { "description": "Currency of the sale price.", "default": "EUR", "example": "EUR", "type": "string", "enum": [ "EUR", "USD" ], "nullable": false, "examples": [ "EUR" ] }, "pricePerSqmCents": { "description": "Price per square metre of living area, in cents. Null when it cannot be derived.", "example": 692307, "type": [ "integer", "null" ], "examples": [ 692307 ] } } }, "TransactionResult": { "type": "object", "properties": { "id": { "description": "Transaction id.", "default": "", "example": "019476e2-8d1f-7a3c-9b2e-1f6a2c4e8b90", "type": "string", "examples": [ "019476e2-8d1f-7a3c-9b2e-1f6a2c4e8b90" ] }, "source": { "description": "Source the transaction was collected from.", "default": "FR_DVF", "example": "FR_DVF", "type": "string", "enum": [ "FR_DVF", "FR_NOTARIES" ], "nullable": false, "examples": [ "FR_DVF" ] }, "externalRef": { "description": "Stable reference of the transaction in its originating source.", "default": "", "example": "2024-123456", "type": "string", "examples": [ "2024-123456" ] }, "dateMutation": { "description": "Date the mutation was recorded (YYYY-MM-DD).", "default": "", "example": "2024-03-15", "type": "string", "examples": [ "2024-03-15" ] }, "nature": { "description": "Legal nature of the mutation.", "default": "SALE", "example": "SALE", "type": "string", "enum": [ "SALE", "OFF_PLAN_SALE", "AUCTION", "EXPROPRIATION", "EXCHANGE", "OTHER" ], "nullable": false, "examples": [ "SALE" ] }, "propertyType": { "description": "Canonical property type of the transaction.", "default": "FLAT", "example": "FLAT", "type": "string", "enum": [ "FLAT", "HOUSE", "BUILDING", "PARKING", "OFFICE", "LAND", "SHOP", "COMMERCIAL_PREMISES" ], "nullable": false, "examples": [ "FLAT" ] }, "price": { "description": "Price block.", "$ref": "#/components/schemas/TransactionPrice" }, "areas": { "description": "Area block.", "$ref": "#/components/schemas/TransactionAreas" }, "location": { "description": "Location block.", "$ref": "#/components/schemas/TransactionLocation" }, "address": { "description": "Structured address parts, when known.", "example": { "streetNumber": "10", "streetName": "Rue de Rivoli" }, "type": "object", "additionalProperties": true, "examples": [ { "streetNumber": "10", "streetName": "Rue de Rivoli" } ] }, "cadastralRef": { "description": "Cadastral parcel reference, when known.", "example": "75101000AB0001", "type": [ "string", "null" ], "examples": [ "75101000AB0001" ] }, "lots": { "description": "Breakdown of the lots that make up the mutation.", "example": [ { "role": "MAIN", "kind": "FLAT" } ], "type": "array", "items": { "type": "object", "additionalProperties": true }, "examples": [ [ { "role": "MAIN", "kind": "FLAT" } ] ] }, "building": { "description": "Building-level characteristics, when known.", "example": { "constructionEra": "1948-1974", "elevator": true }, "type": "object", "additionalProperties": true, "examples": [ { "constructionEra": "1948-1974", "elevator": true } ] }, "amenities": { "description": "Amenity flags, when known.", "example": { "balcony": true, "cellar": true }, "type": "object", "additionalProperties": true, "examples": [ { "balcony": true, "cellar": true } ] }, "createdAt": { "description": "Creation timestamp (ISO 8601).", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "examples": [ "2026-01-15T10:30:00+00:00" ] }, "updatedAt": { "description": "Last update timestamp (ISO 8601).", "example": "2026-01-15T10:30:00+00:00", "type": [ "string", "null" ], "examples": [ "2026-01-15T10:30:00+00:00" ] }, "matched": { "description": "Present when a duplicate from another source was reconciled into this row.", "anyOf": [ { "$ref": "#/components/schemas/TransactionMatch" }, { "type": "null" } ] }, "sourcePayload": { "description": "Raw source payload. Returned on the item endpoint only, and only to authorized service accounts.", "example": { "id_mutation": "2024-123456", "type_local": "Appartement" }, "type": "object", "additionalProperties": true, "examples": [ { "id_mutation": "2024-123456", "type_local": "Appartement" } ] } } }, "TransactionSearchMeta": { "type": "object", "properties": { "count": { "description": "Number of transactions returned on this page.", "default": 0, "example": 20, "type": "integer", "examples": [ 20 ] }, "nextCursor": { "description": "Cursor for the next page. Send it back as page.cursor in the next request. Null when there are no more results.", "example": "eyJ1dWlkIjoiMDE5NDc2ZTItOGQxZi03YTNjLTliMmUtMWY2YTJjNGU4YjkwIiwiZGF0ZSI6IjIwMjQtMDMtMTUifQ==", "type": [ "string", "null" ], "examples": [ "eyJ1dWlkIjoiMDE5NDc2ZTItOGQxZi03YTNjLTliMmUtMWY2YTJjNGU4YjkwIiwiZGF0ZSI6IjIwMjQtMDMtMTUifQ==" ] } } }, "TransactionSection": { "type": "object", "properties": { "type": { "description": "Transaction type (sell / rent). Most frequent across listings.", "example": "SELL", "type": "string", "enum": [ "SELL", "RENT" ], "nullable": true, "examples": [ "SELL" ] }, "status": { "description": "Strongest transaction status across listings (AVAILABLE > UNDER_OFFER > SOLD/RENTED > WITHDRAWN).", "example": "AVAILABLE", "type": "string", "enum": [ "AVAILABLE", "UNDER_OFFER", "SOLD", "RENTED", "WITHDRAWN" ], "nullable": true, "examples": [ "AVAILABLE" ] }, "saleType": { "description": "Canonical sale type (standard, life annuity, …). Most-frequent + recency tie-break.", "example": "STANDARD", "type": "string", "enum": [ "STANDARD", "LIFE_ANNUITY" ], "nullable": true, "examples": [ "STANDARD" ] }, "availableAt": { "description": "ISO 8601 date from which the property is available. Most recent date reported across listings.", "example": "2026-06-01", "type": [ "string", "null" ], "examples": [ "2026-06-01" ] } } }, "Unit.EnergyScore": { "type": "object", "properties": { "rating": { "description": "Energy rating letter (A–G).", "example": "C", "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G" ], "nullable": true, "examples": [ "C" ] }, "value": { "description": "Numeric score value (in the corresponding unit).", "example": 120, "type": [ "number", "null" ], "examples": [ 120 ] }, "unit": { "description": "Measurement unit.", "example": "KWH_EP_PER_SQM_YEAR", "type": "string", "enum": [ "KWH_EP_PER_SQM_YEAR", "KWH_EF_PER_SQM_YEAR", "KG_CO2E_PER_SQM_YEAR" ], "nullable": true, "examples": [ "KWH_EP_PER_SQM_YEAR" ] } } }, "Unit.Heating": { "type": "object", "properties": { "system": { "description": "Heating system.", "example": "BOILER", "type": "string", "enum": [ "BOILER", "HEAT_PUMP", "RADIATOR", "FLOOR_HEATING", "SOLAR_THERMAL", "WOOD_STOVE", "AIR_CONDITIONING", "ELECTRIC_HEATER" ], "nullable": true, "examples": [ "BOILER" ] }, "energyCarrier": { "description": "Energy carrier.", "example": "GAS", "type": "string", "enum": [ "GAS", "ELECTRICITY", "OIL", "WOOD", "SOLAR", "GEOTHERMAL", "DISTRICT_HEATING" ], "nullable": true, "examples": [ "GAS" ] }, "collective": { "description": "Whether the heating is collective.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] } } }, "Unit.Parking": { "type": "object", "properties": { "total": { "description": "Total number of parking spots (value most listings report).", "example": 2, "type": [ "integer", "null" ], "examples": [ 2 ] }, "spots": { "description": "Deduplicated parking spots sorted by type name then box flag.", "type": "array", "items": { "$ref": "#/components/schemas/Unit.ParkingSpot" } } } }, "Unit.ParkingSpot": { "type": "object", "properties": { "type": { "description": "Parking type.", "example": "GARAGE", "type": "string", "enum": [ "GARAGE", "OUTDOOR", "UNDERGROUND", "COVERED" ], "nullable": true, "examples": [ "GARAGE" ] }, "box": { "description": "Whether the spot is a closed box.", "default": false, "type": "boolean", "example": false, "examples": [ false ] } } }, "UnitDiagnostic": { "type": "object", "properties": { "type": { "description": "Diagnostic type (DPE, audit, …).", "example": "DPE", "type": "string", "enum": [ "DPE" ], "nullable": true, "examples": [ "DPE" ] }, "date": { "description": "Diagnostic date (ISO 8601).", "example": "2024-06-15", "type": [ "string", "null" ], "examples": [ "2024-06-15" ] }, "standard": { "description": "Regulatory standard the diagnostic follows; the grade scale and the method differ per standard (FR_DPE_2006 before 1 July 2021, FR_DPE_2021 from that date). Absent when the source did not state it.", "example": "FR_DPE_2021", "type": "string", "enum": [ "FR_DPE_2006", "FR_DPE_2021" ], "nullable": true, "examples": [ "FR_DPE_2021" ] }, "methodVersion": { "description": "Revision of the data model printed on the certificate (ADEME version_dpe for a DPE). Free text; does not identify the standard.", "example": "2.4", "type": [ "string", "null" ], "examples": [ "2.4" ] }, "reference": { "description": "Certificate identifier at the issuing registry (ADEME number for a DPE).", "example": "2421E1234567X", "type": [ "string", "null" ], "examples": [ "2421E1234567X" ] }, "scores": { "description": "Energy scores keyed by EnergyScoreType name (ENERGY_CONSUMPTION, CARBON_EMISSIONS).", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Unit.EnergyScore" }, "example": { "ENERGY_CONSUMPTION": { "rating": "D", "value": 245, "unit": "KWH_EP_PER_SQM_YEAR" }, "CARBON_EMISSIONS": { "rating": "D", "value": 35, "unit": "KG_CO2E_PER_SQM_YEAR" } }, "examples": [ { "ENERGY_CONSUMPTION": { "rating": "D", "value": 245, "unit": "KWH_EP_PER_SQM_YEAR" }, "CARBON_EMISSIONS": { "rating": "D", "value": 35, "unit": "KG_CO2E_PER_SQM_YEAR" } } ] } } }, "UnitEnergy": { "type": "object", "properties": { "heating": { "description": "Heating systems / carriers reported on the canonical listing.", "type": "array", "items": { "$ref": "#/components/schemas/Unit.Heating" } } } }, "UnitSection": { "type": "object", "properties": { "rooms": { "description": "Number of rooms (value most listings report).", "example": 3, "type": [ "integer", "null" ], "examples": [ 3 ] }, "bedrooms": { "description": "Number of bedrooms (value most listings report).", "example": 2, "type": [ "integer", "null" ], "examples": [ 2 ] }, "bathrooms": { "description": "Number of bathrooms (value most listings report).", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "showerRooms": { "description": "Number of shower rooms (value most listings report).", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "wc": { "description": "Number of WC (value most listings report).", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "livingRooms": { "description": "Number of living rooms (value most listings report).", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "kitchens": { "description": "Number of kitchens (value most listings report).", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "floor": { "description": "Floor number (value most listings report).", "example": 2, "type": [ "integer", "null" ], "examples": [ 2 ] }, "lastFloor": { "description": "On the last floor of the building.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "groundFloor": { "description": "On the ground floor.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "gardenFloor": { "description": "On the garden floor.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "orientation": { "description": "Deduplicated union of orientations reported across listings.", "example": [ "SOUTH" ], "type": "array", "items": { "type": "string", "enum": [ "NORTH", "NORTH_EAST", "EAST", "SOUTH_EAST", "SOUTH", "SOUTH_WEST", "WEST", "NORTH_WEST" ] }, "examples": [ [ "SOUTH" ] ] }, "condition": { "description": "Canonical condition (most frequent across listings, recency tie-break).", "example": "GOOD", "type": "string", "enum": [ "NEW", "GOOD", "TO_RENOVATE" ], "nullable": true, "examples": [ "GOOD" ] }, "furnished": { "description": "Furnished.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "disabledAccess": { "description": "Disabled access.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "equippedKitchen": { "description": "Equipped kitchen.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "fireplace": { "description": "Fireplace.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "airConditioning": { "description": "Air conditioning.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "doubleGlazing": { "description": "Double glazing.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "parquet": { "description": "Parquet flooring.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "balcony": { "description": "Balcony.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "terrace": { "description": "Terrace.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "garden": { "description": "Garden.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "dressing": { "description": "Dressing room.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "crossing": { "description": "Crossing apartment.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "quiet": { "description": "Quiet location.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "cellar": { "description": "Cellar.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "basement": { "description": "Basement.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "storage": { "description": "Storage room.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "parking": { "description": "Parking facet — total count and individual spots with type / box flag.", "anyOf": [ { "$ref": "#/components/schemas/Unit.Parking" }, { "type": "null" } ] }, "diagnostic": { "description": "Canonical regulatory diagnostic (DPE / audit) — most-filled across listings, recency tie-break.", "anyOf": [ { "$ref": "#/components/schemas/UnitDiagnostic" }, { "type": "null" } ] }, "energy": { "description": "Energy equipment (heating systems / carriers) attached to the canonical diagnostic's source listing.", "anyOf": [ { "$ref": "#/components/schemas/UnitEnergy" }, { "type": "null" } ] } } }, "AndNode": { "type": "object", "properties": { "and": { "minItems": 2, "maxItems": 10, "description": "Child nodes — all must match.", "type": "array", "items": { "$ref": "#/components/schemas/CriteriaNode" } } } }, "CriteriaNode": { "description": "A search criteria node. Exactly one of three shapes: a flat Filters object (most common), {\"and\": [...]} requiring all children to match, or {\"or\": [...]} requiring at least one child to match.", "oneOf": [ { "$ref": "#/components/schemas/Filters" }, { "$ref": "#/components/schemas/AndNode" }, { "$ref": "#/components/schemas/OrNode" } ] }, "OrNode": { "type": "object", "properties": { "or": { "minItems": 2, "maxItems": 10, "description": "Child nodes — at least one must match.", "type": "array", "items": { "$ref": "#/components/schemas/CriteriaNode" } } } }, "Filters": { "type": "object", "properties": { "property": { "description": "Property-facet filters (type, transaction, pricing, areas, locations, unit, building, amenities, body).", "anyOf": [ { "$ref": "#/components/schemas/PropertyFacetFilters" }, { "type": "null" } ] }, "publisher": { "description": "Publisher filters (type, mandate, references, contact-presence) — all clauses apply to the SAME publisher (intra-publisher semantic). For cross-publisher independent matching, combine multiple publisher blocks via and: at the criteria tree level.", "anyOf": [ { "$ref": "#/components/schemas/PublisherFilters" }, { "type": "null" } ] }, "listings": { "description": "Listing-level filters targeting the nested listings.* (url, sources, marketing flags) — all clauses apply to the SAME listing.", "anyOf": [ { "$ref": "#/components/schemas/ListingsFilters" }, { "type": "null" } ] }, "dates": { "description": "Date-range filters on createdAt and updatedAt.", "anyOf": [ { "$ref": "#/components/schemas/DatesFilters" }, { "type": "null" } ] }, "changes": { "description": "Attribute-change filters (changed attribute, signed variation range, occurrence date) — all clauses apply to the SAME change. For independent changes (e.g. a price drop AND an area drop), combine multiple changes blocks via and: at the criteria tree level.", "anyOf": [ { "$ref": "#/components/schemas/ChangesFilters" }, { "type": "null" } ] } } }, "PropertyFacetFilters": { "type": "object", "properties": { "id": { "description": "Property id filter (in / nin). Targets the id of each result. Not available on alerts.", "anyOf": [ { "$ref": "#/components/schemas/PropertyIdFilters" }, { "type": "null" } ] }, "type": { "description": "Property-type filter (in / nin). Targets property.propertyType.", "anyOf": [ { "$ref": "#/components/schemas/PropertyTypeFilters" }, { "type": "null" } ] }, "constructionStatus": { "description": "Construction-status filter (in / nin / inOrMissing). Omitting any construction-status filter across the whole search restricts results to OLD or not-yet-qualified properties by default.", "anyOf": [ { "$ref": "#/components/schemas/ConstructionStatusFilters" }, { "type": "null" } ] }, "transaction": { "description": "Transaction facet filter (type).", "anyOf": [ { "$ref": "#/components/schemas/TransactionFilters" }, { "type": "null" } ] }, "pricing": { "description": "Pricing facet filters (displayed, pricePerArea, sale + rental subtrees).", "anyOf": [ { "$ref": "#/components/schemas/PricingFilters" }, { "type": "null" } ] }, "areas": { "description": "Area filters (area.displayed headline plus land).", "anyOf": [ { "$ref": "#/components/schemas/AreasFilters" }, { "type": "null" } ] }, "locations": { "description": "Geographic filter (in / nin sets, accuracy).", "anyOf": [ { "$ref": "#/components/schemas/LocationFilters" }, { "type": "null" } ] }, "unit": { "description": "Unit-interior filters (features, rooms, bedrooms, diagnostic, energy).", "anyOf": [ { "$ref": "#/components/schemas/UnitFilters" }, { "type": "null" } ] }, "building": { "description": "Building filters (construction year, renovation year, number of lots, type, condition, energy).", "anyOf": [ { "$ref": "#/components/schemas/BuildingFilters" }, { "type": "null" } ] }, "amenities": { "description": "Amenity feature filters (in / nin / inOrMissing).", "anyOf": [ { "$ref": "#/components/schemas/AmenityFilters" }, { "type": "null" } ] }, "body": { "description": "Free-text body filters (title, description).", "anyOf": [ { "$ref": "#/components/schemas/BodyFilters" }, { "type": "null" } ] } } }, "PropertyIdFilters": { "type": "object", "properties": { "in": { "maxItems": 100, "description": "Property ids to return, up to 100. The default filters still apply, so an expired, new-build or price-incoherent property is returned only when the criteria ask for it.", "example": [ "019e1a00-0000-7000-8000-000000000001", "019e1a00-0000-7000-8000-000000000002" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "019e1a00-0000-7000-8000-000000000001", "019e1a00-0000-7000-8000-000000000002" ] ] }, "nin": { "maxItems": 100, "description": "Property ids to leave out of the results, up to 100.", "example": [ "019e1a00-0000-7000-8000-000000000003" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "019e1a00-0000-7000-8000-000000000003" ] ] } } }, "PropertyTypeFilters": { "type": "object", "properties": { "in": { "description": "Property types the result must match (OR within the array).", "example": [ "FLAT", "HOUSE" ], "type": "array", "items": { "type": "string", "enum": [ "FLAT", "HOUSE", "BUILDING", "PARKING", "OFFICE", "LAND", "SHOP", "COMMERCIAL_PREMISES" ] }, "examples": [ [ "FLAT", "HOUSE" ] ] }, "nin": { "description": "Property types the result must NOT match.", "example": [ "PARKING" ], "type": "array", "items": { "type": "string", "enum": [ "FLAT", "HOUSE", "BUILDING", "PARKING", "OFFICE", "LAND", "SHOP", "COMMERCIAL_PREMISES" ] }, "examples": [ [ "PARKING" ] ] } } }, "ConstructionStatusFilters": { "type": "object", "properties": { "in": { "description": "Construction statuses the property must match (strict — at least one match required).", "example": [ "NEW", "UNDER_CONSTRUCTION" ], "type": "array", "items": { "type": "string", "enum": [ "OLD", "NEW", "UNDER_CONSTRUCTION" ] }, "examples": [ [ "NEW", "UNDER_CONSTRUCTION" ] ] }, "nin": { "description": "Construction statuses the property must NOT match.", "example": [ "UNDER_CONSTRUCTION" ], "type": "array", "items": { "type": "string", "enum": [ "OLD", "NEW", "UNDER_CONSTRUCTION" ] }, "examples": [ [ "UNDER_CONSTRUCTION" ] ] }, "inOrMissing": { "description": "Construction statuses the property is allowed to match OR be missing — keeps properties without a documented construction status.", "example": [ "OLD" ], "type": "array", "items": { "type": "string", "enum": [ "OLD", "NEW", "UNDER_CONSTRUCTION" ] }, "examples": [ [ "OLD" ] ] } } }, "TransactionFilters": { "type": "object", "properties": { "type": { "description": "Transaction type filter — single value (SELL or RENT). Omit to include both.", "example": "SELL", "type": "string", "enum": [ "SELL", "RENT" ], "nullable": true, "examples": [ "SELL" ] } } }, "PricingFilters": { "type": "object", "properties": { "displayed": { "description": "Observed price range — the raw price as advertised on the source listings. Whether agency fees are included depends on the source: some publishers post the fees-inclusive price, others the seller net price.", "example": { "gte": 350000, "lte": 750000 }, "anyOf": [ { "$ref": "#/components/schemas/FloatRange" }, { "type": "null" } ], "examples": [ { "gte": 350000, "lte": 750000 } ] }, "pricePerArea": { "description": "Price per area-unit range (e.g. €/m² in France). Computed on displayed price/area.", "example": { "gte": 8000, "lte": 14000 }, "anyOf": [ { "$ref": "#/components/schemas/FloatRange" }, { "type": "null" } ], "examples": [ { "gte": 8000, "lte": 14000 } ] }, "sale": { "description": "Sale-side pricing filters (pricing.sale.*).", "anyOf": [ { "$ref": "#/components/schemas/SalePricingFilters" }, { "type": "null" } ] }, "rental": { "description": "Rental-side pricing filters (pricing.rental.*).", "anyOf": [ { "$ref": "#/components/schemas/RentalPricingFilters" }, { "type": "null" } ] } } }, "FloatRange": { "type": "object", "properties": { "gte": { "minimum": 0, "description": "Minimum value (greater than or equal)", "example": 50, "type": [ "number", "null" ], "examples": [ 50 ] }, "lte": { "minimum": 0, "description": "Maximum value (less than or equal)", "example": 150, "type": [ "number", "null" ], "examples": [ 150 ] } } }, "SalePricingFilters": { "type": "object", "properties": { "netPrice": { "description": "Seller net price (excluding agency fees). Targets property.pricing.sale.netPrice.", "anyOf": [ { "$ref": "#/components/schemas/NullableFloatRange" }, { "type": "null" } ] }, "fees": { "description": "Sale fee filters (agency, condominium, legal).", "anyOf": [ { "$ref": "#/components/schemas/SaleFeesFilters" }, { "type": "null" } ] } } }, "NullableFloatRange": { "type": "object", "properties": { "orMissing": { "description": "When true, also match properties whose indexed field is missing. Default false (strict).", "default": false, "example": false, "type": "boolean", "examples": [ false ] }, "gte": { "minimum": 0, "description": "Minimum value (greater than or equal)", "example": 50, "type": [ "number", "null" ], "examples": [ 50 ] }, "lte": { "minimum": 0, "description": "Maximum value (less than or equal)", "example": 150, "type": [ "number", "null" ], "examples": [ 150 ] } } }, "SaleFeesFilters": { "type": "object", "properties": { "agency": { "description": "Agency fee filters.", "anyOf": [ { "$ref": "#/components/schemas/SaleAgencyFilters" }, { "type": "null" } ] }, "condominium": { "description": "Condominium fee filters.", "anyOf": [ { "$ref": "#/components/schemas/SaleCondominiumFilters" }, { "type": "null" } ] }, "legal": { "description": "Legal fee filters.", "anyOf": [ { "$ref": "#/components/schemas/SaleLegalFilters" }, { "type": "null" } ] } } }, "SaleAgencyFilters": { "type": "object", "properties": { "amount": { "description": "Agency fee amount (€). Targets property.pricing.sale.fees.agency.amount.", "anyOf": [ { "$ref": "#/components/schemas/NullableFloatRange" }, { "type": "null" } ] }, "percentage": { "description": "Agency fee percentage of the sale price. Targets property.pricing.sale.fees.agency.percentage.", "anyOf": [ { "$ref": "#/components/schemas/NullableFloatRange" }, { "type": "null" } ] }, "paidBy": { "description": "Who pays the agency fees on a sale: BUYER or SELLER. Targets property.pricing.sale.fees.agency.paidBy.", "example": "SELLER", "type": "string", "enum": [ "BUYER", "SELLER", "OWNER", "TENANT" ], "nullable": true, "examples": [ "SELLER" ] }, "includedInPrice": { "description": "Whether agency fees are included in the displayed price. Targets property.pricing.sale.fees.agency.includedInPrice.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] } } }, "SaleCondominiumFilters": { "type": "object", "properties": { "total": { "description": "Total monthly condominium fees. Targets property.pricing.sale.fees.condominium.total.", "anyOf": [ { "$ref": "#/components/schemas/NullableFloatRange" }, { "type": "null" } ] } } }, "SaleLegalFilters": { "type": "object", "properties": { "amount": { "description": "Legal fee amount. Targets property.pricing.sale.fees.legal.amount.", "anyOf": [ { "$ref": "#/components/schemas/NullableFloatRange" }, { "type": "null" } ] } } }, "RentalPricingFilters": { "type": "object", "properties": { "rent": { "description": "Rent-level filters (charges-inclusion flag, etc.).", "anyOf": [ { "$ref": "#/components/schemas/RentalRentFilters" }, { "type": "null" } ] }, "fees": { "description": "Rental fee filters (charges, deposit, inventory, tenant agency).", "anyOf": [ { "$ref": "#/components/schemas/RentalFeesFilters" }, { "type": "null" } ] } } }, "RentalRentFilters": { "type": "object", "properties": { "includesCharges": { "description": "Whether the monthly rent already includes charges. Targets property.pricing.rental.rent.includesCharges.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] } } }, "RentalFeesFilters": { "type": "object", "properties": { "charges": { "description": "Monthly charges filters.", "anyOf": [ { "$ref": "#/components/schemas/RentalChargesFilters" }, { "type": "null" } ] }, "deposit": { "description": "Security deposit filters.", "anyOf": [ { "$ref": "#/components/schemas/RentalDepositFilters" }, { "type": "null" } ] }, "inventory": { "description": "Inventory check fee filters.", "anyOf": [ { "$ref": "#/components/schemas/RentalInventoryFilters" }, { "type": "null" } ] }, "agency": { "description": "Tenant-side agency fee filters.", "anyOf": [ { "$ref": "#/components/schemas/RentalAgencyFilters" }, { "type": "null" } ] } } }, "RentalChargesFilters": { "type": "object", "properties": { "amount": { "description": "Monthly rental charges amount. Targets property.pricing.rental.fees.charges.amount.", "anyOf": [ { "$ref": "#/components/schemas/NullableFloatRange" }, { "type": "null" } ] } } }, "RentalDepositFilters": { "type": "object", "properties": { "amount": { "description": "Security deposit amount. Targets property.pricing.rental.fees.deposit.amount.", "anyOf": [ { "$ref": "#/components/schemas/NullableFloatRange" }, { "type": "null" } ] } } }, "RentalInventoryFilters": { "type": "object", "properties": { "amount": { "description": "Inventory check fee amount. Targets property.pricing.rental.fees.inventory.amount.", "anyOf": [ { "$ref": "#/components/schemas/NullableFloatRange" }, { "type": "null" } ] } } }, "RentalAgencyFilters": { "type": "object", "properties": { "amount": { "description": "Agency fee amount charged to the tenant. Targets property.pricing.rental.fees.agency.amount.", "anyOf": [ { "$ref": "#/components/schemas/NullableFloatRange" }, { "type": "null" } ] } } }, "AreasFilters": { "type": "object", "properties": { "displayed": { "description": "Headline area range in m². Targets property.area.displayed.", "example": { "gte": 45, "lte": 95 }, "anyOf": [ { "$ref": "#/components/schemas/FloatRange" }, { "type": "null" } ], "examples": [ { "gte": 45, "lte": 95 } ] }, "land": { "description": "Land area range in m². Targets property.area.land.value.", "example": { "gte": 200, "lte": 2000 }, "anyOf": [ { "$ref": "#/components/schemas/FloatRange" }, { "type": "null" } ], "examples": [ { "gte": 200, "lte": 2000 } ] } } }, "LocationFilters": { "type": "object", "properties": { "countryCode": { "description": "Country the uniqueCodes belong to. Applies to uniqueCodes only; uniqueCodes sent without countryCode are ignored.", "example": "FR", "type": "string", "enum": [ "FR", "BE" ], "nullable": true, "examples": [ "FR" ] }, "in": { "description": "Locations the property must intersect (OR across the five fields).", "anyOf": [ { "$ref": "#/components/schemas/LocationsSet" }, { "type": "null" } ] }, "nin": { "description": "Locations the property must NOT intersect (OR across the five fields).", "anyOf": [ { "$ref": "#/components/schemas/LocationsSet" }, { "type": "null" } ] }, "accuracy": { "description": "Allowed location accuracy levels. Empty = no filter. Use e.g. [PRECISE, STREET] to keep only well-geolocated properties.", "example": [ "PRECISE", "STREET" ], "type": "array", "items": { "type": "string", "enum": [ "PRECISE", "STREET", "CITY", "UNKNOWN", "NEIGHBORHOOD", "DISTRICT" ] }, "examples": [ [ "PRECISE", "STREET" ] ] } } }, "LocationsSet": { "type": "object", "properties": { "ids": { "description": "Administrative division ids; matches the materialized path so descendants are included automatically.", "example": [ "019dedb1-fdf4-714c-8392-5b9cfd63cde3" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "019dedb1-fdf4-714c-8392-5b9cfd63cde3" ] ] }, "centerPoint": { "description": "Single center+radius geographic circle.", "anyOf": [ { "$ref": "#/components/schemas/CenterPoint" }, { "type": "null" } ] }, "geoShapes": { "description": "GeoJSON polygons / multipolygons (RFC 7946 — geometry types Polygon and MultiPolygon). A property inside any one shape matches.", "type": "array", "items": { "$ref": "#/components/schemas/GeoJsonGeometry" } }, "postalCodes": { "description": "Postal codes.", "example": [ "75018", "75019" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "75018", "75019" ] ] }, "uniqueCodes": { "description": "Country-native unique codes (INSEE in FR, BCE in BE, AGS in DE…). Scoped by the parent countryCode to avoid cross-country collisions.", "example": [ "75118" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "75118" ] ] } } }, "CenterPoint": { "type": "object", "properties": { "latitude": { "minimum": -90, "maximum": 90, "description": "Center latitude in WGS 84.", "default": 0, "example": 48.8566, "type": "number", "examples": [ 48.8566 ] }, "longitude": { "minimum": -180, "maximum": 180, "description": "Center longitude in WGS 84.", "default": 0, "example": 2.3522, "type": "number", "examples": [ 2.3522 ] }, "radiusKm": { "minimum": 0, "exclusiveMinimum": 0, "maximum": 500, "description": "Search radius in kilometers.", "default": 0, "example": 5, "type": "number", "examples": [ 5 ] } } }, "UnitFilters": { "type": "object", "properties": { "features": { "description": "Unit-interior feature filters (in / nin / inOrMissing).", "anyOf": [ { "$ref": "#/components/schemas/UnitFeatureFilters" }, { "type": "null" } ] }, "rooms": { "description": "Number of rooms range. Opt-in orMissing to keep properties without an indexed room count.", "example": { "gte": 2, "lte": 5 }, "anyOf": [ { "$ref": "#/components/schemas/NullableIntRange" }, { "type": "null" } ], "examples": [ { "gte": 2, "lte": 5 } ] }, "bedrooms": { "description": "Number of bedrooms range. Opt-in orMissing to keep properties without an indexed bedroom count.", "example": { "gte": 1, "lte": 3 }, "anyOf": [ { "$ref": "#/components/schemas/NullableIntRange" }, { "type": "null" } ], "examples": [ { "gte": 1, "lte": 3 } ] }, "floor": { "description": "Floor number range. Opt-in orMissing to keep properties without an indexed floor (e.g. houses).", "example": { "gte": 1, "lte": 5 }, "anyOf": [ { "$ref": "#/components/schemas/NullableIntRange" }, { "type": "null" } ], "examples": [ { "gte": 1, "lte": 5 } ] }, "orientation": { "description": "Orientation filter (in / nin / inOrMissing).", "anyOf": [ { "$ref": "#/components/schemas/OrientationFilters" }, { "type": "null" } ] }, "condition": { "description": "Condition filter (in / nin / inOrMissing).", "anyOf": [ { "$ref": "#/components/schemas/ConditionFilters" }, { "type": "null" } ] }, "diagnostic": { "description": "Filters on the canonical regulatory diagnostic (DPE / audit): regulatory standard, per-score rating letters and/or value ranges.", "anyOf": [ { "$ref": "#/components/schemas/UnitDiagnosticFilter" }, { "type": "null" } ] }, "energy": { "description": "Filters on the unit's energy heating (system, fuel, collective flag).", "anyOf": [ { "$ref": "#/components/schemas/EnergyFilters" }, { "type": "null" } ] } } }, "UnitFeatureFilters": { "type": "object", "properties": { "in": { "description": "Features the property must have (strict — feature must be indexed as true).", "example": [ "BALCONY", "TERRACE" ], "type": "array", "items": { "type": "string", "enum": [ "LAST_FLOOR", "GROUND_FLOOR", "GARDEN_FLOOR", "FURNISHED", "DISABLED_ACCESS", "EQUIPPED_KITCHEN", "FIREPLACE", "AIR_CONDITIONING", "DOUBLE_GLAZING", "PARQUET", "BALCONY", "TERRACE", "GARDEN", "DRESSING", "CROSSING", "QUIET", "CELLAR", "BASEMENT", "STORAGE" ] }, "examples": [ [ "BALCONY", "TERRACE" ] ] }, "nin": { "description": "Features the property must NOT have (false or missing both pass).", "example": [ "GROUND_FLOOR" ], "type": "array", "items": { "type": "string", "enum": [ "LAST_FLOOR", "GROUND_FLOOR", "GARDEN_FLOOR", "FURNISHED", "DISABLED_ACCESS", "EQUIPPED_KITCHEN", "FIREPLACE", "AIR_CONDITIONING", "DOUBLE_GLAZING", "PARQUET", "BALCONY", "TERRACE", "GARDEN", "DRESSING", "CROSSING", "QUIET", "CELLAR", "BASEMENT", "STORAGE" ] }, "examples": [ [ "GROUND_FLOOR" ] ] }, "inOrMissing": { "description": "Features the property is allowed to have OR be missing — keeps properties where the feature is documented true AND those where it has not been documented at all. Excludes only explicitly-false properties.", "example": [ "FURNISHED" ], "type": "array", "items": { "type": "string", "enum": [ "LAST_FLOOR", "GROUND_FLOOR", "GARDEN_FLOOR", "FURNISHED", "DISABLED_ACCESS", "EQUIPPED_KITCHEN", "FIREPLACE", "AIR_CONDITIONING", "DOUBLE_GLAZING", "PARQUET", "BALCONY", "TERRACE", "GARDEN", "DRESSING", "CROSSING", "QUIET", "CELLAR", "BASEMENT", "STORAGE" ] }, "examples": [ [ "FURNISHED" ] ] } } }, "NullableIntRange": { "type": "object", "properties": { "orMissing": { "description": "When true, also match properties whose indexed field is missing. Default false (strict).", "default": false, "example": false, "type": "boolean", "examples": [ false ] }, "gte": { "minimum": 0, "description": "Minimum value (greater than or equal)", "example": 2, "type": [ "integer", "null" ], "examples": [ 2 ] }, "lte": { "minimum": 0, "description": "Maximum value (less than or equal)", "example": 5, "type": [ "integer", "null" ], "examples": [ 5 ] } } }, "OrientationFilters": { "type": "object", "properties": { "in": { "description": "Orientations the unit must face (strict — at least one match required).", "example": [ "SOUTH", "SOUTH_WEST" ], "type": "array", "items": { "type": "string", "enum": [ "NORTH", "NORTH_EAST", "EAST", "SOUTH_EAST", "SOUTH", "SOUTH_WEST", "WEST", "NORTH_WEST" ] }, "examples": [ [ "SOUTH", "SOUTH_WEST" ] ] }, "nin": { "description": "Orientations the unit must NOT face.", "example": [ "NORTH" ], "type": "array", "items": { "type": "string", "enum": [ "NORTH", "NORTH_EAST", "EAST", "SOUTH_EAST", "SOUTH", "SOUTH_WEST", "WEST", "NORTH_WEST" ] }, "examples": [ [ "NORTH" ] ] }, "inOrMissing": { "description": "Orientations the unit is allowed to face OR be missing — keeps properties without documented orientation.", "example": [ "SOUTH" ], "type": "array", "items": { "type": "string", "enum": [ "NORTH", "NORTH_EAST", "EAST", "SOUTH_EAST", "SOUTH", "SOUTH_WEST", "WEST", "NORTH_WEST" ] }, "examples": [ [ "SOUTH" ] ] } } }, "ConditionFilters": { "type": "object", "properties": { "in": { "description": "Conditions the unit must match (strict — at least one match required).", "example": [ "NEW", "GOOD" ], "type": "array", "items": { "type": "string", "enum": [ "NEW", "GOOD", "TO_RENOVATE" ] }, "examples": [ [ "NEW", "GOOD" ] ] }, "nin": { "description": "Conditions the unit must NOT match.", "example": [ "TO_RENOVATE" ], "type": "array", "items": { "type": "string", "enum": [ "NEW", "GOOD", "TO_RENOVATE" ] }, "examples": [ [ "TO_RENOVATE" ] ] }, "inOrMissing": { "description": "Conditions the unit is allowed to match OR be missing — keeps properties without a documented condition.", "example": [ "GOOD" ], "type": "array", "items": { "type": "string", "enum": [ "NEW", "GOOD", "TO_RENOVATE" ] }, "examples": [ [ "GOOD" ] ] } } }, "UnitDiagnosticFilter": { "type": "object", "properties": { "standard": { "description": "Regulatory standard filter (in / nin / inOrMissing); inOrMissing keeps properties whose standard is unknown.", "anyOf": [ { "$ref": "#/components/schemas/EnergyCertificateStandardFilters" }, { "type": "null" } ] }, "scores": { "description": "Per-score filters. Each entry pins a type (e.g. ENERGY_CONSUMPTION) and optionally constrains its rating letters and/or numeric value range.", "example": [ { "type": "ENERGY_CONSUMPTION", "rating": [ "A", "B", "C" ], "value": { "gte": 50, "lte": 250 } }, { "type": "CARBON_EMISSIONS", "rating": [ "A", "B" ] } ], "type": "array", "items": { "$ref": "#/components/schemas/DiagnosticScoreFilter" }, "examples": [ [ { "type": "ENERGY_CONSUMPTION", "rating": [ "A", "B", "C" ], "value": { "gte": 50, "lte": 250 } }, { "type": "CARBON_EMISSIONS", "rating": [ "A", "B" ] } ] ] } } }, "EnergyCertificateStandardFilters": { "type": "object", "properties": { "in": { "description": "Standards the diagnostic must follow (strict — at least one match required).", "example": [ "FR_DPE_2021" ], "type": "array", "items": { "type": "string", "enum": [ "FR_DPE_2006", "FR_DPE_2021" ] }, "examples": [ [ "FR_DPE_2021" ] ] }, "nin": { "description": "Standards the diagnostic must NOT follow.", "example": [ "FR_DPE_2006" ], "type": "array", "items": { "type": "string", "enum": [ "FR_DPE_2006", "FR_DPE_2021" ] }, "examples": [ [ "FR_DPE_2006" ] ] }, "inOrMissing": { "description": "Standards the diagnostic is allowed to follow OR be missing — keeps properties whose standard is unknown.", "example": [ "FR_DPE_2021" ], "type": "array", "items": { "type": "string", "enum": [ "FR_DPE_2006", "FR_DPE_2021" ] }, "examples": [ [ "FR_DPE_2021" ] ] } } }, "DiagnosticScoreFilter": { "type": "object", "required": [ "type" ], "properties": { "type": { "description": "Diagnostic score type — ENERGY_CONSUMPTION or CARBON_EMISSIONS for now.", "example": "ENERGY_CONSUMPTION", "type": "string", "enum": [ "ENERGY_CONSUMPTION", "CARBON_EMISSIONS" ], "nullable": true, "examples": [ "ENERGY_CONSUMPTION" ] }, "rating": { "description": "Allowed rating letters (A–G). Empty = no rating filter.", "example": [ "A", "B", "C" ], "type": "array", "items": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G" ] }, "examples": [ [ "A", "B", "C" ] ] }, "value": { "description": "Numeric score range. Unit depends on score type (typically kWh/m²/year for ENERGY_CONSUMPTION, kgCO₂/m²/year for CARBON_EMISSIONS).", "example": { "gte": 50, "lte": 250 }, "anyOf": [ { "$ref": "#/components/schemas/IntRange" }, { "type": "null" } ], "examples": [ { "gte": 50, "lte": 250 } ] } } }, "IntRange": { "type": "object", "properties": { "gte": { "minimum": 0, "description": "Minimum value (greater than or equal)", "example": 2, "type": [ "integer", "null" ], "examples": [ 2 ] }, "lte": { "minimum": 0, "description": "Maximum value (less than or equal)", "example": 5, "type": [ "integer", "null" ], "examples": [ 5 ] } } }, "EnergyFilters": { "type": "object", "properties": { "heating": { "description": "Heating filters (system, energy carrier, collective flag).", "anyOf": [ { "$ref": "#/components/schemas/HeatingFilters" }, { "type": "null" } ] } } }, "HeatingFilters": { "type": "object", "properties": { "system": { "description": "Heating system filter (in / nin).", "anyOf": [ { "$ref": "#/components/schemas/HeatingSystemFilters" }, { "type": "null" } ] }, "energyCarrier": { "description": "Energy carrier (fuel) filter (in / nin).", "anyOf": [ { "$ref": "#/components/schemas/EnergyCarrierFilters" }, { "type": "null" } ] }, "collective": { "description": "Whether heating is collective (shared with the building) or individual. Targets property.unit.energy.heating.collective.", "example": false, "type": [ "boolean", "null" ], "examples": [ false ] } } }, "HeatingSystemFilters": { "type": "object", "properties": { "in": { "description": "Heating systems the property must use one of.", "example": [ "HEAT_PUMP", "FLOOR_HEATING" ], "type": "array", "items": { "type": "string", "enum": [ "BOILER", "HEAT_PUMP", "RADIATOR", "FLOOR_HEATING", "SOLAR_THERMAL", "WOOD_STOVE", "AIR_CONDITIONING", "ELECTRIC_HEATER" ] }, "examples": [ [ "HEAT_PUMP", "FLOOR_HEATING" ] ] }, "nin": { "description": "Heating systems the property must NOT use.", "example": [ "ELECTRIC_HEATER" ], "type": "array", "items": { "type": "string", "enum": [ "BOILER", "HEAT_PUMP", "RADIATOR", "FLOOR_HEATING", "SOLAR_THERMAL", "WOOD_STOVE", "AIR_CONDITIONING", "ELECTRIC_HEATER" ] }, "examples": [ [ "ELECTRIC_HEATER" ] ] } } }, "EnergyCarrierFilters": { "type": "object", "properties": { "in": { "description": "Energy carriers (fuel) the property must use one of.", "example": [ "GAS", "ELECTRICITY" ], "type": "array", "items": { "type": "string", "enum": [ "GAS", "ELECTRICITY", "OIL", "WOOD", "SOLAR", "GEOTHERMAL", "DISTRICT_HEATING" ] }, "examples": [ [ "GAS", "ELECTRICITY" ] ] }, "nin": { "description": "Energy carriers (fuel) the property must NOT use.", "example": [ "OIL" ], "type": "array", "items": { "type": "string", "enum": [ "GAS", "ELECTRICITY", "OIL", "WOOD", "SOLAR", "GEOTHERMAL", "DISTRICT_HEATING" ] }, "examples": [ [ "OIL" ] ] } } }, "BuildingFilters": { "type": "object", "properties": { "constructionYear": { "description": "Construction year range. Opt-in orMissing to keep properties without an indexed construction year.", "example": { "gte": 1900, "lte": 2024 }, "anyOf": [ { "$ref": "#/components/schemas/NullableIntRange" }, { "type": "null" } ], "examples": [ { "gte": 1900, "lte": 2024 } ] }, "renovationYear": { "description": "Renovation year range. Opt-in orMissing to keep properties without an indexed renovation year.", "example": { "gte": 2010 }, "anyOf": [ { "$ref": "#/components/schemas/NullableIntRange" }, { "type": "null" } ], "examples": [ { "gte": 2010 } ] }, "numberOfLots": { "description": "Number of lots range (condominium size). Opt-in orMissing to keep properties without an indexed lot count.", "example": { "gte": 10, "lte": 100 }, "anyOf": [ { "$ref": "#/components/schemas/NullableIntRange" }, { "type": "null" } ], "examples": [ { "gte": 10, "lte": 100 } ] }, "floors": { "description": "Total number of floors in the building (distinct from unit.floor which is the dwelling's floor). Opt-in orMissing to keep properties without an indexed floor count.", "example": { "gte": 3, "lte": 8 }, "anyOf": [ { "$ref": "#/components/schemas/NullableIntRange" }, { "type": "null" } ], "examples": [ { "gte": 3, "lte": 8 } ] }, "constructionType": { "description": "Construction type filter (in / nin / inOrMissing).", "anyOf": [ { "$ref": "#/components/schemas/ConstructionTypeFilters" }, { "type": "null" } ] }, "condition": { "description": "Condition filter (in / nin / inOrMissing).", "anyOf": [ { "$ref": "#/components/schemas/ConditionFilters" }, { "type": "null" } ] }, "energy": { "description": "Filters on the building's energy heating (system, fuel, collective flag).", "anyOf": [ { "$ref": "#/components/schemas/EnergyFilters" }, { "type": "null" } ] } } }, "ConstructionTypeFilters": { "type": "object", "properties": { "in": { "description": "Construction types the building must be one of.", "example": [ "HAUSSMANNIAN", "STONE" ], "type": "array", "items": { "type": "string", "enum": [ "HAUSSMANNIAN", "MODERN", "CONTEMPORARY", "TRADITIONAL", "STONE", "BRICK", "CONCRETE", "WOOD", "MIXED", "OTHER" ] }, "examples": [ [ "HAUSSMANNIAN", "STONE" ] ] }, "nin": { "description": "Construction types the building must NOT be.", "example": [ "OTHER" ], "type": "array", "items": { "type": "string", "enum": [ "HAUSSMANNIAN", "MODERN", "CONTEMPORARY", "TRADITIONAL", "STONE", "BRICK", "CONCRETE", "WOOD", "MIXED", "OTHER" ] }, "examples": [ [ "OTHER" ] ] }, "inOrMissing": { "description": "Construction types the building is allowed to be OR missing — keeps properties without a documented construction type.", "example": [ "HAUSSMANNIAN" ], "type": "array", "items": { "type": "string", "enum": [ "HAUSSMANNIAN", "MODERN", "CONTEMPORARY", "TRADITIONAL", "STONE", "BRICK", "CONCRETE", "WOOD", "MIXED", "OTHER" ] }, "examples": [ [ "HAUSSMANNIAN" ] ] } } }, "AmenityFilters": { "type": "object", "properties": { "features": { "description": "Amenity feature filters (in / nin / inOrMissing).", "anyOf": [ { "$ref": "#/components/schemas/AmenityFeatureFilters" }, { "type": "null" } ] } } }, "AmenityFeatureFilters": { "type": "object", "properties": { "in": { "description": "Amenities the property must have (strict — amenity must be indexed as true).", "example": [ "ELEVATOR", "PARKING" ], "type": "array", "items": { "type": "string", "enum": [ "ELEVATOR", "INTERCOM", "DIGICODE", "CARETAKER", "BIKE_ROOM", "DISABLED_ACCESS", "GYM", "PLAYGROUND", "PARTY_HALL", "SPORT_COURT", "ADULT_GAME_ROOM", "GATED_COMMUNITY", "BARBECUE_GRILL", "SWIMMING_POOL", "PARKING" ] }, "examples": [ [ "ELEVATOR", "PARKING" ] ] }, "nin": { "description": "Amenities the property must NOT have (false or missing both pass).", "example": [ "GATED_COMMUNITY" ], "type": "array", "items": { "type": "string", "enum": [ "ELEVATOR", "INTERCOM", "DIGICODE", "CARETAKER", "BIKE_ROOM", "DISABLED_ACCESS", "GYM", "PLAYGROUND", "PARTY_HALL", "SPORT_COURT", "ADULT_GAME_ROOM", "GATED_COMMUNITY", "BARBECUE_GRILL", "SWIMMING_POOL", "PARKING" ] }, "examples": [ [ "GATED_COMMUNITY" ] ] }, "inOrMissing": { "description": "Amenities the property is allowed to have OR be missing. Use this when the user prefers a false positive over a false negative on a sparsely-documented amenity (e.g. ELEVATOR).", "example": [ "ELEVATOR" ], "type": "array", "items": { "type": "string", "enum": [ "ELEVATOR", "INTERCOM", "DIGICODE", "CARETAKER", "BIKE_ROOM", "DISABLED_ACCESS", "GYM", "PLAYGROUND", "PARTY_HALL", "SPORT_COURT", "ADULT_GAME_ROOM", "GATED_COMMUNITY", "BARBECUE_GRILL", "SWIMMING_POOL", "PARKING" ] }, "examples": [ [ "ELEVATOR" ] ] } } }, "BodyFilters": { "type": "object", "properties": { "title": { "description": "Phrase filters on the property title.", "example": { "in": [ "vue mer" ] }, "anyOf": [ { "$ref": "#/components/schemas/BodyTextFilter" }, { "type": "null" } ], "examples": [ { "in": [ "vue mer" ] } ] }, "description": { "description": "Phrase filters on the property description.", "example": { "in": [ "à rénover" ], "nin": [ "bail commercial" ] }, "anyOf": [ { "$ref": "#/components/schemas/BodyTextFilter" }, { "type": "null" } ], "examples": [ { "in": [ "à rénover" ], "nin": [ "bail commercial" ] } ] } } }, "BodyTextFilter": { "type": "object", "properties": { "in": { "maxItems": 25, "description": "Phrases the text must contain at least one of (up to 25). Each entry matches only where its words appear side by side, in order; case and accents are ignored.", "example": [ "à rénover" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "à rénover" ] ] }, "nin": { "maxItems": 25, "description": "Phrases the text must contain none of (up to 25). Each entry excludes only where its words appear side by side, in order; case and accents are ignored.", "example": [ "bail commercial", "ehpad" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "bail commercial", "ehpad" ] ] } } }, "PublisherFilters": { "type": "object", "properties": { "type": { "description": "Publisher type filter (in / nin). Use \"PROFESSIONAL\" as a shorthand for every non-individual case.", "anyOf": [ { "$ref": "#/components/schemas/PublisherTypeFilters" }, { "type": "null" } ] }, "mandate": { "description": "Publisher mandate filter (in / nin). Targets publishers.mandate.", "anyOf": [ { "$ref": "#/components/schemas/MandateFilters" }, { "type": "null" } ] }, "references": { "description": "Match if any of the publisher's listing references is in the array. Targets publishers.reference.", "example": [ "REF-12345", "INTERNAL-99" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "REF-12345", "INTERNAL-99" ] ] }, "hasEmail": { "description": "When true, only keep publishers that carry an email. When false, only those without. Targets publishers.contact.email.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "hasPhone": { "description": "When true, only keep publishers that carry a phone number. When false, only those without. Targets publishers.contact.phone.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] } } }, "PublisherTypeFilters": { "type": "object", "properties": { "in": { "description": "Publisher types the matching publisher must be in. Use \"PROFESSIONAL\" as a shorthand for every non-individual case.", "example": [ "PROFESSIONAL" ], "type": "array", "items": { "type": "string", "enum": [ "PRIVATE_INDIVIDUAL", "REAL_ESTATE_AGENCY", "COMMERCIAL_AGENT", "MANDATED_AGENT", "PROFESSIONAL_UNKNOWN", "PROFESSIONAL" ] }, "examples": [ [ "PROFESSIONAL" ] ] }, "nin": { "description": "Publisher types the matching publisher must NOT be in.", "example": [ "PRIVATE_INDIVIDUAL" ], "type": "array", "items": { "type": "string", "enum": [ "PRIVATE_INDIVIDUAL", "REAL_ESTATE_AGENCY", "COMMERCIAL_AGENT", "MANDATED_AGENT", "PROFESSIONAL_UNKNOWN", "PROFESSIONAL" ] }, "examples": [ [ "PRIVATE_INDIVIDUAL" ] ] } } }, "MandateFilters": { "type": "object", "properties": { "in": { "description": "Mandates the matching publisher must hold at least one of.", "example": [ "EXCLUSIVE", "SEMI_EXCLUSIVE" ], "type": "array", "items": { "type": "string", "enum": [ "NON_EXCLUSIVE", "EXCLUSIVE", "SEMI_EXCLUSIVE" ] }, "examples": [ [ "EXCLUSIVE", "SEMI_EXCLUSIVE" ] ] }, "nin": { "description": "Mandates the matching publisher must NOT hold.", "example": [ "NON_EXCLUSIVE" ], "type": "array", "items": { "type": "string", "enum": [ "NON_EXCLUSIVE", "EXCLUSIVE", "SEMI_EXCLUSIVE" ] }, "examples": [ [ "NON_EXCLUSIVE" ] ] } } }, "ListingsFilters": { "type": "object", "properties": { "url": { "format": "uri", "maxLength": 2083, "description": "Listing URL, with or without a trailing slash. An exact match is not required: when the search matches nothing, the URL is resolved from the information it carries. Alerts match the exact URL only. Targets listings.url.", "externalDocs": { "url": "https://schema.org/url" }, "example": "https://www.real-estate.io/ventes_immobilieres/123456789.html", "type": [ "string", "null" ], "examples": [ "https://www.real-estate.io/ventes_immobilieres/123456789.html" ] }, "sources": { "description": "Source filter (in / nin by source id). Targets listings.source.id.", "anyOf": [ { "$ref": "#/components/schemas/SourceFilters" }, { "type": "null" } ] }, "marketing": { "description": "Marketing filters on the listing (favorites count, urgent / boosted / highlighted flags).", "anyOf": [ { "$ref": "#/components/schemas/MarketingFilters" }, { "type": "null" } ] }, "expiredAt": { "description": "Restrict to expired listings, optionally within an expiry date range (from / to). Setting this filter includes expired listings, which search hides by default. Targets listings.expiredAt.", "anyOf": [ { "$ref": "#/components/schemas/DateRange" }, { "type": "null" } ] }, "priceCoherent": { "description": "Whether listing prices look coherent with the local market. Defaults to true: properties whose listings are all price-incoherent are hidden from results. Set false to return only those properties. Judged across the whole property rather than per listing.", "default": true, "example": false, "type": [ "boolean", "null" ], "examples": [ false ] } } }, "SourceFilters": { "type": "object", "properties": { "in": { "description": "Source ids the property must have at least one listing from.", "example": [ "019e1a00-0000-7000-8000-00000000bcd1" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "019e1a00-0000-7000-8000-00000000bcd1" ] ] }, "nin": { "description": "Source ids the property must NOT have any listing from.", "example": [ "019e1a00-0000-7000-8000-00000000aaaa" ], "type": "array", "items": { "type": "string" }, "examples": [ [ "019e1a00-0000-7000-8000-00000000aaaa" ] ] } } }, "MarketingFilters": { "type": "object", "properties": { "favorites": { "description": "Number of times the listing has been favorited. Targets listings.marketing.favorites.", "example": { "gte": 5 }, "anyOf": [ { "$ref": "#/components/schemas/NullableIntRange" }, { "type": "null" } ], "examples": [ { "gte": 5 } ] }, "urgent": { "description": "Whether the listing is flagged urgent. Targets listings.marketing.urgent.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "boosted": { "description": "Whether the listing is boosted by the publisher. Targets listings.marketing.boosted.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "highlighted": { "description": "Whether the listing is highlighted on the source. Targets listings.marketing.highlighted.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] } } }, "DateRange": { "type": "object", "properties": { "from": { "description": "Lower bound (inclusive) — ISO 8601.", "example": "2024-01-01T00:00:00Z", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2024-01-01T00:00:00Z" ] }, "to": { "description": "Upper bound (inclusive) — ISO 8601.", "example": "2024-12-31T23:59:59Z", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2024-12-31T23:59:59Z" ] } } }, "DatesFilters": { "type": "object", "properties": { "createdAt": { "description": "Date range on property.createdAt.", "anyOf": [ { "$ref": "#/components/schemas/DateRange" }, { "type": "null" } ] }, "updatedAt": { "description": "Date range on property.updatedAt (when data was last collected from a source for this property).", "anyOf": [ { "$ref": "#/components/schemas/DateRange" }, { "type": "null" } ] } } }, "ChangesFilters": { "type": "object", "properties": { "attribute": { "description": "Filter by the changed attribute (in / nin). Targets changes.attribute.", "anyOf": [ { "$ref": "#/components/schemas/AttributeFilter" }, { "type": "null" } ] }, "variationPercent": { "description": "Signed variation range on numeric changes (price, area). A drop is negative: a 3 to 5 percent price drop is gte -5, lte -3. Targets changes.variationPercent.", "anyOf": [ { "$ref": "#/components/schemas/SignedFloatRange" }, { "type": "null" } ] }, "occurredAt": { "description": "Date range on when the change occurred (from / to). Targets changes.at.", "anyOf": [ { "$ref": "#/components/schemas/DateRange" }, { "type": "null" } ] } } }, "AttributeFilter": { "type": "object", "properties": { "in": { "description": "Changed attributes the change must be one of.", "example": [ "DISPLAYED_PRICE" ], "type": "array", "items": { "type": "string", "enum": [ "DISPLAYED_PRICE", "DISPLAYED_AREA", "DESCRIPTION", "TITLE", "FEATURES", "ROOMS", "BEDROOMS", "ADDRESS", "GEO_POINT", "CITY", "DISTRICT", "NEIGHBORHOOD", "LOCATION_ACCURACY", "PICTURES", "MARKET_PRESENCE" ] }, "examples": [ [ "DISPLAYED_PRICE" ] ] }, "nin": { "description": "Changed attributes the change must not be. Applies to one change at a time, so a property still matches if it also has a change on one of these attributes elsewhere.", "example": [ "TITLE", "DESCRIPTION" ], "type": "array", "items": { "type": "string", "enum": [ "DISPLAYED_PRICE", "DISPLAYED_AREA", "DESCRIPTION", "TITLE", "FEATURES", "ROOMS", "BEDROOMS", "ADDRESS", "GEO_POINT", "CITY", "DISTRICT", "NEIGHBORHOOD", "LOCATION_ACCURACY", "PICTURES", "MARKET_PRESENCE" ] }, "examples": [ [ "TITLE", "DESCRIPTION" ] ] } } }, "SignedFloatRange": { "type": "object", "properties": { "gte": { "description": "Minimum value (greater than or equal). May be negative.", "example": -5, "type": [ "number", "null" ], "examples": [ -5 ] }, "lte": { "description": "Maximum value (less than or equal). May be negative.", "example": -3, "type": [ "number", "null" ], "examples": [ -3 ] } } }, "PropertySearch.PropertySearchRequestInput": { "type": "object", "properties": { "criteria": { "description": "Search criteria tree. A node is one of: a flat set of filters (most common); {\"and\": [...]} requiring all children to match; {\"or\": [...]} requiring at least one child to match. Omit to match all properties.", "anyOf": [ { "$ref": "#/components/schemas/CriteriaNode" }, { "type": "null" } ] }, "paginationType": { "description": "Pagination mode — \"PAGE\" (default, offset-based) or \"CURSOR\" (cursor-based). In \"PAGE\" mode, use page+size. In \"CURSOR\" mode, use cursor+size.", "default": "PAGE", "example": "PAGE", "type": "string", "enum": [ "PAGE", "CURSOR" ], "nullable": false, "examples": [ "PAGE" ] }, "page": { "minimum": 1, "description": "Page number (1-based). Honored only when paginationType is \"PAGE\".", "default": 1, "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "size": { "minimum": 0, "maximum": 100, "description": "Number of items per page, from 0 to 100. With 0 the response carries no item, only the number of matching properties, readable as meta.totalItems in the JSON:API format and reported up to 10,000 in \"PAGE\" mode.", "default": 10, "example": 10, "type": "integer", "examples": [ 10 ] }, "cursor": { "description": "Opaque cursor for the next page, returned from the previous response. Honored only when paginationType is \"CURSOR\". Omit or set to null for the first page.", "example": "eyJzb3J0IjpbMTc3ODg0NDY0MzAwMCwiMDE5Z", "type": [ "string", "null" ], "examples": [ "eyJzb3J0IjpbMTc3ODg0NDY0MzAwMCwiMDE5Z" ] }, "sort": { "description": "Sort directive (field + direction). Defaults to updatedAt DESC when omitted. A tiebreaker is appended for stable pagination.", "anyOf": [ { "$ref": "#/components/schemas/Sort" }, { "type": "null" } ] } } }, "Sort": { "type": "object", "required": [ "field" ], "properties": { "field": { "description": "Field to sort on. One of CREATED_AT, UPDATED_AT, PRICE, AREA, PRICE_PER_AREA.", "example": "PRICE", "type": "string", "enum": [ "CREATED_AT", "UPDATED_AT", "PRICE", "AREA", "PRICE_PER_AREA" ], "nullable": true, "examples": [ "PRICE" ] }, "direction": { "description": "Sort direction (ASC or DESC). Defaults to DESC.", "default": "DESC", "example": "DESC", "type": "string", "enum": [ "ASC", "DESC" ], "nullable": false, "examples": [ "DESC" ] } } }, "Alert.AlertRequestInput": { "type": "object", "properties": { "name": { "maxLength": 255, "description": "Human-readable alert name, surfaced in the user dashboard. Optional — clients can leave it blank and rely on the generated criteria summary. On update, omit it to keep the current name, or send null to clear it.", "example": "2-bedroom apartments in Paris", "type": [ "string", "null" ], "examples": [ "2-bedroom apartments in Paris" ] }, "enabled": { "description": "Whether the alert is enabled. A disabled alert stops matching new listings and sends nothing, including notifications already queued for it. New alerts are enabled; on update, omit it to keep the current value.", "example": true, "type": "boolean", "examples": [ true ] }, "criteria": { "anyOf": [ { "$ref": "#/components/schemas/Alert.CriteriaNode" }, { "type": "null" } ] }, "notificationDestination": { "description": "Notification destination. Provide exactly one destination input. On create, omit it to use your default destination at delivery time; on update, omit it to keep the current destination, or send null to go back to your default.", "anyOf": [ { "$ref": "#/components/schemas/NotificationDestination" }, { "type": "null" } ] }, "notificationConfig": { "description": "Notification configuration, which selects the event types you receive. On create, omit it and the alert never notifies; on update, omit it to keep the current configuration, or send null to stop notifying.", "anyOf": [ { "$ref": "#/components/schemas/AlertNotificationConfig" }, { "type": "null" } ] } } }, "NotificationDestination": { "type": "object", "properties": { "eventDestination": { "description": "Existing event destination to link. Provide only one destination input.", "example": "/account/event-destinations/01926b8a-5d2c-7b1e-8a4f-9c3d2e1b7a05", "type": [ "string", "null" ], "format": "iri-reference", "examples": [ "/account/event-destinations/01926b8a-5d2c-7b1e-8a4f-9c3d2e1b7a05" ] }, "webhookUrl": { "description": "Webhook URL; creates or reuses a webhook destination. Provide only one destination input.", "example": "https://your-server.com/webhooks/alerts", "type": [ "string", "null" ], "examples": [ "https://your-server.com/webhooks/alerts" ] } } }, "AlertForecast.AlertForecastInput": { "type": "object", "properties": { "criteria": { "anyOf": [ { "$ref": "#/components/schemas/Alert.CriteriaNode" }, { "type": "null" } ] } } }, "Alert.PropertyFacetFilters": { "type": "object", "properties": { "type": { "description": "Property-type filter (in / nin). Targets property.propertyType.", "anyOf": [ { "$ref": "#/components/schemas/PropertyTypeFilters" }, { "type": "null" } ] }, "constructionStatus": { "description": "Construction-status filter (in / nin / inOrMissing). Omitting any construction-status filter across the whole search restricts results to OLD or not-yet-qualified properties by default.", "anyOf": [ { "$ref": "#/components/schemas/ConstructionStatusFilters" }, { "type": "null" } ] }, "transaction": { "description": "Transaction facet filter (type).", "anyOf": [ { "$ref": "#/components/schemas/TransactionFilters" }, { "type": "null" } ] }, "pricing": { "description": "Pricing facet filters (displayed, pricePerArea, sale + rental subtrees).", "anyOf": [ { "$ref": "#/components/schemas/PricingFilters" }, { "type": "null" } ] }, "areas": { "description": "Area filters (area.displayed headline plus land).", "anyOf": [ { "$ref": "#/components/schemas/AreasFilters" }, { "type": "null" } ] }, "locations": { "description": "Geographic filter (in / nin sets, accuracy).", "anyOf": [ { "$ref": "#/components/schemas/LocationFilters" }, { "type": "null" } ] }, "unit": { "description": "Unit-interior filters (features, rooms, bedrooms, diagnostic, energy).", "anyOf": [ { "$ref": "#/components/schemas/UnitFilters" }, { "type": "null" } ] }, "building": { "description": "Building filters (construction year, renovation year, number of lots, type, condition, energy).", "anyOf": [ { "$ref": "#/components/schemas/BuildingFilters" }, { "type": "null" } ] }, "amenities": { "description": "Amenity feature filters (in / nin / inOrMissing).", "anyOf": [ { "$ref": "#/components/schemas/AmenityFilters" }, { "type": "null" } ] }, "body": { "description": "Free-text body filters (title, description).", "anyOf": [ { "$ref": "#/components/schemas/BodyFilters" }, { "type": "null" } ] } } }, "Alert.Filters": { "type": "object", "properties": { "property": { "anyOf": [ { "$ref": "#/components/schemas/Alert.PropertyFacetFilters" }, { "type": "null" } ] }, "publisher": { "description": "Publisher filters (type, mandate, references, contact-presence) — all clauses apply to the SAME publisher (intra-publisher semantic). For cross-publisher independent matching, combine multiple publisher blocks via and: at the criteria tree level.", "anyOf": [ { "$ref": "#/components/schemas/PublisherFilters" }, { "type": "null" } ] }, "listings": { "description": "Listing-level filters targeting the nested listings.* (url, sources, marketing flags) — all clauses apply to the SAME listing.", "anyOf": [ { "$ref": "#/components/schemas/ListingsFilters" }, { "type": "null" } ] } } }, "Alert.AndNode": { "type": "object", "properties": { "and": { "minItems": 2, "maxItems": 10, "description": "Child nodes — all must match.", "type": "array", "items": { "$ref": "#/components/schemas/Alert.CriteriaNode" } } } }, "Alert.OrNode": { "type": "object", "properties": { "or": { "minItems": 2, "maxItems": 10, "description": "Child nodes — at least one must match.", "type": "array", "items": { "$ref": "#/components/schemas/Alert.CriteriaNode" } } } }, "Alert.CriteriaNode": { "description": "An alert criteria node. Same shapes as the property-search criteria (a flat Filters object, {\"and\": [...]}, or {\"or\": [...]}) but the dates, changes and property.id filters are not supported — they only apply to property search.", "oneOf": [ { "$ref": "#/components/schemas/Alert.Filters" }, { "$ref": "#/components/schemas/Alert.AndNode" }, { "$ref": "#/components/schemas/Alert.OrNode" } ] }, "PropertySearchResult.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "enum": [ "Property" ], "example": "Property", "examples": [ "Property" ] }, "attributes": { "description": "Aggregated canonical view of the property (carries the property timestamps).", "$ref": "#/components/schemas/PropertySection" }, "relationships": { "type": "object", "properties": { "listings": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Listing" ], "example": "Listing", "examples": [ "Listing" ] }, "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } } }, "required": [ "data" ] }, "publishers": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Publisher" ], "example": "Publisher", "examples": [ "Publisher" ] }, "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } } }, "required": [ "data" ] }, "propertyPublishers": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PropertyPublisher" ], "example": "PropertyPublisher", "examples": [ "PropertyPublisher" ] }, "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } } }, "required": [ "data" ] } }, "required": [ "listings", "publishers", "propertyPublishers" ] }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ], "example": "/properties/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/properties/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "required": [ "type", "id" ] }, "ListingSection.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "enum": [ "Listing" ], "example": "Listing", "examples": [ "Listing" ] }, "attributes": { "type": "object", "properties": { "url": { "description": "URL to the original listing. Absent when the listing comes from a protected source the caller is not allowed to see.", "example": "https://www.example-realestate.com/listings/019dedb1", "type": [ "string", "null" ], "examples": [ "https://www.example-realestate.com/listings/019dedb1" ] }, "publishedAt": { "description": "Date the listing was first published (ISO 8601).", "example": "2026-04-15T09:00:00+00:00", "type": [ "string", "null" ], "examples": [ "2026-04-15T09:00:00+00:00" ] }, "expiredAt": { "description": "Date the listing expired (ISO 8601).", "example": "2026-07-15T09:00:00+00:00", "type": [ "string", "null" ], "examples": [ "2026-07-15T09:00:00+00:00" ] }, "lastSeenAt": { "description": "Last date the listing was observed alive at the source (ISO 8601). Surfaces listing freshness for clients.", "example": "2026-05-12T08:30:00+00:00", "type": [ "string", "null" ], "examples": [ "2026-05-12T08:30:00+00:00" ] }, "title": { "description": "Variant title, present only when it diverges from property.body.title (different normalized hash).", "example": "Bright 3-room apartment with balcony", "type": [ "string", "null" ], "examples": [ "Bright 3-room apartment with balcony" ] }, "description": { "description": "Variant description, present only when it diverges from property.body.description (different normalized hash).", "example": "Renovated flat on a quiet street, close to transit and shops.", "type": [ "string", "null" ], "examples": [ "Renovated flat on a quiet street, close to transit and shops." ] }, "createdAt": { "description": "Crawl creation date (ISO 8601).", "default": "", "example": "2026-04-15T09:05:00+00:00", "type": "string", "examples": [ "2026-04-15T09:05:00+00:00" ] }, "updatedAt": { "description": "Crawl last-update date (ISO 8601).", "default": "", "example": "2026-05-12T08:30:00+00:00", "type": "string", "examples": [ "2026-05-12T08:30:00+00:00" ] }, "area": { "description": "Variant displayed area, present only when it differs from property.area.displayed.", "example": 54, "type": [ "number", "null" ], "examples": [ 54 ] }, "rooms": { "description": "Variant rooms count, present only when it differs from property.unit.rooms.", "example": 3, "type": [ "integer", "null" ], "examples": [ 3 ] }, "bedrooms": { "description": "Variant bedrooms count, present only when it differs from property.unit.bedrooms.", "example": 2, "type": [ "integer", "null" ], "examples": [ 2 ] }, "bathrooms": { "description": "Variant bathrooms count, present only when it differs from property.unit.bathrooms.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "showerRooms": { "description": "Variant shower-rooms count.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "wc": { "description": "Variant WC count.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "livingRooms": { "description": "Variant living-rooms count.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "kitchens": { "description": "Variant kitchens count.", "example": 1, "type": [ "integer", "null" ], "examples": [ 1 ] }, "floor": { "description": "Variant floor number.", "example": 2, "type": [ "integer", "null" ], "examples": [ 2 ] }, "lastFloor": { "description": "Variant last-floor flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "groundFloor": { "description": "Variant ground-floor flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "gardenFloor": { "description": "Variant garden-floor flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "condition": { "description": "Variant condition, present only when it differs from property.unit.condition.", "example": "TO_RENOVATE", "type": "string", "enum": [ "NEW", "GOOD", "TO_RENOVATE" ], "nullable": true, "examples": [ "TO_RENOVATE" ] }, "furnished": { "description": "Variant furnished flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "disabledAccess": { "description": "Variant disabled-access flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "equippedKitchen": { "description": "Variant equipped-kitchen flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "fireplace": { "description": "Variant fireplace flag.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "airConditioning": { "description": "Variant air-conditioning flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "doubleGlazing": { "description": "Variant double-glazing flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "parquet": { "description": "Variant parquet flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "balcony": { "description": "Variant balcony flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "terrace": { "description": "Variant terrace flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "garden": { "description": "Variant garden flag.", "type": [ "boolean", "null" ], "example": false, "examples": [ false ] }, "dressing": { "description": "Variant dressing-room flag.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "crossing": { "description": "Variant crossing-apartment flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "quiet": { "description": "Variant quiet flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "cellar": { "description": "Variant cellar flag.", "example": true, "type": [ "boolean", "null" ], "examples": [ true ] }, "basement": { "description": "Variant basement flag.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "storage": { "description": "Variant storage-room flag.", "type": [ "boolean", "null" ], "example": true, "examples": [ true ] }, "transactionStatus": { "description": "Variant transaction status, present only when it differs from property.transactionStatus.", "example": "SOLD", "type": "string", "enum": [ "AVAILABLE", "UNDER_OFFER", "SOLD", "RENTED", "WITHDRAWN" ], "nullable": true, "examples": [ "SOLD" ] }, "displayedPrice": { "description": "Variant displayed price, present only when it differs from property.pricing.displayed.", "example": 420000, "type": [ "number", "null" ], "examples": [ 420000 ] }, "propertyType": { "description": "Variant property type (rare, indicates upstream data quality issue).", "example": "FLAT", "type": "string", "enum": [ "FLAT", "HOUSE", "BUILDING", "PARKING", "OFFICE", "LAND", "SHOP", "COMMERCIAL_PREMISES" ], "nullable": true, "examples": [ "FLAT" ] }, "transactionType": { "description": "Variant transaction type (rare, indicates upstream data quality issue).", "example": "SELL", "type": "string", "enum": [ "SELL", "RENT" ], "nullable": true, "examples": [ "SELL" ] }, "marketing": { "description": "Source-side marketing signals (favorite count, urgent/boosted/highlighted flags).", "anyOf": [ { "$ref": "#/components/schemas/ListingMarketing" }, { "type": "null" } ] } } }, "relationships": { "type": "object", "properties": { "publisher": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Publisher" ], "example": "Publisher", "examples": [ "Publisher" ] }, "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] }, { "type": "null" } ] } }, "required": [ "data" ] }, "source": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Source" ], "example": "Source", "examples": [ "Source" ] }, "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] }, { "type": "null" } ] } }, "required": [ "data" ] } }, "required": [ "publisher", "source" ] } }, "required": [ "type", "id" ] }, "PublisherSection.jsonapi": { "type": "object", "description": "", "deprecated": false, "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "enum": [ "Publisher" ], "example": "Publisher", "examples": [ "Publisher" ] }, "attributes": { "type": "object", "properties": { "publisherType": { "description": "Publisher type.", "example": "REAL_ESTATE_AGENCY", "type": "string", "enum": [ "PRIVATE_INDIVIDUAL", "REAL_ESTATE_AGENCY", "COMMERCIAL_AGENT", "MANDATED_AGENT", "PROFESSIONAL_UNKNOWN" ], "nullable": true, "examples": [ "REAL_ESTATE_AGENCY" ] }, "agencyName": { "description": "Agency name (when applicable).", "example": "Foncia Paris 18", "type": [ "string", "null" ], "examples": [ "Foncia Paris 18" ] }, "professionalCardNumber": { "description": "Professional card number (FR: carte T).", "example": "12345", "type": [ "string", "null" ], "examples": [ "12345" ] }, "website": { "description": "Publisher website.", "example": "https://www.foncia-paris18.example.com", "type": [ "string", "null" ], "examples": [ "https://www.foncia-paris18.example.com" ] } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ], "example": "/publishers/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/publishers/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "required": [ "type", "id" ] }, "SourceSection.jsonapi": { "type": "object", "description": "Source the listing was crawled from, as a JSON:API included resource.", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "enum": [ "Source" ], "example": "Source", "examples": [ "Source" ] }, "attributes": { "type": "object", "properties": { "slug": { "type": "string", "description": "URL-friendly identifier of the source.", "example": "realty-portal", "examples": [ "realty-portal" ] } } }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ], "example": "/sources/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/sources/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } } }, "required": [ "id", "type", "attributes" ] }, "PropertyPublisher.jsonapi": { "type": "object", "description": "What one publisher states on one property: its mandate, its listing reference and its contact.", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "type": { "type": "string", "enum": [ "PropertyPublisher" ], "example": "PropertyPublisher", "examples": [ "PropertyPublisher" ] }, "attributes": { "type": "object", "properties": { "mandate": { "description": "Canonical mandate the publisher uses on this property. Publishers grouped by id; mandate and publishing reference are single canonical values (most frequent + tie-break by most recent listing); contact is the most recently verified one.", "example": "EXCLUSIVE", "type": "string", "enum": [ "NON_EXCLUSIVE", "EXCLUSIVE", "SEMI_EXCLUSIVE" ], "nullable": true, "examples": [ "EXCLUSIVE" ] }, "reference": { "description": "Canonical reference the publisher uses on this property (the agency's internal listing reference, \"publishing reference\" in legacy parlance).", "example": "REF-AB42", "type": [ "string", "null" ], "examples": [ "REF-AB42" ] }, "contact": { "description": "Most recently verified contact information for this publisher.", "anyOf": [ { "$ref": "#/components/schemas/Publisher.Contact" }, { "type": "null" } ] } } }, "relationships": { "type": "object", "properties": { "property": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Property" ], "example": "Property", "examples": [ "Property" ] }, "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } }, "required": [ "data" ] }, "publisher": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Publisher" ], "example": "Publisher", "examples": [ "Publisher" ] }, "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } }, "required": [ "type", "id" ] } }, "required": [ "data" ] } }, "required": [ "property", "publisher" ] } }, "required": [ "id", "type", "attributes", "relationships" ] }, "PropertySearchResultDocument.jsonapi": { "type": "object", "description": "JSON:API document envelope for a single property search result.", "properties": { "data": { "$ref": "#/components/schemas/PropertySearchResult.jsonapi" }, "links": { "type": "object", "properties": { "self": { "type": [ "string", "null" ], "example": "/properties/3fa85f64-5717-4562-b3fc-2c963f66afa6", "examples": [ "/properties/3fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } }, "included": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ListingSection.jsonapi" }, { "$ref": "#/components/schemas/PublisherSection.jsonapi" }, { "$ref": "#/components/schemas/PropertyPublisher.jsonapi" }, { "$ref": "#/components/schemas/SourceSection.jsonapi" } ] }, "example": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Listing", "attributes": { "url": "https://www.example-realestate.com/listings/019dedb1", "publishedAt": "2026-04-15T09:00:00+00:00", "expiredAt": "2026-07-15T09:00:00+00:00", "lastSeenAt": "2026-05-12T08:30:00+00:00", "title": "Bright 3-room apartment with balcony", "description": "Renovated flat on a quiet street, close to transit and shops.", "createdAt": "2026-04-15T09:05:00+00:00", "updatedAt": "2026-05-12T08:30:00+00:00", "area": 54, "rooms": 3, "bedrooms": 2, "bathrooms": 1, "showerRooms": 1, "wc": 1, "livingRooms": 1, "kitchens": 1, "floor": 2, "lastFloor": false, "groundFloor": false, "gardenFloor": false, "condition": "TO_RENOVATE", "furnished": false, "disabledAccess": false, "equippedKitchen": true, "fireplace": true, "airConditioning": false, "doubleGlazing": true, "parquet": true, "balcony": true, "terrace": false, "garden": false, "dressing": true, "crossing": true, "quiet": true, "cellar": true, "basement": true, "storage": true, "transactionStatus": "SOLD", "displayedPrice": 420000, "propertyType": "FLAT", "transactionType": "SELL", "marketing": { "favorites": 12, "urgent": false, "boosted": true, "highlighted": true } }, "relationships": { "publisher": { "data": { "type": "Publisher", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "source": { "data": { "type": "Source", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Publisher", "attributes": { "publisherType": "REAL_ESTATE_AGENCY", "agencyName": "Foncia Paris 18", "professionalCardNumber": "12345", "website": "https://www.foncia-paris18.example.com" }, "links": { "self": "/publishers/3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "PropertyPublisher", "attributes": { "mandate": "EXCLUSIVE", "reference": "REF-AB42", "contact": { "email": "contact@foncia-paris18.example.com", "phone": "+33123456789", "profileUrl": "https://www.example-realestate.com/agencies/foncia-paris18" } }, "relationships": { "property": { "data": { "type": "Property", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "publisher": { "data": { "type": "Publisher", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Source", "attributes": { "slug": "realty-portal" }, "links": { "self": "/sources/3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "examples": [ [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Listing", "attributes": { "url": "https://www.example-realestate.com/listings/019dedb1", "publishedAt": "2026-04-15T09:00:00+00:00", "expiredAt": "2026-07-15T09:00:00+00:00", "lastSeenAt": "2026-05-12T08:30:00+00:00", "title": "Bright 3-room apartment with balcony", "description": "Renovated flat on a quiet street, close to transit and shops.", "createdAt": "2026-04-15T09:05:00+00:00", "updatedAt": "2026-05-12T08:30:00+00:00", "area": 54, "rooms": 3, "bedrooms": 2, "bathrooms": 1, "showerRooms": 1, "wc": 1, "livingRooms": 1, "kitchens": 1, "floor": 2, "lastFloor": false, "groundFloor": false, "gardenFloor": false, "condition": "TO_RENOVATE", "furnished": false, "disabledAccess": false, "equippedKitchen": true, "fireplace": true, "airConditioning": false, "doubleGlazing": true, "parquet": true, "balcony": true, "terrace": false, "garden": false, "dressing": true, "crossing": true, "quiet": true, "cellar": true, "basement": true, "storage": true, "transactionStatus": "SOLD", "displayedPrice": 420000, "propertyType": "FLAT", "transactionType": "SELL", "marketing": { "favorites": 12, "urgent": false, "boosted": true, "highlighted": true } }, "relationships": { "publisher": { "data": { "type": "Publisher", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "source": { "data": { "type": "Source", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Publisher", "attributes": { "publisherType": "REAL_ESTATE_AGENCY", "agencyName": "Foncia Paris 18", "professionalCardNumber": "12345", "website": "https://www.foncia-paris18.example.com" }, "links": { "self": "/publishers/3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "PropertyPublisher", "attributes": { "mandate": "EXCLUSIVE", "reference": "REF-AB42", "contact": { "email": "contact@foncia-paris18.example.com", "phone": "+33123456789", "profileUrl": "https://www.example-realestate.com/agencies/foncia-paris18" } }, "relationships": { "property": { "data": { "type": "Property", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "publisher": { "data": { "type": "Publisher", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } }, { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Source", "attributes": { "slug": "realty-portal" }, "links": { "self": "/sources/3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ] ] } }, "required": [ "data", "links" ] }, "PublisherDocument.jsonapi": { "type": "object", "description": "JSON:API document envelope for a publisher.", "properties": { "data": { "$ref": "#/components/schemas/Publisher.jsonapi" } }, "required": [ "data" ] } }, "responses": {}, "parameters": {}, "examples": {}, "requestBodies": {}, "headers": {}, "securitySchemes": { "apiKey": { "type": "apiKey", "description": "Value for the X-API-KEY header parameter.", "name": "X-API-KEY", "in": "header" } } }, "security": [ { "apiKey": [] } ], "tags": [ { "name": "Tenant", "description": "Resource 'Tenant' operations." }, { "name": "Email", "description": "Admin history of one email in one language: every revision ever written, draft or published, and which\none is on the air. A version is a revision — creating one never changes what is sent; publishing one is\na separate, more privileged act. Once published a version is immutable for good, and publishing it\nagain appends a copy, so the history stays a record of what was actually sent." }, { "name": "User", "description": "Resource 'User' operations." }, { "name": "Billing", "description": "What the customer holds, and where the rest went." }, { "name": "Property", "description": "Resource 'Property' operations." }, { "name": "AdminSourceCategory", "description": "Resource 'AdminSourceCategory' operations." }, { "name": "AdminSource", "description": "Resource 'AdminSource' operations." }, { "name": "Storage", "description": "Resource 'Storage' operations." }, { "name": "Crawl", "description": "Resource 'Crawl' operations." }, { "name": "Alert", "description": "Resource 'Alert' operations." }, { "name": "Account", "description": "Resource 'Account' operations." }, { "name": "Analytics", "description": "Resource 'Analytics' operations." }, { "name": "ApiKey", "description": "Resource 'ApiKey' operations." }, { "name": "Transaction", "description": "Public API for closed real-estate transactions." }, { "name": "EventNotification", "description": "Resource 'EventNotification' operations." }, { "name": "FavoriteProperty", "description": "Resource 'FavoriteProperty' operations." }, { "name": "Geo", "description": "API Platform resource for location autocomplete." } ], "webhooks": { "alertEvent": { "post": { "operationId": "alertEventWebhook", "tags": [ "EventNotification" ], "responses": { "2XX": { "description": "Any 2xx status acknowledges receipt. The response body is ignored." }, "default": { "description": "Any non-2xx status (and any timeout or connection error) is treated as a delivery failure and triggers a retry." } }, "summary": "Alert event triggered", "description": "Sent to your webhook URL when an alert event fires. Verify the HMAC signature (see headers below) and reply with a 2xx status; anything else is retried up to 4 times with exponential back-off. The same event may arrive more than once: use eventId as your idempotency key. The signing key is returned a single time, on the response that creates the first webhook destination of your account; rotate it from your dashboard.", "parameters": [ { "name": "X-Webhook-Timestamp", "in": "header", "description": "Unix timestamp (seconds, UTC) when the request was signed. Included in the signed payload — reject requests with a stale timestamp to prevent replays.", "required": true, "deprecated": false, "schema": { "type": "string", "example": "1716304200" }, "style": "simple", "explode": false }, { "name": "X-Webhook-Signature", "in": "header", "description": "sha256={hex_hmac} — HMAC-SHA256 of {X-Webhook-Timestamp}.{raw_body} using your account signing key.", "required": true, "deprecated": false, "schema": { "type": "string", "example": "sha256=5d41402abc4b2a76b9719d911017c592..." }, "style": "simple", "explode": false }, { "name": "User-Agent", "in": "header", "description": "Always StreamEstate-Webhook/1.0.", "required": true, "deprecated": false, "schema": { "type": "string", "example": "StreamEstate-Webhook/1.0" }, "style": "simple", "explode": false } ], "requestBody": { "description": "Signed alert event payload.", "content": { "application/json": { "schema": { "type": "object", "required": [ "eventType", "eventId", "alert", "listing", "data" ], "properties": { "eventType": { "type": "string", "enum": [ "NEW_MATCH", "PRICE_CHANGE", "OTHER_CHANGE", "EXPIRED", "REACTIVATED" ], "description": "Type of alert event that triggered the notification." }, "eventId": { "type": "string", "format": "uuid", "description": "Unique identifier of this delivery. The same eventId may be delivered more than once on retry — use it as your idempotency key." }, "alert": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Id of the alert that matched." }, "name": { "type": [ "string", "null" ], "description": "Name of the alert that matched. Null when the alert has no name." } } }, "listing": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Id of the listing whose update triggered this event, within the data.listings array below." } } }, "data": { "type": "object", "additionalProperties": true, "description": "Full property representation — the exact body returned by GET /properties/{id}. Embedded so you can ingest the match without an extra (billed) API call. It reflects the freshest indexed state at delivery time, not a point-in-time snapshot of the event. Protected sources are masked according to your account permissions, exactly as on the API." } } }, "example": { "eventType": "NEW_MATCH", "eventId": "01926b8a-7c1d-7f3a-9b2e-5a8f4d6c1e90", "alert": { "id": "01926b8a-5d2c-7b1e-8a4f-9c3d2e1b7a05", "name": "Paris 2-bed under 2k" }, "listing": { "id": "019dedb1-ff41-7e5a-bd16-6900cbd8c004" }, "data": { "id": "019dedb1-fdf4-714c-8392-5b9cfd63cde3", "property": { "createdAt": "2026-04-15T09:05:00+00:00", "updatedAt": "2026-05-12T08:30:00+00:00", "propertyType": "FLAT", "transaction": { "type": "SELL", "status": "AVAILABLE", "saleType": "STANDARD", "availableAt": "2026-06-01" }, "area": { "displayed": 56, "unit": "SQM", "indoor": { "legal": { "value": 55.4, "law": "CARREZ" }, "living": 56, "total": 60 }, "outdoor": { "balcony": 4.5 } }, "unit": { "rooms": 3, "bedrooms": 2, "bathrooms": 1, "wc": 1, "livingRooms": 1, "kitchens": 1, "floor": 2, "lastFloor": false, "groundFloor": false, "gardenFloor": false, "orientation": [ "SOUTH", "WEST" ], "condition": "GOOD", "furnished": false, "disabledAccess": false, "equippedKitchen": true, "fireplace": false, "airConditioning": false, "doubleGlazing": true, "parquet": true, "balcony": true, "terrace": false, "garden": false, "dressing": false, "crossing": true, "quiet": true, "cellar": true, "basement": false, "storage": false, "diagnostic": { "type": "DPE", "date": "2024-06-15", "scores": { "ENERGY_CONSUMPTION": { "rating": "D", "value": 245, "unit": "KWH_EP_PER_SQM_YEAR" }, "CARBON_EMISSIONS": { "rating": "D", "value": 35, "unit": "KG_CO2E_PER_SQM_YEAR" } } }, "energy": { "heating": [ { "system": "BOILER", "energyCarrier": "GAS", "collective": true } ] } }, "building": { "constructionYear": 1900, "renovationYear": 2020, "constructionType": "HAUSSMANNIAN", "condition": "GOOD", "floors": 6, "numberOfLots": 45, "legalStatus": { "underLegalProceedings": false }, "energy": { "heating": [ { "system": "BOILER", "energyCarrier": "GAS", "collective": true } ] } }, "amenities": { "elevator": true, "intercom": true, "digicode": true, "caretaker": true, "bikeRoom": true, "disabledAccess": false, "gym": false, "playground": false, "partyHall": false, "sportCourt": false, "adultGameRoom": false, "gatedCommunity": false, "barbecueGrill": false, "swimmingPool": false, "connectivity": [ "FIBER" ] }, "body": { "title": "Beautiful flat in Paris", "description": "Renovated flat on a quiet street, close to transit and shops." }, "pricing": { "displayed": 400000, "currency": "EUR", "sale": { "netPrice": 376000, "fees": { "agency": { "amount": 24000, "percentage": 6, "currency": "EUR", "paidBy": "BUYER", "includedInPrice": true }, "legal": { "type": "NOTARY", "currency": "EUR", "amount": 30000, "percentage": 7.5, "paidBy": "BUYER" }, "condominium": { "total": 1020, "currency": "EUR", "frequency": "MONTHLY", "breakdown": [ { "type": "MAINTENANCE", "amount": 85, "currency": "EUR", "frequency": "MONTHLY" } ] }, "taxes": { "propertyTax": { "amount": 1200, "currency": "EUR", "frequency": "YEARLY", "paidBy": "OWNER" } } } } }, "location": { "geometry": { "type": "Point", "coordinates": [ 2.3522, 48.8566 ] }, "accuracy": "NEIGHBORHOOD", "address": "10 rue Eugène Sue", "countryCode": "FR", "city": { "iri": "/geo/administrative-divisions/019dedb1-fdf4-714c-8392-5b9cfd63cde3", "id": "019dedb1-fdf4-714c-8392-5b9cfd63cde3", "name": "Paris 18e Arrondissement", "type": "MUNICIPAL_DISTRICT", "uniqueCode": "75118", "postalCodes": [ "75018" ] }, "neighborhood": { "iri": "/geo/administrative-divisions/019dedb2-1111-7222-8333-444455556666", "id": "019dedb2-1111-7222-8333-444455556666", "name": "Grandes-Carrières", "type": "NEIGHBORHOOD" } }, "pictures": [ { "url": "https://cdn.stream.estate/storage/properties/2026/10/14/01/019dedb1-aaa1-7c3d-8e4f-5a6b7c8d9e01.webp" }, { "url": "https://cdn.stream.estate/storage/properties/2026/10/14/01/019dedb1-aaa2-7c3d-8e4f-5a6b7c8d9e02.webp" }, { "url": "https://cdn.stream.estate/storage/properties/2026/10/14/01/019dedb1-aaa3-7c3d-8e4f-5a6b7c8d9e03.webp" } ] }, "publishers": [ { "id": "019d0000-0000-7000-8000-000000000001", "publisherType": "REAL_ESTATE_AGENCY", "agencyName": "Foncia Paris 18", "professionalCardNumber": "12345", "website": "https://www.foncia-paris18.example.com", "mandate": "EXCLUSIVE", "reference": "REF-AB42", "contact": { "email": "contact@foncia-paris18.example.com", "phone": "+33123456789", "profileUrl": "https://www.example-realestate.com/agencies/foncia-paris18" } } ], "listings": [ { "id": "019dedb1-ff41-7e5a-bd16-6900cbd8c004", "url": "https://www.example-realestate.com/listings/019dedb1", "source": { "iri": "/sources/019d0000-0000-7000-8000-000000000001", "uuid": "019d0000-0000-7000-8000-000000000001", "slug": "example-source" }, "publishedAt": "2026-04-15T09:00:00+00:00", "lastSeenAt": "2026-05-12T08:30:00+00:00", "createdAt": "2026-04-15T09:05:00+00:00", "updatedAt": "2026-05-12T08:30:00+00:00", "marketing": { "favorites": 12, "urgent": false, "boosted": true, "highlighted": true } }, { "id": "019dedb2-7c10-71aa-9f02-2b77e0a1d655", "url": "https://www.other-source.example.com/annonce/019dedb2", "source": { "iri": "/sources/019d0000-0000-7000-8000-000000000002", "uuid": "019d0000-0000-7000-8000-000000000002", "slug": "other-source" }, "publishedAt": "2026-04-18T14:30:00+00:00", "lastSeenAt": "2026-05-11T07:15:00+00:00", "createdAt": "2026-04-18T14:35:00+00:00", "updatedAt": "2026-05-11T07:15:00+00:00", "title": "Bright 3-room apartment with balcony", "displayedPrice": 420000, "marketing": { "favorites": 5, "urgent": false, "boosted": false, "highlighted": false } } ] } } } }, "required": true } } } } }