Wahi Search API

openapi: 3.2.0
info:
  title: Listing Search API
  description: The Listing Search API enables users to find property listings that match specific criteria.
  version: 1.0.0
servers:
- url: https://api.prod.wahi.com/gpt
tags:
- name: Search
paths:
  /search:
    get:
      operationId: searchListings
      summary: Search for property listings, including flats, houses, condos, and apartments for sale, rent, or lease.
      parameters:
      - in: query
        name: first
        schema:
          type: integer
        description: Retrieve the first X items in the result set.
        required: false
        example: 10
      - in: query
        name: last
        schema:
          type: integer
        description: Retrieve the last X items in the result set.
        required: false
        example: 42
      - in: query
        name: sortBy
        description: Sort results based on a specific attribute.
        schema:
          type: string
          enum:
          - relevance
          - date
          - distance
          - listDate
          - listPrice
          - price
          - soldDate
          - updatedOn
          default: relevance
        required: false
      - in: query
        name: sortOrder
        description: Specify the sort order - ascending (asc) or descending (desc).
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        required: false
      - in: query
        name: active
        description: Filter results by active listings. By default, returns active listings only. If set to false, it returns sold listings only.
        schema:
          type: boolean
          default: true
        required: false
      - in: query
        name: coordinatesLatitude
        description: Latitude coordinate for geographic filtering.
        schema:
          type: number
          format: float
        required: false
      - in: query
        name: coordinatesLongitude
        description: Longitude coordinate for geographic filtering.
        schema:
          type: number
          format: float
        required: false
      - in: query
        name: distance
        description: Filter results by the distance from the specified coordinates. The distance unit is meters.
        schema:
          type: number
          format: float
        required: false
      - in: query
        name: maxPrice
        schema:
          type: number
          format: float
          description: Filter results by a maximum price in CAD.
        required: false
      - in: query
        name: minPrice
        schema:
          type: number
          format: float
          description: Filter results by a minimum price in CAD.
        required: false
      - in: query
        name: minBeds
        description: Filter results by a minimum number of bedrooms.
        schema:
          type: number
        required: false
      - in: query
        name: maxBeds
        description: Filter results by a maximum number of bedrooms.
        schema:
          type: number
        required: false
      - in: query
        name: minBaths
        description: Filter results by a minimum number of bathrooms.
        schema:
          type: number
        required: false
      - in: query
        name: maxBaths
        description: Filter results by a maximum number of bathrooms.
        schema:
          type: number
        required: false
      - in: query
        name: highestRatedSchools
        description: Filter listings by Fraser Institute School Rating with a score greater than or equal to 7.
        schema:
          type: boolean
        required: false
      - in: query
        name: searchString
        description: A search query string to find listings matching specific keywords or phrases.
        schema:
          type: string
        required: false
      - in: query
        name: propertyTypes
        description: Filter listings by specific property types.
        schema:
          type: array
          items:
            type: string
            enum:
            - Apartment
            - Detached
            - SemiDetached
            - Townhouse
            - Condominium
            - Land
            - Other
        required: false
      - in: query
        name: listingType
        description: Filter listings by sale or rent.
        schema:
          type: string
          enum:
          - Sale
          - Rent
        required: false
      - in: query
        name: garage
        description: Filter listings that include a garage.
        schema:
          type: boolean
        required: false
      - in: query
        name: fireplace
        description: Filter listings that include a fireplace.
        schema:
          type: boolean
        required: false
      - in: query
        name: airConditioning
        description: Filter listings that include air conditioning.
        schema:
          type: boolean
        required: false
      - in: query
        name: allowPets
        description: Filter listings that allow pets.
        schema:
          type: boolean
        required: false
      - in: query
        name: newlyAdded
        description: Filter listings that have been recently added.
        schema:
          type: boolean
        required: false
      - in: query
        name: minLotDepth
        description: Filter listings by minimum lot depth (in meters).
        schema:
          type: integer
        required: false
      - in: query
        name: maxLotDepth
        description: Filter listings by maximum lot depth (in meters).
        schema:
          type: integer
        required: false
      - in: query
        name: minLotWidth
        description: Filter listings by minimum lot width (in meters).
        schema:
          type: integer
        required: false
      - in: query
        name: maxLotWidth
        description: Filter listings by maximum lot width (in meters).
        schema:
          type: integer
        required: false
      - in: query
        name: minParkings
        description: Filter listings by minimum number of parking spaces.
        schema:
          type: integer
        required: false
      - in: query
        name: minSquareFt
        description: Filter listings by minimum square footage.
        schema:
          type: integer
        required: false
      - in: query
        name: maxSquareFt
        description: Filter listings by maximum square footage.
        schema:
          type: integer
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingsResponse'
      tags:
      - Search
components:
  schemas:
    Listing:
      type: object
      description: A single property listing with its details.
      properties:
        mlsId:
          type: string
          description: The unique identifier for the property listing in MLS board.
        listPrice:
          type: number
          format: float
          description: The listing price in CAD.
        annualTaxAmount:
          type: number
          format: float
          description: The annual tax amount in CAD.
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        geoZoneSeoPath:
          type: string
          description: The breadcrumb hierarchy path from province/state to neighborhood.
        highestRatedSchool:
          type: number
          format: float
          description: The rating of the highest-rated school nearby.
        listDate:
          type: string
          format: date-time
          description: The date the property was listed.
        soldPrice:
          type: number
          format: float
          description: The price the property was sold for, if applicable.
        soldDate:
          type: string
          format: date-time
          description: The date the property was sold, if applicable.
        address:
          $ref: '#/components/schemas/Address'
        numBedrooms:
          type: number
          format: float
          description: The total number of bedrooms in the property.
        numBedroomsFull:
          type: number
          format: float
          description: The number of full-size bedrooms in the property.
        numBedroomsPlus:
          type: number
          format: float
          description: The number of additional rooms that can be used as bedrooms.
        numBathrooms:
          type: number
          format: float
          description: The total number of bathrooms in the property.
        numBathroomsFull:
          type: number
          format: float
          description: The number of full-size bathrooms in the property.
        numBathroomsPlus:
          type: number
          format: float
          description: The number of additional rooms that can be used as bathrooms.
        numParkingSpaces:
          type: number
          format: float
          description: The number of parking spaces available at the property.
        detailsPropertyType:
          type: string
          description: The detailed property type description. More specific than the property type.
        type:
          type: string
          enum:
          - Sale
          - Rent
          description: The type of listing, either for sale or for rent.
        url:
          type: string
          description: The URL to access the listing page.
        coverImage:
          type: string
          description: The main image of the property listing.
        sqft:
          type: string
          description: The square footage of the property, displayed as a unique value (X), range (X-X), or comparative value (<X).
    ListingsResponse:
      title: ListingsResponse
      type: object
      description: The response object containing an array of property listings.
      properties:
        listings:
          title: Listings
          description: An array of property listings.
          type: array
          items:
            $ref: '#/components/schemas/Listing'
    Coordinates:
      type: object
      description: Latitude and longitude coordinates of a location.
      properties:
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
    Address:
      type: object
      description: Detailed address information for a property listing.
      properties:
        area:
          type: string
          description: The area where the property is located.
        city:
          type: string
          description: The city where the property is located.
        country:
          type: string
          description: The country where the property is located.
        district:
          type: string
          description: The district where the property is located.
        majorIntersection:
          type: string
          description: The nearest major intersection to the property.
        neighborhood:
          type: string
          description: The neighborhood where the property is located.
        streetDirection:
          type: string
          description: The direction the street is facing.
        streetName:
          type: string
          description: The name of the street where the property is located.
        streetNumber:
          type: string
          description: The street number of the property.
        streetSuffix:
          type: string
          description: The suffix for the street name (e.g., "Avenue" or "Street").
        unitNumber:
          type: string
          description: The unit number of the property, if applicable.
        zip:
          type: string
          description: The postal code of the property.
        state:
          type: string
          description: The state or province where the property is located.