Filtrage

Le body de POST /properties repose sur un seul champ criteria — un arbre récursif dont chaque nœud prend exactement l'une de ces trois formes :

une feuille Filters (un regroupement plat de filtres par facette — le cas le plus courant) ;
un nœud AND { "and": [/* enfants */] } — tous les enfants doivent correspondre ;
un nœud OR { "or": [/* enfants */] } — au moins un enfant doit correspondre.

Omettez criteria pour faire correspondre toutes les properties.

Forme du body

{
  "criteria": { /* CriteriaNode */ },
  "paginationType": "PAGE",
  "page": 1,
  "size": 20
}

Champ	Type	Valeur
`criteria`	`CriteriaNode` \| null	Feuille `Filters`, nœud `and`, ou nœud `or`.
`paginationType`	enum	`"PAGE"` (défaut) ou `"CURSOR"`. Voir Pagination.
`page`	integer	Honoré uniquement en `PAGE`. Défaut `1`, minimum `1`.
`cursor`	string \| null	Honoré uniquement en `CURSOR`. Renvoyez la valeur reçue dans la réponse précédente.
`size`	integer	1–100. Défaut `10`.
`sort`	object	Directive de tri (champ + direction).

La feuille `Filters`

Une feuille regroupe les filtres par facette (toutes combinées en AND au sein de la feuille) :

Facette	DTO	Cible
`property`	`PropertyFacetFiltersDTO`	`type`, `transaction`, `pricing`, `areas`, `locations`, `unit`, `building`, `amenities`, `body`.
`publisher`	`PublisherFiltersDTO`	`type`, `mandate`, `references`, `hasEmail`, `hasPhone` (toutes les clauses portent sur le même publisher).
`listings`	`ListingsFiltersDTO`	`url`, `sources`, `marketing`, `expiredAt` (toutes les clauses portent sur le même listing).
`dates`	`DatesFiltersDTO`	`createdAt`, `updatedAt`.

Pour la liste exhaustive des sous-champs de chaque facette (par exemple property.pricing.displayed, property.areas.displayed, property.unit.rooms, property.locations.in, etc.), voir /api-reference — la référence est régénérée à chaque build depuis la spec live.

Exemple — feuille simple

Appartements à vendre à Paris entre 200k€ et 600k€, 3 à 5 pièces, avec balcon :

curl -X POST "https://api-v2.stream.estate/properties" \
  -H "X-API-KEY: <votre_clé>" \
  -H "Content-Type: application/json" \
  -d '{
    "criteria": {
      "property": {
        "type":      { "in": ["FLAT"] },
        "transaction": { "type": "SELL" },
        "pricing":   { "displayed": { "gte": 200000, "lte": 600000 } },
        "areas":     { "displayed": { "gte": 50 } },
        "unit":      {
          "rooms":    { "gte": 3, "lte": 5 },
          "features": { "in": ["BALCONY"] }
        },
        "locations": {
          "countryCode": "FR",
          "in": { "uniqueCodes": ["75056"] }
        }
      }
    },
    "paginationType": "PAGE",
    "page": 1,
    "size": 20
  }'

Nœuds AND / OR

Pour combiner plusieurs feuilles, utilisez and: ou or: — chaque enfant est lui-même un CriteriaNode (donc une feuille, un autre and, ou un autre or). Chaque tableau contient les nœuds enfants à combiner et peut être imbriqué à volonté.

{
  "criteria": {
    "or": [
      {
        "property": {
          "type": { "in": ["FLAT"] },
          "areas": { "displayed": { "gte": 60 } }
        }
      },
      {
        "property": {
          "type": { "in": ["HOUSE"] },
          "areas": { "displayed": { "gte": 100 }, "land": { "gte": 300 } }
        }
      }
    ]
  },
  "paginationType": "PAGE",
  "size": 20
}

Réponse

Toutes les requêtes renvoient un PropertySearchResponseDTO :

{
  "items": [ /* PropertySearchResultDTO[] */ ],
  "totalItems": 1847,
  "hasNextPage": true,
  "cursor": "eyJzb3J0Ijpb..."
}

totalItems — nombre total de matches, identique en mode PAGE et CURSOR.
hasNextPage — true s'il reste des résultats.
cursor — opaque, à renvoyer tel quel dans la requête suivante en mode CURSOR. null en mode PAGE.