Locations

In the context of the Housemates API, a "Location" can refer to either a city or a university. This is an essential model within our service, as it provides the geographical context for our properties and allows users to find accommodations in areas that are most relevant to them.

City

A "City" is a fundamental entity within our Location model. It represents the urban area in which properties are located. Each city can contain multiple properties and universities, making it an essential factor for users when searching for accommodations. The City attribute within a property indicates the city in which the property is situated.

University

A "University" is another critical entity within our Location model. This represents the academic institution around which student accommodations are usually centered. Each university is typically associated with a specific city and can have numerous nearby properties. The University attribute within a property can indicate its proximity to a particular university.

The Location model

The location model contains all the information about a city or university that is stored on Housemates' system. Following is a list of all the attributes that are available on the Location model.

Attributes

Name
name
Type
string
Description
The name of location i.e. city or university.
Name
slug
Type
string
Description
The slug of location i.e. city or university.
Name
coordinates
Type
object
Description
The coordinates of the location. i.e. latitude and longitude.
Name
university
Type
array of locations
Description
List of universities of the given city location. This field is only returned when querying cities.
Name
city
Type
location
Description
City of the given university location. This field is only returned when querying universities.

Location model

{
  "name":"Manchester",
  "slug":"manchester",
  "coordinates":{
    "lat":"52.48685840",
    "long":"-1.88821740"
  },
  "universities": [
    {
        "name": "The University of Manchester",
        "slug": "the-university-of-manchester",
        "coordinates": {
          "lat": "53.46684980",
          "long": "-2.23388370"
        }
    }
  ],
}

GET/api/universities

List all universities

When you invoke this endpoint, it returns a paginated list of universities, each equipped with key details. For each university in the list, you'll find not only its name and geographical coordinates, but the response also encapsulates information about the city where the university is located.

The city data is nested within each university item, offering an all-encompassing view of the university and its associated city. This design ensures a seamless, integrated experience, providing a comprehensive understanding of universities and their locations within a single response.

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
The number of items to return per page. The default value is 10.
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.
Name
filter[university]
Type
string
Description
Filter the results by university slug. e.g. filter[university]=abertay-university

Request

GET

/api/universities

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

    # Filter by city slug

curl --globoff --request GET \
    --url 'https://api.housemates.io/api/universities?filter[university]=university-of-salford' \
    --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":[
      {
        "name":"Abertay University",
        "slug":"abertay-university",
        "coordinates":{
          "lat":"56.46330700",
          "long":"-2.97391700"
        },
        "city":{
          "name":"Dundee",
          "slug":"dundee",
          "coordinates":{
            "lat":"56.46059380",
            "long":"-2.97019000"
          }
        }
      },
      // ... more items
    ],
    "meta":{
      "total":103,
      "count":10,
      "per_page":10,
      "current_page":1,
      "total_pages":11,
      "path":"https://api.housemates.io/universities",
      "links":[
        {
          "url":null,
          "label":"&laquo; Previous",
          "active":false
        },
        {
          "url":"https://api.housemates.io/universities?page=1",
          "label":"1",
          "active":true
        },
       // ... more links
      ]
    },
    "links":{
      "first":"https://api.housemates.io/universities?page=1",
      "last":"https://api.housemates.io/universities?page=11",
      "next":"https://api.housemates.io/universities?page=2",
      "prev":null
    }
  }
}

GET/api/cities

List all cities

When you invoke this endpoint, it returns a paginated list of cities, each equipped with key details. For each city in the list, you'll find not only its name and geographical coordinates, but the response also encapsulates information about list of universities located in the city.

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
The number of items to return per page. The default value is 10.
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.
Name
filter[city]
Type
string
Description
Filter the results by city slug. e.g. filter[city]=manchester

Request

GET

/api/cities

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

# Filter by city slug
curl --globoff --request GET \
    --url 'https://api.housemates.io/api/cities?filter[city]=manchester' \
    --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": [
      {
        "name": "Aberdeen",
        "slug": "aberdeen",
        "coordinates": {
          "lat": "57.14824290",
          "long": "-2.09280950"
        },
        "universities": [
          {
            "name": "University of Aberdeen",
            "slug": "university-of-aberdeen",
            "coordinates": {
              "lat": "57.16476000",
              "long": "-2.10152570"
            }
          },
        ]
      },
      // more items...
    ],
    "meta": {
      "total": 39,
      "count": 10,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 4,
      "path": "https://api.housemates.io/api/cities",
      "links": [
        {
          "url": null,
          "label": "&laquo; Previous",
          "active": false
        },
        {
          "url": "https://api.housemates.io/api/cities?page=1",
          "label": "1",
          "active": true
        },
        // ...
      ]
    },
    "links": {
      "first": "https://api.housemates.io/api/cities?page=1",
      "last": "https://api.housemates.io/api/cities?page=4",
      "next": "https://api.housemates.io/api/cities?page=2",
      "prev": null
    }
  }
}