Casafari API and MCP Platform API Valuation API

openapi: 3.2.0
info:
  title: Casafari API Valuation API
  description: 'The Casafari API provides clients with methods for manipulating alerts feeds, accounts, and consulting a reference

    of available locations, features and conditions.


    # Authentication methods


    -->'
  version: 0.1.0
servers:
- url: https://api.casafari.com
tags:
- name: api---valuation
  x-displayName: Valuation
paths:
  /api/v1/valuation/comparables-prices:
    post:
      tags:
      - api---valuation
      summary: Search estimated prices (v1)
      description: Returns estimated prices by the given parameters.
      operationId: api__post__v1__valuation__comparables-prices
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiComparablesPricesRequestV1'
            examples:
              '0':
                value:
                  comparables_count: 20
                  location_boundary:
                    circle:
                      distance: 3.5
                      target_point:
                        coordinates:
                          latitude: 38.74
                          longitude: -9.17
                  sold_or_rented_after: '2020-06-01'
                  days_on_market_from: 10
                  days_on_market_to: 1000
                  operation: sale
                  comparables_types:
                  - apartment
                  bedrooms: 2
                  construction_year: 2010
                  total_area: 125
                  condition: used
                  floors:
                  - middle
                  - top
                  floor_number:
                  - 3
                  - 5
                  views:
                  - city
                  - landscape
                  directions:
                  - west
                  - north
                  characteristics:
                    must_have:
                    - balcony
                    - elevator
                    nice_to_have:
                    - garage
                    - parking
                    - storage
                  energy_ratings:
                  - A
                  - B
                  - C
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiComparablesPricesV1'
              examples:
                '0':
                  value:
                    statistics:
                      average_price: 767950
                      average_price_per_sqm: 6376
                      average_time_on_the_market: 169
                      average_listings_per_property: 6.2
                      sold_or_rented_in_last_six_months: 453
                    estimated_prices:
                      fast_sell_price: 741210
                      fair_market_price: 797000
                      out_of_market_price: 852790
                      fast_sell_price_per_sqm: 5929.68
                      fair_market_price_per_sqm: 6376.0
                      out_of_market_price_per_sqm: 6822.32
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                properties:
                  detail:
                    type: string
                    description: Description of the error encountered.
                    example: Authentication credentials were not provided.
                type: object
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                properties:
                  detail:
                    type: string
                    description: Description of the error encountered.
                    example: You do not have permission to perform this action.
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: object
                    description: Description of the errors encountered.
                type: object
      security:
      - HTTPBearer: []
      - OAuth2ClientCredentials: []
components:
  schemas:
    ApiComparablesPricesRequestV1:
      properties:
        comparables_count:
          type: integer
          maximum: 50.0
          minimum: 1.0
          description: Maximum number of comparable properties in results.
        target_point:
          properties:
            coordinates:
              properties:
                latitude:
                  type: number
                  maximum: 90.0
                  minimum: -90.0
                  description: Latitude.
                longitude:
                  type: number
                  maximum: 180.0
                  minimum: -180.0
                  description: Longitude.
              type: object
              required:
              - latitude
              - longitude
              description: Target point coordinates to search around.
            address:
              type: string
              description: Address of the property to define the point to search around.
            cadastral_reference:
              properties:
                country_code:
                  type: string
                  enum:
                  - ES
                  description: Country code following the ISO 3166-1 alpha-2 rules.
                  writeOnly: true
                cadastral_reference:
                  type: string
                  description: Cadastral reference of the estate.
                  writeOnly: true
                province:
                  type: string
                  description: Name of the estate's province.
                  writeOnly: true
                municipality:
                  type: string
                  description: Name of the estate's municipality.
                  writeOnly: true
              type: object
              required:
              - country_code
              - cadastral_reference
              description: Cadastral reference of the property to define the point to search around. <br/>For now available only for Spain.
          type: object
          description: Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided.<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `location_boundary.circle` field instead.</strong>
        distance:
          type: number
          maximum: 50.0
          minimum: 0.05
          description: Maximum distance in kilometers from the requested `target_point` to comparable properties.<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `location_boundary.circle` field instead.</strong>
          default: 5
        location_boundary:
          properties:
            polygon:
              items:
                properties:
                  latitude:
                    type: number
                    maximum: 90.0
                    minimum: -90.0
                    description: Latitude.
                  longitude:
                    type: number
                    maximum: 180.0
                    minimum: -180.0
                    description: Longitude.
                type: object
                required:
                - latitude
                - longitude
              type: array
              minItems: 4
              description: 'Closed polygon of geo-points to search within. First and last points must match. '
            circle:
              properties:
                distance:
                  type: number
                  maximum: 50.0
                  minimum: 0.05
                  description: Maximum distance in kilometers from the requested `target_point` to the properties.
                  default: 5
                target_point:
                  properties:
                    coordinates:
                      properties:
                        latitude:
                          type: number
                          maximum: 90.0
                          minimum: -90.0
                          description: Latitude.
                        longitude:
                          type: number
                          maximum: 180.0
                          minimum: -180.0
                          description: Longitude.
                      type: object
                      required:
                      - latitude
                      - longitude
                      description: Target point coordinates to search around.
                    address:
                      type: string
                      description: Address of the property to define the point to search around.
                    cadastral_reference:
                      properties:
                        country_code:
                          type: string
                          enum:
                          - ES
                          description: Country code following the ISO 3166-1 alpha-2 rules.
                          writeOnly: true
                        cadastral_reference:
                          type: string
                          description: Cadastral reference of the estate.
                          writeOnly: true
                        province:
                          type: string
                          description: Name of the estate's province.
                          writeOnly: true
                        municipality:
                          type: string
                          description: Name of the estate's municipality.
                          writeOnly: true
                      type: object
                      required:
                      - country_code
                      - cadastral_reference
                      description: Cadastral reference of the property to define the point to search around. <br/>For now available only for Spain.
                  type: object
                  description: Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided.
              type: object
              required:
              - target_point
              description: Circle boundary to search within.
          type: object
          description: Location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided.
        sold_or_rented_after:
          type: string
          format: date
          description: 'Properties sold/rented since this date (in the format `YYYY-MM-DD`) will be considered as possible comparables. Default value: 9 months ago, counting from today. If `null` is passed, only active properties will be considered.'
          nullable: true
        operation:
          type: string
          enum:
          - sale
          - rent
          description: Operation type.
        comparables_type:
          type: string
          enum:
          - apartment
          - studio
          - duplex
          - penthouse
          - dachgeschosswohnung
          - etagenwohnung
          - erdgeschosswohnung
          - country_house
          - house
          - palace
          - townhouse
          - villa
          - country_estate
          - chalet
          - bungalow
          - family_house
          - reihenhaus
          - reihenendhaus
          - reihenmittelhaus
          - einfamilienhaus
          - zweifamilienhaus
          - landwirtschaftliche_betriebe
          - retail
          - office
          - industrial
          - warehouse
          - hotel
          - other_commercial
          - restaurant
          - werkstatt
          - plot
          - urban_plot
          - rural_plot
          - room
          - other
          - garage
          - parking
          - apartment_building
          - office_building
          - mix_use_building
          description: Comparables property type, as returned by the [GET /api/v1/references/types](/#operation/api__get__v1__references__types) endpoint.<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `comparables_types` field instead.</strong>
        comparables_types:
          items:
            type: string
            enum:
            - apartment
            - studio
            - duplex
            - penthouse
            - dachgeschosswohnung
            - etagenwohnung
            - erdgeschosswohnung
            - country_house
            - house
            - palace
            - townhouse
            - villa
            - country_estate
            - chalet
            - bungalow
            - family_house
            - reihenhaus
            - reihenendhaus
            - reihenmittelhaus
            - einfamilienhaus
            - zweifamilienhaus
            - landwirtschaftliche_betriebe
            - retail
            - office
            - industrial
            - warehouse
            - hotel
            - other_commercial
            - restaurant
            - werkstatt
            - plot
            - urban_plot
            - rural_plot
            - room
            - other
            - garage
            - parking
            - apartment_building
            - office_building
            - mix_use_building
          type: array
          description: <br>Country availability per type is available at the [GET /api/v1/references/types](/#operation/api__get__v1__references__types) endpoint.<br><br>Property types by type groups:<br/><strong>apartment:</strong> erdgeschosswohnung, penthouse, duplex, etagenwohnung, apartment, dachgeschosswohnung, studio<br/><strong>house:</strong> zweifamilienhaus, palace, reihenmittelhaus, landwirtschaftliche_betriebe, chalet, house, reihenendhaus, townhouse, einfamilienhaus, bungalow, villa, reihenhaus, family_house (<span style="color:red">DEPRECATED</span>), country_estate, country_house<br/><strong>room:</strong> room<br/><strong>building:</strong> office_building, mix_use_building, apartment_building<br/><strong>investment:</strong> other_commercial, warehouse, industrial, office, hotel, restaurant, werkstatt, retail<br/><strong>plot:</strong> urban_plot, rural_plot, plot (<span style="color:red">DEPRECATED</span>)<br/><strong>other:</strong> other, garage, parking<br/><br/><i><span style="color:red">Note that you can select multiple types only from one property type group.</span></i>
        min_price:
          type: integer
          maximum: 2147483647.0
          minimum: 0.0
          description: The minimum price filter for comparables result.
          default: 0
        max_price:
          type: integer
          maximum: 2147483647.0
          minimum: 1.0
          description: The maximum price filter for comparables result.
        condition:
          type: string
          enum:
          - used
          - ruin
          - very-good
          - new
          - other
          description: Property condition, as returned by the [GET /api/v1/references/conditions](/#operation/api__get__v1__references__conditions) endpoint.
        bedrooms:
          type: integer
          maximum: 15000.0
          minimum: 0.0
          description: Number of bedrooms (cannot be used together with `rooms`).
        rooms:
          type: integer
          maximum: 15000.0
          minimum: 0.0
          description: Number of rooms (cannot be used together with `bedrooms`).
        bathrooms:
          type: integer
          maximum: 15000.0
          minimum: 1.0
          description: Number of bathrooms.
        construction_year:
          type: integer
          maximum: 3000.0
          minimum: 1.0
          description: Desired construction year.
        total_area:
          type: integer
          maximum: 10000000.0
          minimum: 5.0
          description: Desired total area, square meters. This field is required for `hotel`, `industrial`, `office`, `other_commercial`, `restaurant`, `retail`, `warehouse`, `werkstatt` property types if `target_point.cadastral_reference` is not provided.
        plot_area:
          type: integer
          maximum: 10000000.0
          minimum: 20.0
          description: Desired plot area, square meters. This field is required for `rural_plot` and `urban_plot` property types if `target_point.cadastral_reference` is not provided.
        floors:
          items:
            type: string
            enum:
            - no_floor
            - ground
            - middle
            - top
          type: array
          description: List of floor types.
        floor_number:
          items:
            type: integer
            maximum: 250.0
            minimum: -250.0
          type: array
          description: Desired list of floor numbers. Negative values indicate underground floors (e.g. basements).<br>Minimum value is -250.<br>Maximum value is 250.
        orientation:
          type: string
          enum:
          - exterior
          - interior
          description: Property view orientation.
        views:
          items:
            type: string
            enum:
            - water
            - landscape
            - city
            - golf
            - park
          type: array
          description: List of views from the property.
        directions:
          items:
            type: string
            enum:
            - north
            - south
            - east
            - west
          type: array
          description: List of cardinal directions the property faces.
        characteristics:
          properties:
            must_have:
              items:
                type: string
                enum:
                - balcony
                - elevator
                - no_elevator
                - garage
                - garden
                - parking
                - storage
                - swimming_pool
                - terrace
                - rental_license
                - furniture
                - rented_out
                - life_annuity
              type: array
              description: Include only properties that have all these characteristics.
            nice_to_have:
              items:
                type: string
                enum:
                - balcony
                - elevator
                - no_elevator
                - garage
                - garden
                - parking
                - storage
                - swimming_pool
                - terrace
                - rental_license
                - furniture
                - rented_out
                - life_annuity
              type: array
              description: Include properties that have any of these characteristics.
            exclude:
              items:
                type: string
                enum:
                - balcony
                - elevator
                - no_elevator
                - garage
                - garden
                - parking
                - storage
                - swimming_pool
                - terrace
                - rental_license
                - furniture
                - rented_out
                - life_annuity
              type: array
              description: Exclude properties that contain any of these characteristics.
          type: object
          description: Property characteristics.
        energy_certificate:
          type: string
          enum:
          - Unknown
          - A+
          - A
          - B
          - C
          - D
          - E
          - F
          - G
          - H
          description: Energy certificate. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `energy_ratings` field instead.</strong>
        energy_certificates:
          items:
            type: string
            enum:
            - Unknown
            - A+
            - A
            - B
            - C
            - D
            - E
            - F
            - G
            - H
          type: array
          description: List of energy certificates. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `energy_ratings` field instead.</strong>
        energy_ratings:
          items:
            type: string
            enum:
            - Unknown
            - A+
            - A
            - B
            - C
            - D
            - E
            - F
            - G
            - H
          type: array
          description: List of energy ratings.
        days_on_market_from:
          type: integer
          maximum: 10000.0
          minimum: 1.0
          description: Minimum days on market value.
        days_on_market_to:
          type: integer
          maximum: 10000.0
          minimum: 1.0
          description: Maximum days on market value.
        with_agencies:
          items:
            type: string
          type: array
          description: Return properties from specified agencies, companies or sources. To find allowed agency names use the [GET /api/v1/references/agencies](/#operation/api__get__v1__references__agencies) endpoint.
        without_agencies:
          items:
            type: string
          type: array
          description: Exclude properties from specified agencies, companies or sources. To find allowed agency names use the [GET /api/v1/references/agencies](/#operation/api__get__v1__references__agencies) endpoint.
        exclude_outliers:
          type: boolean
          description: Exclude properties that are significantly underpriced or overpriced compared to similar properties.
          default: true
      type: object
      required:
      - comparables_count
      - location_boundary
      - operation
      - comparables_types
    ApiComparablesPricesV1:
      properties:
        statistics:
          properties:
            average_price:
              type: integer
              description: Average price.
            average_price_per_sqm:
              type: number
              description: Average price per square meter.
            average_time_on_the_market:
              type: integer
              description: Average number of days on the market.
            average_listings_per_property:
              type: number
              description: Average number of listings per property.
            sold_or_rented_in_last_six_months:
              type: integer
              description: Number of properties that were sold or rented during the last 6 months in the requested location.
          type: object
          required:
          - average_price
          - average_price_per_sqm
          - average_time_on_the_market
          - average_listings_per_property
          - sold_or_rented_in_last_six_months
          description: Statistics information for the found comparables (for `operation` defined in the request).
          nullable: true
        estimated_prices:
          properties:
            fast_sell_price:
              type: integer
              description: Fast sell price.
            fair_market_price:
              type: integer
              description: Fair market price.
            out_of_market_price:
              type: integer
              description: Out of market price.
            fast_sell_price_per_sqm:
              type: number
              description: Fast sell price per square meter.
            fair_market_price_per_sqm:
              type: number
              description: Fair market price per square meter.
            out_of_market_price_per_sqm:
              type: number
              description: Out of market price per square meter.
          type: object
          required:
          - fast_sell_price
          - fair_market_price
          - out_of_market_price
          - fast_sell_price_per_sqm
          - fair_market_price_per_sqm
          - out_of_market_price_per_sqm
          description: Estimated prices calculated based on the found comparables (for `operation` defined in the request).
      type: object
      required:
      - statistics
      - estimated_prices
  securitySchemes:
    HTTPBearer:
      type: http
      description: '

        Sign in with your account: `POST /login` with your email and password returns an `access_token` and a

        `refresh_token`. Send the access token as `Authorization: Bearer <access_token>`. When it expires, call

        `GET /refresh-token` with `Authorization: Bearer <refresh_token>` for a new access token.

        '
      scheme: bearer
      bearerFormat: JWT
    OAuth2ClientCredentials:
      type: oauth2
      description: "**Recommended.** Create a client in Settings → API Clients and save its ID and secret. The secret is displayed only once, and the client can be used only in the environment where it was created.\n\nExchange the client ID and secret for an access token using HTTP Basic authentication:\n\n```bash\ncurl -X POST 'https://api.casafari.com/oauth/token' \\\n  -u 'CLIENT_ID:CLIENT_SECRET' \\\n  -d 'grant_type=client_credentials' \\\n  -d 'scope=api'\n```\n\nThe access token is valid for 30 minutes. No refresh token is issued, so you must request a new access token when the current one expires.\n\nInclude the access token in API requests using the following header:\n\n```\nAuthorization: Bearer <token>\n```"
      flows:
        clientCredentials:
          scopes:
            api: Access to the CASAFARI REST API.
          tokenUrl: https://api.casafari.com/oauth/token
x-tagGroups:
- name: User Management
  tags:
  - user-management---authentication
- name: API
  tags:
  - api---valuation
  - api---alerts
  - api---comparables
  - api---references
  - api---properties
- name: Market Analytics API
  tags:
  - market-analytics-api---time series
  - market-analytics-api---distributions
  - market-analytics-api---analysis
- name: Alerts API
  tags:
  - alerts-api---webhooks
  - alerts-api---feeds