Yay, you made it! 🎉

Welcome to the documentation for UCL's brand new open API. Each service is listed below with examples in three different programming languages (Shell script using cURL, Python and JavaScript) to help you get going as quickly as possible.

The API will be made up of several services, each of which will be separately versioned and explained. Every service will be documented here with important information, tips and examples.

Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you'll be given a key that you can use to access all the services. Simples!

Each service has a header named uclapi-servicenamehere-version which you can add to your requests, where servicenamehere is the endpoint name for the service you are using. For example, for the Room Bookings service you would set the uclapi-roombookings-version header.

curl -H "uclapi-roombookings-version: 1" https://uclapi.com/roombookings/rooms?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb

import requests

params = {
  "token": "uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb"
}
headers = {
  "uclapi-roombookings-version": "1"
}
r = requests.get("https://uclapi.com/roombookings/rooms", params=params, headers=headers)
print(r.json())

var myHeaders = new Headers();
myHeaders.append("uclapi-roombookings-version", "1");
var initData = {
  method: 'GET',
  headers: myHeaders,
  mode: 'cors',
  cache: 'default'
};
fetch("https://uclapi.com/roombookings/rooms?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb", initData)
.then((response) => {
  return response.json()
})
.then((json) => {
  console.log(json);
  })

• By default, every UCL API request gets sent to the latest version of the service you requested.
• This is okay for test purposes.
• If you are deploying into production you must follow the versioning instructions to ensure you are not affected by breaking changes.

On the right hand side you'll see a code sample with the version data added. We are specifying that version 1 of the roombookings service should be used for the request URL https://uclapi.com/roombookings/rooms?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb. You should amend the example accordingly for the service and API version you are using.

The base url is https://uclapi.com/roombookings/

Endpoint: https://uclapi.com/roombookings/rooms

This endpoint returns rooms and information about them. If you don't specify any query parameters besides the token, all rooms will be returned.
Note: This endpoint only returns publicly bookable rooms. Departmentally bookable rooms are not included.

Allowed request type: GET

curl https://uclapi.com/roombookings/rooms?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb

import requests

params = {
  "token": "uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb"
}
r = requests.get("https://uclapi.com/roombookings/rooms", params=params)
print(r.json())

fetch("https://uclapi.com/roombookings/rooms?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb")
.then((response) => {
  return response.json()
})
.then((json) => {
  console.log(json);
  })

{
  "ok": true,
  "rooms": [
    {
      "roomname": "Wilkins Building (Main Building) Portico",
      "roomid": "Z4",
      "siteid": "005",
      "sitename": "Main Building",
      "capacity": 50,
      "classification": "SS",
      "automated": "N",
      "location": {
        "address": [
          "Gower Street",
          "London",
          "WC1E 6BT",
          ""
        ]
      }
    }
    ...
  ]
}

The room field contains a list of rooms that match your query. If no filters are applied, all rooms will be returned.

Endpoint: https://uclapi.com/roombookings/bookings

This endpoint shows the results to a bookings or space availability query. It returns a paginated list of bookings. Note: This endpoint only returns publicly displayed bookings. Departmental bookings are not included.

Allowed request type: GET

curl https://uclapi.com/roombookings/bookings?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&contact=Mark

import requests

params = {
  "token": "uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb",
  "contact": "Mark"
}
r = requests.get("https://uclapi.com/roombookings/bookings", params=params)
print(r.json())

fetch("https://uclapi.com/roombookings/bookings?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&contact=Mark")
.then((response) => {
  return response.json()
})
.then((json) => {
  console.log(json);
  })

{
   "ok": true,
   "bookings": [
      {  
          "slotid": 998503,
          "end_time": "2016-09-02T18:00:00+00:00",
          "description": "split weeks to assist rooming 29.06",
          "roomname": "Torrington (1-19) 433",
          "siteid": "086",
          "contact": "Ms Leah Markwick",
          "weeknumber": 1,
          "roomid": "433",
          "start_time": "2016-09-02T09:00:00+00:00",
          "phone": "45699"
       },
       ...
    ],
    "next_page_exists": true,
    "page_token": "6hb14hXjRV",
    "count": 1197
}

The bookings array contains booking objects, which each have the following properties.

Endpoint: https://uclapi.com/roombookings/bookings

Paginated requests also go to the /bookings endpoint but, unlike the regular requests, only the token and page_token should be supplied. All other filters are "remembered" from the initiating regular request.

The API "remembers" how many requests you've made, so to move through the pages you can keep making the same request (with the same token and page_token) until the response's next_page_exists field is false.

Allowed request type: GET

curl https://uclapi.com/roombookings/bookings?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&page_token=6hb14hXjRV

import requests

params = {
  "token": "uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb",
  "page_token": "6hb14hXjRV"
}

r = requests.get("https://uclapi.com/roombookings/bookings", params=params)
print(r.json())

fetch("https://uclapi.com/roombookings/bookings?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&page_token=6hb14hXjRV")
.then((response) => {
  return response.json()
})
.then((json) => {
  console.log(json);
  })

{
    "ok": true,
    "page_token": "wmCUiJgItq",
    "next_page_exists": true,
    "bookings": [
      {
        "roomname": "Christopher Ingold Building XLG2 Auditorium",
        "slotid": 733044,
        "siteid": "067",
        "start_time": "2017-03-20T13:00:00+00:00",
        "roomid": "XLG2",
        "weeknumber": 30,
        "description": "",
        "end_time": "2017-03-20T14:00:00+00:00",
        "phone": "",
        "contact": "Dr Mark Roberts"
      },
      ...
    ]
}

The response to a paginated request is identical to that of a regular request, except that no count field is provided.

Endpoint: https://uclapi.com/roombookings/equipment

This endpoint returns any equipment/feature information about a specific room. So, for example whether there is a Whiteboard or a DVD Player in the room. A full example can be seen here.

You need to supply a token, roomid, and siteid to get a response.

Allowed request type: GET

curl https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb

import requests

r = requests.get("https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb")
print(r.json())

fetch("https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb")
.then((response) => {
  return response.json()
})
.then((json) => {
  console.log(json);
  })

{
  "ok": true,
  "equipment": [
    {
      "type": "FF",
      "description": "Managed PC",
      "units": 1
    },
    {
      "type": "FE",
      "description": "Chairs with Tables",
      "units": 1
    },
    ...
  ]
}

The equipment field contains a list of equipment items. This list can have a different length depending on the room, and it can also be empty.

Each equipment item contains a type, a description, and the number of units.

This documentation is all open sourced at https://github.com/uclapi/apiDocs.

The full API is open sourced at https://github.com/uclapi/uclapi.

Any and all contributions are welcome! If you spot a tpyo or error, feel free to fix it and submit a pull request :)