stream-estate Indicators API

openapi: 3.2.0
info:
  title: Stream Estate Indicators 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: Indicators
  description: Market indicators, points of interest and location lookups.
paths:
  /indicators/price_per_meter:
    get:
      tags:
      - Indicators
      summary: Price per meter evolution
      description: Returns the price per meter `average`, `median` and `time series` of properties matching the given criteria.
      operationId: getPricePerMeter
      parameters:
      - name: aggregationInterval
        in: query
        description: Date histogram granularity for time series.
        schema:
          type: string
          enum:
          - month
          - year
          default: month
      - 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: Filter for expired properties.
        schema:
          type: boolean
      - 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: 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: 30
      responses:
        '200':
          description: Price per meter indicators.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricePerMeterCollection'
        '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!
  /indicators/points_of_interest:
    get:
      tags:
      - Indicators
      summary: Points of interest
      description: Returns the points of interest matching the given criteria.
      operationId: getPointsOfInterest
      parameters:
      - name: facilities
        in: query
        description: 'Category of points of interest. Current available categories are `kindergarten`, `school`, `restaurant`, `hospital`, `parking`. Example: `facilities[]=kindergarten&facilities[]=school`'
        schema:
          type: array
          items:
            type: string
            enum:
            - kindergarten
            - school
            - restaurant
            - hospital
            - parking
        required: true
        style: form
        explode: true
      - name: lat
        in: query
        description: Latitude.
        schema:
          type: number
        required: true
      - name: lon
        in: query
        description: Longitude.
        schema:
          type: number
        required: true
      - name: radius
        in: query
        description: Distance expressed in kilometers.
        schema:
          type: number
        required: true
      responses:
        '200':
          description: Points of interest around the given location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PointOfInterestCollection'
        '400':
          description: Bad Request — your request is incorrect.
        '401':
          description: Unauthorized — your API key is wrong.
  /public/location-autocomplete:
    get:
      tags:
      - Indicators
      summary: Location autocomplete
      description: Returns cities or departments matching the given criteria. Use the returned IRIs in `includedCities` / `includedDepartments` filters.
      operationId: locationAutocomplete
      security: []
      parameters:
      - name: query
        in: query
        description: Query term to perform search.
        schema:
          type: string
      - name: excludedCitiesIds
        in: query
        description: Exclude cities using their IRI.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: excludedDepartmentsIds
        in: query
        description: Exclude departments using their IRI.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Matching cities and departments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationAutocompleteCollection'
        '400':
          description: Bad Request — your request is incorrect.
  /cities:
    get:
      tags:
      - Indicators
      summary: List cities
      description: Returns cities matching the given criteria.
      operationId: getCities
      parameters:
      - name: excludeGroupedCities
        in: query
        description: Set to true to exclude cities that have grouped cities under them.
        schema:
          type: boolean
          default: false
      - name: insee
        in: query
        description: Filter by INSEE code.
        schema:
          type: string
      - name: insee[]
        in: query
        description: Filter by multiple INSEE codes.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: polygon
        in: query
        description: 'Filter by cities inside a given polygon defined by GPS coordinates. Example: `polygon[0][lat]=43.12&polygon[0][lon]=5.93&polygon[1][lat]=43.12&polygon[1][lon]=6.01&...`'
        schema:
          type: string
      - name: libelle
        in: query
        description: Filter by city label/display name.
        schema:
          type: string
      - name: name
        in: query
        description: Filter by city name.
        schema:
          type: string
      - name: order[name]
        in: query
        description: Sort by name.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: page
        in: query
        description: The collection page number.
        schema:
          type: integer
          default: 1
      - name: slug
        in: query
        description: Filter by city slug.
        schema:
          type: string
      - name: zipcode
        in: query
        description: Filter by zipcode.
        schema:
          type: string
      - name: zipcode[]
        in: query
        description: Filter by multiple zipcodes.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Collection of cities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CityCollection'
        '400':
          description: Bad Request — your request is incorrect.
        '401':
          description: Unauthorized — your API key is wrong.
components:
  schemas:
    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
    PricePerMeterIndicator:
      type: object
      properties:
        average:
          type: number
        average_min:
          type: number
        average_max:
          type: number
        median:
          type: number
        series:
          type: object
          description: Price per meter time series keyed by period (e.g. `2023-01`).
          additionalProperties:
            type: number
    CityCollection:
      type: object
      properties:
        hydra:member:
          type: array
          items:
            $ref: '#/components/schemas/City'
    LocationAutocompleteItem:
      type: object
      description: A city or department matching the autocomplete query.
      properties:
        '@id':
          type: string
          description: IRI usable in `includedCities` / `includedDepartments` filters.
        '@type':
          type: string
        code:
          type: string
        displayName:
          type: string
        groupedCityNames:
          type: array
          items:
            type: string
        groupedCityZipcodes:
          type: array
          items:
            type: string
        id:
          type: string
        insee:
          type: string
        libelle:
          type: string
        location:
          $ref: '#/components/schemas/GeoPoint'
        name:
          type: string
        zipcode:
          type: string
    HydraView:
      type: object
      properties:
        '@id':
          type: string
        '@type':
          type: string
        hydra:first:
          type: string
        hydra:last:
          type: string
        hydra:next:
          type: string
    PointOfInterest:
      type: object
      properties:
        lat:
          type: number
        lon:
          type: number
        name:
          type:
          - string
          - 'null'
        type:
          type: string
        attributes:
          description: Category-specific attributes (e.g. `schoolType`, `operatorType`).
          type: object
          additionalProperties: true
    LocationAutocompleteCollection:
      type: object
      properties:
        hydra:member:
          type: array
          items:
            $ref: '#/components/schemas/LocationAutocompleteItem'
    PointOfInterestCollection:
      type: object
      properties:
        '@context':
          type: string
        '@id':
          type: string
        '@type':
          type: string
        hydra:member:
          type: array
          items:
            $ref: '#/components/schemas/PointOfInterest'
        hydra:totalItems:
          type: integer
        hydra:view:
          $ref: '#/components/schemas/HydraView'
    PricePerMeterCollection:
      type: object
      description: Price per meter indicators.
      properties:
        hydra:member:
          type: array
          items:
            $ref: '#/components/schemas/PricePerMeterIndicator'
        hydra:totalItems:
          type: integer
        hydra:view:
          $ref: '#/components/schemas/HydraView'
        hydra:search:
          $ref: '#/components/schemas/HydraSearch'
    City:
      type: object
      properties:
        '@id':
          type: string
        '@type':
          type: string
        zipcode:
          type: string
        insee:
          type: string
        article:
          type: string
        name:
          type:
          - string
          - 'null'
        libelle:
          type:
          - string
          - 'null'
        department:
          type: string
          description: IRI of the department, e.g. `/departments/1`.
        cityParent:
          type:
          - object
          - 'null'
          properties:
            '@id':
              type: string
            '@type':
              type: string
            zipcode:
              type: string
            insee:
              type: string
            article:
              type: string
            name:
              type:
              - string
              - 'null'
            libelle:
              type:
              - string
              - 'null'
        originalName:
          type: string
    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.