stream-estate Properties API

openapi: 3.2.0
info:
  title: Stream Estate Properties API
  description: The Stream Estate API is designed to enable builders to easily query, observe, and automate real estate data and insights. All API calls require the `X-API-KEY` header. Sign up at https://stream.estate/signup and create an API key in your settings.
  version: 1.0.0
  contact:
    url: https://stream.estate
servers:
- url: https://api.stream.estate
security:
- apiKey: []
tags:
- name: Properties
  description: Query aggregated real estate properties and their adverts.
paths:
  /documents/properties:
    get:
      tags:
      - Properties
      summary: List properties
      description: Returns a collection of properties matching given criteria.
      operationId: getProperties
      parameters:
      - name: advertPriceMin
        in: query
        description: Minimum price of advert. Filters properties based on any non expired adverts prices.
        schema:
          type: number
      - name: advertPriceMax
        in: query
        description: Maximum price of advert. Filters properties based on any non expired adverts prices.
        schema:
          type: number
      - name: bedroomMin
        in: query
        description: Minimum number of bedrooms in the property.
        schema:
          type: integer
      - name: bedroomMax
        in: query
        description: Maximum number of bedrooms in the property.
        schema:
          type: integer
      - name: budgetMin
        in: query
        description: Minimum budget for the property.
        schema:
          type: number
      - name: budgetMax
        in: query
        description: Maximum budget for the property.
        schema:
          type: number
      - name: condominiumFeesMin
        in: query
        description: Minimum condominium fees for the property.
        schema:
          type: number
      - name: condominiumFeesMax
        in: query
        description: Maximum condominium fees for the property.
        schema:
          type: number
      - name: constructionYearMin
        in: query
        description: Minimum construction year of the property.
        schema:
          type: integer
      - name: constructionYearMax
        in: query
        description: Maximum construction year of the property.
        schema:
          type: integer
      - name: energyCategories
        in: query
        description: 'The energy efficiency categories of the property. Example: `energyCategories[]=A&energyCategories[]=B`'
        schema:
          type: array
          items:
            type: string
            enum:
            - A
            - B
            - C
            - D
            - E
            - F
            - G
        style: form
        explode: true
      - name: energyValueMin
        in: query
        description: Minimum energy value of the property.
        schema:
          type: number
      - name: energyValueMax
        in: query
        description: Maximum energy value of the property.
        schema:
          type: number
      - name: eventPriceVariationFromCreatedAt
        in: query
        description: Date from which an event of type price is created — inclusive.
        schema:
          type: string
          format: date-time
      - name: eventPriceVariationToCreatedAt
        in: query
        description: Date before which an event of type price is created — inclusive.
        schema:
          type: string
          format: date-time
      - name: eventPriceVariationMin
        in: query
        description: Minimum percent variation of an event of type price.
        schema:
          type: number
      - name: eventPriceVariationMax
        in: query
        description: Maximum percent variation of an event of type price.
        schema:
          type: number
      - name: eventSurfaceVariationFromCreatedAt
        in: query
        description: Date from which an event of type surface is created — inclusive.
        schema:
          type: string
          format: date-time
      - name: eventSurfaceVariationToCreatedAt
        in: query
        description: Date before which an event of type surface is created — inclusive.
        schema:
          type: string
          format: date-time
      - name: eventSurfaceVariationMin
        in: query
        description: Minimum percent variation of an event of type surface.
        schema:
          type: number
      - name: eventSurfaceVariationMax
        in: query
        description: Maximum percent variation of an event of type surface.
        schema:
          type: number
      - name: excludedCities
        in: query
        description: Cities to be excluded.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: excludedInseeCodes
        in: query
        description: Insee codes to be excluded.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: excludedProperties
        in: query
        description: Properties to be excluded.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: excludedZipcodes
        in: query
        description: Zipcodes to be excluded.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: expressions
        in: query
        description: 'Full text matching including/excluding words & phrases in the title or the description of the property. Example: `expressions[0][0][word]=travaux&expressions[0][0][options][includes]=true&expressions[0][0][options][strict]=false`.'
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: feesPercentageMin
        in: query
        description: Minimum percentage of fees.
        schema:
          type: number
      - name: feesPercentageMax
        in: query
        description: Maximum percentage of fees.
        schema:
          type: number
      - name: feesResponsibility
        in: query
        description: Responsibility for fees. `0` for seller, `1` for buyer.
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: floorQuantityMin
        in: query
        description: Minimum number of floors in the property.
        schema:
          type: integer
      - name: floorQuantityMax
        in: query
        description: Maximum number of floors in the property.
        schema:
          type: integer
      - name: fromDate
        in: query
        description: Date from which the property is created — inclusive.
        schema:
          type: string
          format: date-time
      - name: toDate
        in: query
        description: 'Date until which the property is created — inclusive. Example: `toDate=2021-05-07 12:42:42`'
        schema:
          type: string
          format: date-time
      - name: fromUpdatedAt
        in: query
        description: Date from which the property is updated — inclusive.
        schema:
          type: string
          format: date-time
      - name: toUpdatedAt
        in: query
        description: Date until which the property is updated — inclusive.
        schema:
          type: string
          format: date-time
      - name: furnished
        in: query
        description: Filter for furnished properties.
        schema:
          type: boolean
      - name: geoAccuracy
        in: query
        description: 'Filters properties by geocoding confidence level: `1` (house-number level), `2` (neighborhood level).'
        schema:
          type: array
          items:
            type: integer
            enum:
            - 1
            - 2
        style: form
        explode: true
      - name: geoShapes
        in: query
        description: 'Filters properties within specified geographic areas (arrays of `[lon, lat]` points forming polygons). Example: `geoShapes[0][0][0]=6.063201&geoShapes[0][0][1]=44.549092&...`'
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: greenHouseGasCategories
        in: query
        description: Green house gas performance letter array of the property.
        schema:
          type: array
          items:
            type: string
            enum:
            - A
            - B
            - C
            - D
            - E
            - F
            - G
        style: form
        explode: true
      - name: greenHouseGasValueMin
        in: query
        description: Minimum value of green house gas of the property.
        schema:
          type: number
      - name: greenHouseGasValueMax
        in: query
        description: Maximum value of green house gas of the property.
        schema:
          type: number
      - name: includedCities
        in: query
        description: 'Located in given cities. Example: `includedCities[]=/cities/30953`. Use the location autocomplete endpoint to get the desired city IRIs.'
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: includedDepartments
        in: query
        description: 'Located in given departments. Example: `includedDepartments[]=/departments/77`. Use the location autocomplete endpoint to get the desired department IRIs.'
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: includedInseeCodes
        in: query
        description: 'Located in given insee codes. Example: `includedInseeCodes[]=75117&includedInseeCodes[]=75118`'
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: includedZipcodes
        in: query
        description: 'Located in given zipcodes. Example: `includedZipcodes[]=75017&includedZipcodes[]=75018`'
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: inventoryPriceMin
        in: query
        description: Greater than or equal to given inventory price.
        schema:
          type: number
      - name: inventoryPriceMax
        in: query
        description: Lower than or equal to given inventory price.
        schema:
          type: number
      - name: lat
        in: query
        description: 'Latitude. Will work if latitude exists in the property. Example: `lat=48.864716`'
        schema:
          type: number
      - name: lon
        in: query
        description: 'Longitude. Will work if longitude exists in the property. Example: `lon=2.349014`'
        schema:
          type: number
      - name: radius
        in: query
        description: 'Distance expressed in kilometers. Will work if latitude & longitude parameters are also set. Example: `radius=20`, `radius=0.5`'
        schema:
          type: number
      - name: lotCountMin
        in: query
        description: Greater than or equal to given lot count.
        schema:
          type: integer
      - name: lotCountMax
        in: query
        description: Lower than or equal to given lot count.
        schema:
          type: integer
      - name: priceExcludingFeesMin
        in: query
        description: Greater than or equal to given price excluding fees.
        schema:
          type: number
      - name: priceExcludingFeesMax
        in: query
        description: Lower than or equal to given price excluding fees.
        schema:
          type: number
      - name: pricePerMeterMin
        in: query
        description: Greater than or equal to given price per meter.
        schema:
          type: number
      - name: pricePerMeterMax
        in: query
        description: Lower than or equal to given price per meter.
        schema:
          type: number
      - name: propertyTypes
        in: query
        description: 'Type of property. Apartment `0`, House `1`, Building `2`, Parking `3`, Office `4`, Land `5`, Shop `6`. Example: `propertyTypes[]=0&propertyTypes[]=1`'
        schema:
          type: array
          items:
            type: integer
            enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
        style: form
        explode: true
      - name: publisherTypes
        in: query
        description: Type of publisher. Individual `0`, Professional `1`.
        schema:
          type: array
          items:
            type: integer
            enum:
            - 0
            - 1
        style: form
        explode: true
      - name: rentalChargesMin
        in: query
        description: Greater than or equal to given rental charges amount.
        schema:
          type: number
      - name: rentalChargesMax
        in: query
        description: Lower than or equal to given rental charges amount.
        schema:
          type: number
      - name: rentalPledgeMin
        in: query
        description: Greater than or equal to given rental pledge amount.
        schema:
          type: number
      - name: rentalPledgeMax
        in: query
        description: Lower than or equal to given rental pledge amount.
        schema:
          type: number
      - name: renterFeesMin
        in: query
        description: Greater than or equal to given renter fees.
        schema:
          type: number
      - name: renterFeesMax
        in: query
        description: Lower than or equal to given renter fees.
        schema:
          type: number
      - name: roomMin
        in: query
        description: Minimum rooms of the property.
        schema:
          type: integer
      - name: roomMax
        in: query
        description: Maximum rooms of the property.
        schema:
          type: integer
      - name: sortMode
        in: query
        description: Whether to sort results by properties or by adverts. If `property`, `fromDate`/`toDate` apply to the property root object; if `advert`, they apply to the nested adverts.
        schema:
          type: string
          enum:
          - property
          - advert
          default: property
      - name: surfaceMin
        in: query
        description: Greater than or equal to given surface.
        schema:
          type: number
      - name: surfaceMax
        in: query
        description: Lower than or equal to given surface.
        schema:
          type: number
      - name: transactionType
        in: query
        description: Type of transaction. Sell `0`, Rent `1`.
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: withCoherentPrice
        in: query
        description: Price coherence filter. `true` returns properties whose price passes our coherence checks; `false` returns properties flagged as incoherent — both also include properties whose price has not been assessed. Set to `null` (or send an empty value) to disable filtering. If omitted, defaults to `true`.
        schema:
          type: boolean
      - name: withLocation
        in: query
        description: Having a latitude and longitude.
        schema:
          type: boolean
      - name: withVirtualTour
        in: query
        description: Having a virtual tour video link.
        schema:
          type: boolean
      - name: expired
        in: query
        description: Whether to show properties that are expired. A property is considered expired when all its adverts are expired. Default is `null` which returns all properties no matter if they're expired or not.
        schema:
          type: boolean
      - name: fromExpiredAt
        in: query
        description: Date from which the advert is expired — inclusive.
        schema:
          type: string
          format: date-time
      - name: toExpiredAt
        in: query
        description: Date until which the advert is expired — inclusive.
        schema:
          type: string
          format: date-time
      - name: excludedSites
        in: query
        description: Source sites to be excluded.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: includedSites
        in: query
        description: Source sites to be included.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: landSurfaceMin
        in: query
        description: Minimum land surface.
        schema:
          type: number
      - name: landSurfaceMax
        in: query
        description: Maximum land surface.
        schema:
          type: number
      - name: order[createdAt]
        in: query
        description: Order properties by creation date.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: order[updatedAt]
        in: query
        description: Order properties by update date.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: order[pricePerMeter]
        in: query
        description: Order properties by price per meter.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: order[price]
        in: query
        description: Order properties by price.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: order[surface]
        in: query
        description: Order properties by surface.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: page
        in: query
        description: The collection page number.
        schema:
          type: integer
          default: 1
      - name: itemsPerPage
        in: query
        description: The number of items per page. Max is `30`.
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: Collection of properties.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyCollection'
        '400':
          description: Bad Request — your request is incorrect.
        '401':
          description: Unauthorized — your API key is wrong.
        '429':
          description: Too Many Requests — you're requesting too much! Slow down!
  /documents/properties/{id}:
    get:
      tags:
      - Properties
      summary: Get a property
      description: Returns a single property matching the given id.
      operationId: getProperty
      parameters:
      - name: id
        in: path
        required: true
        description: UUID of the selected property
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The requested property.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyDocument'
        '401':
          description: Unauthorized — your API key is wrong.
        '404':
          description: Not Found — the requested resource could not be found.
  /documents/properties/{id}/similar-properties:
    get:
      tags:
      - Properties
      summary: List similar properties
      description: Returns a collection of properties similar to given property.
      operationId: getSimilarProperties
      parameters:
      - name: id
        in: path
        required: true
        description: UUID of the selected property
        schema:
          type: string
          format: uuid
      - name: fromDate
        in: query
        description: Date from which the property is created — inclusive.
        schema:
          type: string
          format: date-time
      - name: order[createdAt]
        in: query
        description: Order properties by creation date.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: order[updatedAt]
        in: query
        description: Order properties by update date.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: order[pricePerMeter]
        in: query
        description: Order properties by price per meter.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: order[price]
        in: query
        description: Order properties by price.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: order[surface]
        in: query
        description: Order properties by surface.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: page
        in: query
        description: The collection page number.
        schema:
          type: integer
          default: 1
      - name: itemsPerPage
        in: query
        description: The number of items per page. Max is `30`.
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: Collection of similar properties.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyCollection'
        '401':
          description: Unauthorized — your API key is wrong.
        '404':
          description: Not Found — the requested resource could not be found.
components:
  schemas:
    Station:
      type: object
      description: Nearby public transport station.
      properties:
        id:
          type: integer
        lines:
          type: array
          items:
            $ref: '#/components/schemas/StationLine'
        name:
          type: string
    HydraSearch:
      type: object
      properties:
        '@type':
          type: string
        hydra:template:
          type: string
        hydra:variableRepresentation:
          type: string
        hydra:mapping:
          type: array
          items:
            type: object
            properties:
              '@type':
                type: string
              variable:
                type: string
              property:
                type: string
              required:
                type: boolean
    Publisher:
      type: object
      properties:
        category:
          type: string
        name:
          type: string
        type:
          type: integer
          description: Publisher type. Individual `0`, Professional `1`.
          enum:
          - 0
          - 1
    Contact:
      type: object
      properties:
        agency:
          type: string
        email:
          type: string
        fax:
          type: string
        name:
          type: string
        phone:
          type: string
        reference:
          type: string
    PropertyDocument:
      type: object
      description: A real estate property aggregated from one or more adverts.
      properties:
        '@context':
          type: string
        '@id':
          type: string
        '@type':
          type: string
        adverts:
          type: array
          items:
            $ref: '#/components/schemas/Advert'
        bedroom:
          type: integer
        city:
          $ref: '#/components/schemas/CityDetails'
        createdAt:
          type: string
          format: date-time
        description:
          type: string
        elevator:
          type: boolean
        expired:
          type: boolean
          description: A property is considered expired when all its adverts are expired.
        expiredAt:
          type: string
          format: date-time
        floor:
          type: integer
        furnished:
          type: boolean
        landSurface:
          type: number
        lastCrawledAdvert:
          type: string
          format: uuid
        lastCrawledAt:
          type: string
          format: date-time
        locations:
          $ref: '#/components/schemas/GeoPoint'
        pictures:
          type: array
          items:
            type: string
            format: uri
        price:
          type: number
        pricePerMeter:
          type: number
        property:
          type: string
        propertyType:
          type: integer
          description: Apartment `0`, House `1`, Building `2`, Parking `3`, Office `4`, Land `5`, Shop `6`.
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
        publisherTypes:
          type: array
          description: Individual `0`, Professional `1`.
          items:
            type: integer
            enum:
            - 0
            - 1
        room:
          type: integer
        stations:
          type: array
          items:
            $ref: '#/components/schemas/Station'
        surface:
          type: number
        title:
          type: string
        transactionType:
          type: integer
          description: Sell `0`, Rent `1`.
          enum:
          - 0
          - 1
        updatedAt:
          type: string
          format: date-time
        uuid:
          type: string
          format: uuid
    Advert:
      type: object
      description: A published listing of the property on a source site.
      properties:
        condominiumFees:
          type: number
        constructionYear:
          type: integer
        contact:
          $ref: '#/components/schemas/Contact'
        createdAt:
          type: string
          format: date-time
        description:
          type: string
        elevator:
          type: boolean
        energy:
          $ref: '#/components/schemas/EnergyRating'
        events:
          type: array
          items:
            $ref: '#/components/schemas/AdvertEvent'
        features:
          type: array
          items:
            type: string
        feesPercentage:
          type: number
        feesResponsibility:
          type: integer
          description: Responsibility for fees. `0` for seller, `1` for buyer.
          enum:
          - 0
          - 1
        floor:
          type: integer
        floorQuantity:
          type: integer
        furnished:
          type: boolean
        greenHouseGas:
          $ref: '#/components/schemas/EnergyRating'
        inventoryPrice:
          type: number
        landSurface:
          type: number
        lastCrawledAt:
          type: string
          format: date-time
        lotCount:
          type: integer
        pictures:
          type: array
          items:
            type: string
            format: uri
        picturesRemote:
          type: array
          items:
            type: string
            format: uri
        price:
          type: number
        priceExcludingFees:
          type: number
        publisher:
          $ref: '#/components/schemas/Publisher'
        rentalCharges:
          type: number
        rentalPledge:
          type: number
        renterFees:
          type: number
        surface:
          type: number
        title:
          type: string
        updatedAt:
          type: string
          format: date-time
        url:
          type: string
          format: uri
        uuid:
          type: string
          format: uuid
        virtualTour:
          type: string
          format: uri
    HydraView:
      type: object
      properties:
        '@id':
          type: string
        '@type':
          type: string
        hydra:first:
          type: string
        hydra:last:
          type: string
        hydra:next:
          type: string
    PropertyCollection:
      type: object
      description: Paginated collection of properties.
      properties:
        hydra:member:
          type: array
          items:
            $ref: '#/components/schemas/PropertyDocument'
        hydra:totalItems:
          type: integer
        hydra:view:
          $ref: '#/components/schemas/HydraView'
        hydra:search:
          $ref: '#/components/schemas/HydraSearch'
    AdvertEvent:
      type: object
      description: A change recorded on an advert (price update, surface update, ...).
      properties:
        createdAt:
          type: string
          format: date-time
        fieldName:
          type: string
        fieldNewValue:
          type: string
        fieldOldValue:
          type: string
        percentVariation:
          type: number
    CodeIdName:
      type: object
      properties:
        code:
          type: string
        id:
          type: integer
        name:
          type: string
    CityDetails:
      type: object
      description: City the property belongs to.
      properties:
        cityParentId:
          type: integer
        country:
          $ref: '#/components/schemas/CodeIdName'
        department:
          $ref: '#/components/schemas/CodeIdName'
        groupedCityNames:
          type: array
          items:
            type: string
        groupedCityZipcodes:
          type: array
          items:
            type: string
        hasGroupedByName:
          type: boolean
        hasGroupedByZipcode:
          type: boolean
        id:
          type: integer
        insee:
          type: string
        location:
          $ref: '#/components/schemas/GeoPoint'
        name:
          type: string
        open:
          type: boolean
        originalName:
          type: string
        region:
          $ref: '#/components/schemas/CodeIdName'
        zipcode:
          type: string
    StationLine:
      type: object
      properties:
        color:
          type: string
        id:
          type: integer
        name:
          type: string
        number:
          type: string
        routeName:
          type: string
    EnergyRating:
      type: object
      description: Energy / greenhouse-gas performance rating.
      properties:
        category:
          type: string
          enum:
          - A
          - B
          - C
          - D
          - E
          - F
          - G
        value:
          type: number
    GeoPoint:
      type: object
      properties:
        lat:
          type: number
        lon:
          type: number
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key created in your Stream Estate settings.