stream-estate Searches API

openapi: 3.2.0
info:
  title: Stream Estate Searches 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: Searches
  description: Saved searches with webhook or email notifications.
paths:
  /searches:
    get:
      tags:
      - Searches
      summary: List searches
      description: Returns a collection of your existing searches matching given criteria.
      operationId: getSearches
      parameters:
      - name: notificationEnabled
        in: query
        description: Filter searches which have notifications enabled or not.
        schema:
          type: boolean
      - name: order[title]
        in: query
        description: Order searches by title.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: page
        in: query
        description: The collection page number.
        schema:
          type: integer
          default: 1
      - name: title
        in: query
        description: Title of the created search.
        schema:
          type: string
      responses:
        '200':
          description: Collection of searches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCollection'
        '401':
          description: Unauthorized — your API key is wrong.
    post:
      tags:
      - Searches
      summary: Create a search
      description: Creates a new search.
      operationId: createSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchInput'
      responses:
        '201':
          description: The created search.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Search'
        '400':
          description: Bad Request — your request is incorrect.
        '401':
          description: Unauthorized — your API key is wrong.
  /searches/{id}:
    get:
      tags:
      - Searches
      summary: Get a search
      description: Returns a single existing search matching the given id.
      operationId: getSearch
      parameters:
      - name: id
        in: path
        required: true
        description: UUID of the selected search
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The requested search.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Search'
        '401':
          description: Unauthorized — your API key is wrong.
        '404':
          description: Not Found — the requested resource could not be found.
    put:
      tags:
      - Searches
      summary: Update a search
      description: Updates an existing search.
      operationId: updateSearch
      parameters:
      - name: id
        in: path
        required: true
        description: UUID of the existing search
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchInput'
      responses:
        '200':
          description: The updated search.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Search'
        '400':
          description: Bad Request — your request is incorrect.
        '401':
          description: Unauthorized — your API key is wrong.
        '404':
          description: Not Found — the requested resource could not be found.
    delete:
      tags:
      - Searches
      summary: Delete a search
      description: Deletes an existing search.
      operationId: deleteSearch
      parameters:
      - name: id
        in: path
        required: true
        description: UUID of the selected search
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Search deleted.
        '401':
          description: Unauthorized — your API key is wrong.
        '404':
          description: Not Found — the requested resource could not be found.
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
    SearchCollection:
      type: object
      description: Paginated collection of searches.
      properties:
        hydra:member:
          type: array
          items:
            $ref: '#/components/schemas/Search'
        hydra:totalItems:
          type: integer
        hydra:view:
          $ref: '#/components/schemas/HydraView'
        hydra:search:
          $ref: '#/components/schemas/HydraSearch'
    HydraView:
      type: object
      properties:
        '@id':
          type: string
        '@type':
          type: string
        hydra:first:
          type: string
        hydra:last:
          type: string
        hydra:next:
          type: string
    Search:
      type: object
      description: A saved search with optional webhook / email notifications.
      properties:
        '@context':
          type: string
        '@id':
          type: string
        '@type':
          type: string
        bedroomMin:
          type:
          - integer
          - 'null'
        bedroomMax:
          type:
          - integer
          - 'null'
        budgetMax:
          type:
          - number
          - 'null'
        budgetMin:
          type:
          - number
          - 'null'
        createdAt:
          type: string
          format: date-time
        endpointRecipient:
          type:
          - string
          - 'null'
          format: uri
          description: HTTPS webhook that receives `match` payloads.
        eventEndpoint:
          type:
          - string
          - 'null'
          format: uri
          description: HTTPS webhook that receives advert `event` payloads.
        excludedCities:
          type: array
          items:
            type: object
            additionalProperties: true
        excludedSiteCategories:
          type: array
          items:
            type: object
            additionalProperties: true
        expressions:
          description: Full text matching rules applied to the title or description.
        furnished:
          type:
          - boolean
          - 'null'
        hidePropertyContact:
          type: boolean
        includedCities:
          type: array
          items:
            type: object
            additionalProperties: true
        includedDepartments:
          type: array
          items:
            type: object
            additionalProperties: true
        includedSiteCategories:
          type: array
          items:
            type: object
            additionalProperties: true
        landSurfaceMax:
          type:
          - number
          - 'null'
        landSurfaceMin:
          type:
          - number
          - 'null'
        lastAlertAt:
          type:
          - string
          - 'null'
          format: date-time
        lat:
          type:
          - number
          - 'null'
        lon:
          type:
          - number
          - 'null'
        notificationEnabled:
          type: boolean
        notificationRecipient:
          type:
          - string
          - 'null'
        pricePerMeterMax:
          type:
          - number
          - 'null'
        pricePerMeterMin:
          type:
          - number
          - 'null'
        propertyTypes:
          type: array
          description: Apartment `0`, House `1`, Building `2`, Parking `3`, Office `4`, Land `5`, Shop `6`.
          items:
            type: integer
            enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
        publisherTypes:
          type: array
          description: Individual `0`, Professional `1`.
          items:
            type: integer
            enum:
            - 0
            - 1
        radius:
          type:
          - number
          - 'null'
          description: Distance in kilometers around `lat`/`lon`.
        roomMin:
          type:
          - integer
          - 'null'
        roomMax:
          type:
          - integer
          - 'null'
        subscribedEvents:
          type: array
          items:
            type: string
            enum:
            - ad.update.price
            - ad.update.surface
            - ad.update.pictures
            - ad.update.expired
            - property.ad.create
            - property.ad.update
        surfaceMax:
          type:
          - number
          - 'null'
        surfaceMin:
          type:
          - number
          - 'null'
        title:
          type: string
        token:
          type: string
        transactionType:
          type: integer
          description: Sell `0`, Rent `1`.
          enum:
          - 0
          - 1
        updatedAt:
          type: string
          format: date-time
        user:
          type: string
        withCoherentPrice:
          type: boolean
        withVirtualTour:
          type:
          - boolean
          - 'null'
    SearchInput:
      type: object
      required:
      - propertyTypes
      - title
      - transactionType
      properties:
        bedroomMin:
          type: integer
          description: Minimum number of bedrooms in the property.
        bedroomMax:
          type: integer
          description: Maximum number of bedrooms in the property.
        budgetMax:
          type: number
          description: Maximum budget for the property.
        budgetMin:
          type: number
          description: Minimum budget for the property.
        endpointRecipient:
          type: string
          format: uri
          description: HTTPS webhook that receives `match` payloads whenever a property satisfies the search. Requires `notificationEnabled=true`.
        eventEndpoint:
          type: string
          format: uri
          description: HTTPS webhook that receives advert `event` payloads (price changes, expirations, etc.). Requires `notificationEnabled=true` and at least one entry in `subscribedEvents`.
        excludedCities:
          type: array
          items:
            type: string
          description: Cities to be excluded.
        excludedSites:
          type: array
          items:
            type: string
          description: Source sites to be excluded.
        excludedSiteCategories:
          type: array
          items:
            type: string
          description: Site categories to be excluded.
        expressions:
          type: array
          description: Full text matching including/excluding words & phrases in the title or the description of the property.
          items: {}
        furnished:
          type: boolean
          description: Whether the property is furnished or not.
        geoAccuracy:
          type: number
          description: Geocoding confidence level. Use `1` to keep only house-number level matches and `2` to include neighborhood-level approximations. Leave empty to allow both.
        geoShapes:
          type: array
          items: {}
          description: Filters properties within specified geographic areas (arrays of `[lon, lat]` points forming polygons).
        hidePropertyContact:
          type: boolean
          description: Whether to hide property contact information or not.
        includedCities:
          type: array
          items:
            type: string
          description: Included cities. Use the location autocomplete endpoint to get the desired city IRIs.
        includedDepartments:
          type: array
          items:
            type: string
          description: Included departments. Use the location autocomplete endpoint to get the desired department IRIs.
        includedSiteCategories:
          type: array
          items:
            type: string
          description: Included site categories.
        includedSites:
          type: array
          items:
            type: string
          description: Source sites to be included.
        includedZipcodes:
          type: array
          items:
            type: string
          description: Included zipcodes.
        includedZipcodesInsee:
          type: array
          items:
            type: string
          description: Included INSEE codes (used to infer the cities associated with the search).
        landSurfaceMax:
          type: number
          description: Maximum land surface.
        landSurfaceMin:
          type: number
          description: Minimum land surface.
        lat:
          type: number
          description: Latitude of the center point used for radial filtering. Provide together with `lon`.
        lon:
          type: number
          description: Longitude of the center point used for radial filtering. Provide together with `lat`.
        notificationEnabled:
          type: boolean
          default: false
          description: Enables delivery of matches and events either by webhook (`endpointRecipient`, `eventEndpoint`) or by email (`notificationRecipient`).
        notificationRecipient:
          type: string
          description: Email address that receives alert summaries when `notificationEnabled=true`.
        pricePerMeterMax:
          type: number
          description: Maximum price per meter.
        pricePerMeterMin:
          type: number
          description: Minimum price per meter.
        propertyTypes:
          type: array
          description: Type of property. Apartment `0`, House `1`, Building `2`, Parking `3`, Office `4`, Land `5`, Shop `6`.
          items:
            type: integer
            enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
        publisherTypes:
          type: array
          description: Type of publisher. Individual `0`, Professional `1`.
          items:
            type: integer
            enum:
            - 0
            - 1
        radius:
          type: number
          description: Distance in kilometers around the provided `lat`/`lon`.
        roomMin:
          type: integer
          description: Minimum number of rooms.
        roomMax:
          type: integer
          description: Maximum number of rooms.
        subscribedEvents:
          type: array
          description: Event codes you want to receive on the `eventEndpoint`.
          items:
            type: string
            enum:
            - ad.update.price
            - ad.update.surface
            - ad.update.pictures
            - ad.update.expired
            - property.ad.create
            - property.ad.update
        surfaceMax:
          type: number
          description: Maximum property surface area.
        surfaceMin:
          type: number
          description: Minimum property surface area.
        title:
          type: string
          description: Title of the created search.
        transactionType:
          type: integer
          description: Type of transaction. Sell `0`, Rent `1`.
          enum:
          - 0
          - 1
        withCoherentPrice:
          type:
          - boolean
          - 'null'
          description: Price coherence filter. `true` returns adverts whose price passes our coherence checks; `false` returns adverts flagged as incoherent — both also include adverts whose price has not been assessed. Set to `null` (or send an empty value) to disable filtering. If omitted, defaults to `true`.
        withVirtualTour:
          type: boolean
          description: Whether the property includes a virtual tour.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key created in your Stream Estate settings.