Rooms

In the context of the Housemates API, a "Room" represents a type of living space within a property (e.g. Studio), available for students to book. Each room has various attributes like room name, size, occupant capacity, and amenities.

Within each room, there are "Booking Periods" that denote the time frames during which a student can book and occupy the room. These periods typically align with academic terms or semesters, but flexibility may be offered depending on the accommodation provider's policies.

Together, the Room and Booking Periods form a comprehensive view of the accommodation options available to students. The Room provides information about the living space itself, while the Booking Periods provide information about the availability and bookability of the room. Both are essential components of the accommodation booking process, enabling students to find and book suitable accommodation efficiently and effectively..

The Room model

The "Room" model within the Housemates system serves as a comprehensive directory of each room across all properties. It's designed to offer the essential information, aiding students in their decision-making process when choosing a room. Let's delve into the various attributes encapsulated within this Room model.

Attributes

Name
id
Type
string
Description
This is the unique identifier that is used to identify the room in our system. It is also used to retrieve detailed information about the property.
Name
operator_id
Type
string
Description
Unique identifier used to identify the accommodation provider in our system.
Name
name
Type
string
Description
The name of the room. e.g. "Standard Studio".
Name
max_rooms_left
Type
integer
Description
The number of units left for this room in the property.
Name
is_available
Type
boolean
Description
Determines if the room is available to book in the property.
Name
price
Type
string
Description
Determines rental price per person per week for this room. We recommend showing this to your users.
Name
total_price
Type
string
Description
Determines the total price of a property, this will differ from the price for group exclusive room types.
Name
is_estimated_price
Type
boolean
Description
If the rooms are sold out then this attribute would be set to true as we wouldn't have the exact rental price for the room.
Name
cancellation
Type
object
Description
The cancellation policies for the room where student can be refunded
Name
price_range
Type
object
Description
The price range of this room in the property per week
Name
coordinates
Type
object
Description
The coordinates of the room. i.e. latitude and longitude.
Name
address
Type
object
Description
The address of the room.
Name
summary
Type
string
Description
Summary of the room.
Name
description
Type
text
Description
Text description of the room.
Name
rich_description
Type
text
Description
HTML i.e. rich description of the room.
Name
amenities
Type
object
Description
Amenities available at the room. Amenities are grouped into general category.It contains a list of amenities that are available at the property. The status of each amenity indicates if the amenity is available. The label of each amenity can be used to filter properties by. A full list of room amenities can be retrieved from the Amenities endpoint.
Name
currency
Type
string
Description
The currency set for the room. e.g. GBP. As we work with accommodation providers from different countries, this attribute is used to determine the currency in which the prices are displayed.
Name
images
Type
array
Description
A list of images of for the room.
Name
booking_periods
Type
array
Description
A list of images of for the room.
Name
universities
Type
array
Description
A list of nearby universities and their distances from the room.
Name
group_exclusive
Type
object
Description
Determines if the room type must be booked by a group or an individual. You should clearly inform users of which properties are required to be booked as a group.
Name
_links
Type
array
Description
A list of links to related resources.

Property model

{
    "id":"01H14V1ECE5814YBJE2KQPVKNP",
    "operator_id":"03d7438a-309f-446e-96be-7b123180e155",
    "name":"Standard Ensuite",
    "max_rooms_left":121,
    "is_available":true,
    "price":"£37.50",
    "total_price":"£150",
    "is_estimated_price":false,
    "cancellation":{
        "visa_cancellation":false,
        "uni_place_cancellation":false
    },
    "price_range":{
        "min":"£150",
        "max":"£150"
    },
    "address":{
        "city":"1",
        "region":"",
        "country":"United Kingdom",
        "postcode":"CA5 6NA",
        "firstLine":"1",
        "secondLine":"1"
    },
    "summary":"Example summary",
    "description":"This is example description",
    "rich_description":"<p>This is example description</p>",
    "amenities":{
        "general":[
            {
                "name":"All Bills Included",
                "label":"AIB",
                "status":false
            },
            {
                "name":"Air Conditioning",
                "label":"AIR",
                "status":false
            },
            // ...
        ]
    },
    "coordinates":{
        "lat":"54.8780960",
        "long":"-3.0478150"
    },
    "currency":"GBP",
    "images":[
        {
            "large":"https://ik.imagekit.io/rk1sb42mtmr/tr:h-auto,w-1936,f-jpg,q-70/cadc73b0-295e-43d9-acd4-060f3d58a605/media/7vD3k63xcEK9wW5uYDwv40eVFmX5iTzFzmb4yHL1.jpg",
            "small":"https://ik.imagekit.io/rk1sb42mtmr/tr:h-auto,w-560,f-jpg,q-70/cadc73b0-295e-43d9-acd4-060f3d58a605/media/7vD3k63xcEK9wW5uYDwv40eVFmX5iTzFzmb4yHL1.jpg",
            "medium":"https://ik.imagekit.io/rk1sb42mtmr/tr:h-auto,w-1120,f-jpg,q-70/cadc73b0-295e-43d9-acd4-060f3d58a605/media/7vD3k63xcEK9wW5uYDwv40eVFmX5iTzFzmb4yHL1.jpg",
            "small_plus":"https://ik.imagekit.io/rk1sb42mtmr/tr:h-auto,w-750,f-jpg,q-70/cadc73b0-295e-43d9-acd4-060f3d58a605/media/7vD3k63xcEK9wW5uYDwv40eVFmX5iTzFzmb4yHL1.jpg"
        },
        // ...
    ],
    "booking_periods":[
        {
            "id":"01H1MVWTAHX06YDFZ7DJMBTY0K",
            "start_date":"09-09-2023",
            "end_date":"06-01-2024",
            "holding_deposit": "£100",
            "price_per_week": "£150",
            "maximum_bookings": 121
        },
        // ...
    ],
    "property":{
        "id":"01H14V1E78QN1MHQWX1KZB964N",
        "name":"City Village",
        "slug":"city-village"
    },
     "universities": [
        {
           "name": "The University of Manchester",
           "distance": 3.77,
           "walk": "45 mins",
           "drive": "7 mins",
           "metric_unit": "miles",
           "coordinates": {
               "lat": "53.46684980",
               "long": "-2.23388370"
           }
        },
       // ... more universities
    ],
    "group_exclusive": {
        "status": true,
        "size": 4
    },
    "_links":[
        {
            "rel":"self",
            "type":"GET",
            "href":"https://api.housemates.io:8060/api/rooms/01H14V1ECE5814YBJE2KQPVKNP"
        },
        {
            "rel":"property",
            "type":"GET",
            "href":"https://api.housemates.io:8060/api/properties/01H14V1E78QN1MHQWX1KZB964N"
        },
        {
            "rel":"checkout_start",
            "type":"POST",
            "href":"https://api.housemates.io:8060/api/rooms/01H14V1ECE5814YBJE2KQPVKNP/checkout/start"
        },
        {
            "rel":"checkout_finish",
            "type":"POST",
            "href":"https://api.housemates.io:8060/api/rooms/01H14V1ECE5814YBJE2KQPVKNP/checkout"
        },
        {
            "rel":"room_amenity_filters",
            "type":"GET",
            "href":"https://api.housemates.io:8060/api/amenities?type=room"
        }
    ]
}

GET/api/rooms

List all rooms

This endpoint provides you with access to a paginated listing of all available room types, paired with their associated booking periods and the maximum count of bookings allowed within each period. The response is paginated, with a default limit of 10 rooms per page. You can change the limit by using the per_page query parameter.

Required attributes

Name
X-API-PARTNER-ID
Type
string
Description
Your API partner ID provided by Housemates. It should be provided in the header.

Optional attributes

Name
per_page
Type
integer
Description
Limit the number of rooms returned.
Name
page
Type
integer
Description
The page number to be returned. e.g. page=2. By default, the first page is returned. It is usually used for pagination.

Filters

You can filter the properties by using the following optional query parameters:

Name
filter[move_in_date]
Type
string
Description
Filter room by move in date. e.g. filter[move_in_date]=01-2023. The date format is MM-YYYY.
Name
filter[geo_fence]
Type
string
Description
Filter properties by certain coordinates within provided radius. More info about geo fence can be found at here. If no radius is set, it will default to 10 miles. You can bypass the radius by setting it as -1, e.g.
filter[geo_fence]=[lat=53.47948920,long=-2.24511480,radius=-1]
Name
filter[amenities]
Type
string
Description
Filter rooms by amenities. e.g.
filter[amenities]=[GAR=true,BRD=false,24HS=false]
Name
filter[price_range]
Type
string
Description
Filter rooms by price range. e.g.
filter[price_range]=[min=100,max=400]
Name
filter[group_exclusive]
Type
boolean
Description
Filter by group exclusive rooms.
filter[group_exclusive]=false
Name
filter[cancellation_policies]
Type
string
Description
Filter by cancellation policies. e.g.
filter[cancellation_policies]=[visa=false,covid=true,uni_place=true]
Name
filter[exclude_unavailable]
Type
boolean
Description
Exclude unavailable rooms from the API response.
filter[exclude_unavailable]=true

Sort

The sort query parameter is used to determine which property the results collection will be ordered. Sorting is ascending by default and can be reversed by adding a hypen (-) to the start of the property name. Additional parameters can be added by separating with a semi colon.

Example: sort=-price,distance.

Name
price
Type
string
Description
Name
max_rooms_left
Type
string
Description
Name
is_available
Type
string
Description
Name
is_estimated_price
Type
string
Description
Name
distance
Type
string
Description
You must apply the filter[geo_fence] filter in order to sort by distance.

Request

GET

/api/rooms


curl --request GET \
--url "https://api.housemates.io/api/rooms" \
--header 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'

# Filter by move in date and geo fence

curl --globoff --request GET \
--url "https://api.housemates.io/api/rooms?filter[move_in_date]=09-2023&filter[geo_fence]=[lat=53.47948920,long=-2.24511480]" \
--header 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Response

{
  "success":true,
  "code":0,
  "locale":"en",
  "message":"OK",
  "data":{
    "items":[
      {
        "id":"01H14V1E98A2A046WFDJZTEJER",
        "operator_id":"03d7438a-309f-446e-96be-7b123180e155",
        "name":"Standard Ensuite",
        "max_rooms_left":2,
        "is_available":true,
        "price":"£98.04",
        "is_estimated_price":false,
        "cancellation":{
          "visa_cancellation":false,
          "uni_place_cancellation":false
        },
        "price_range":{
          "min":"£98.04",
          "max":"£98.04"
        },
        "address":{
          "city":"Manchester",
          "region":"",
          "country":"United Kingdom",
          "postcode":"M35 0PS",
          "firstLine":"1 Manchester Road",
          "secondLine":""
        }
        // ... please see the room model for more details
      }
      // ... more rooms
    ],
    "meta":{
      "total":8,
      "count":8,
      "per_page":10,
      "current_page":1,
      "total_pages":1,
      "path":"https://api.housemates.io/rooms",
      "links":[
        {
          "url":null,
          "label":"&laquo; Previous",
          "active":false
        },
        {
          "url":"https://api.housemates.io/rooms?page=1",
          "label":"1",
          "active":true
        },
        {
          "url":null,
          "label":"Next &raquo;",
          "active":false
        }
      ]
    },
    "links":{
      "first":"https://api.housemates.io/rooms?page=1",
      "last":"https://api.housemates.io/rooms?page=1",
      "next":null,
      "prev":null
    }
  }
}

GET/api/rooms/:id

Retrieve a room

This endpoint allows you to retrieve a room by providing their unique id. Refer to the list at the top of this page to see which properties are included. The output not only includes room specific attributes but also provides associated property information, such as id, name, and slug. Additionally, it offers details on nearby universities, along with their respective distances from the room.

Required attributes

Name
X-API-PARTNER-ID
Type
string
Description
Your API partner ID provided by Housemates. It should be provided in the header.
Name
room_id
Type
string
Description
Unique identifier for the room to be provided in the path.

Request

GET

/api/rooms/:id

curl --location 'https://api.housemates.io/api/rooms/{room_id}' \
--header 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Response

{
  "success":true,
  "code":0,
  "locale":"en",
  "message":"OK",
  "data":{
    "item":{
      "id":"01H0N7WS7ZN1DGEJFF2C14K8NJ",
      "operator_id":"9258a234-f90b-4871-b434-247087fec215",
      "name":"Standard ",
      "max_rooms_left":96,
      "is_available":true,
      // ... please see the room model for more details
      "property":{
        "id":"01H0N7WRYG684ZPHASFNSAX6S9",
        "name":"Hockley House",
        "slug":"hockley-house"
      },
      "universities":[
        {
          "name":"The University of Manchester",
          "distance":3.77,
          "walk":"45 mins",
          "drive":"7 mins",
          "metric_unit":"miles",
          "coordinates":{
            "lat":"53.46684980",
            "long":"-2.23388370"
          }
        }
        // ... more universities
      ]
    }
  }
}

GET/api/rooms/:id/booking-periods

Retrieve booking periods

This endpoint allows you to retrieve booking periods for a room by providing their unique id.

Required attributes

Name
X-API-PARTNER-ID
Type
string
Description
Your API partner ID provided by Housemates. It should be provided in the header.
Name
room_id
Type
string
Description
Unique identifier for the room to be provided in the path.

Request

GET

/api/rooms/:id/booking-periods

curl --location 'https://api.housemates.io/api/rooms/{room_id}/booking-periods' \
--header 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Response

{
  "success":true,
  "code":0,
  "locale":"en",
  "message":"OK",
  "data":{
    "items":[
      {
        "id":"01H1MVWTANTVPESEXCS7HCNF00",
        "start_date":"09-09-2023",
        "end_date":"31-08-2024",
        "holding_deposit":"£10",
        "price_per_week":"£98.04",
        "maximum_bookings":2
      }
      // ... more booking periods
    ]
  }
}