openapi: 3.0.1
info:
description: "NUSMods API contains data used to render <https://nusmods.com>. It includes data on modules offered by NUS and their timetables, as well as information on the locations the classes take place in. You are welcome to use and experiment with the data, which is extracted from official APIs provided by the Registrar's Office.\n\nThe API consists of static JSON files scraped daily from the school's APIs. This means it only partially follow REST conventions, and all resources are read only. All successful responses will return JSON, and all endpoints end in `.json`.\n\nThe shape of the data returned by these endpoints are designed for NUSMods in mind. If you have any questions or find that you need the data in other shapes for other purposes, feel free to reach out to us:\n\n- **Telegram**: <https://telegram.me/nusmods>\n- **Mailing list**: <mods@nusmods.com>\n\n## Fetching data\n\nAny HTTP client can be used to fetch data from the API. HTTPS is preferred, but the server will also respond to HTTP requests. The server supports HTTP 1.1 as well as HTTP 2 over HTTPS, and supports gzip compression.\n\nThe API has no authentication, and is not rate limited. While the server can respond to a large number of requests simultaneously, we request that you be polite with resource usage so as not to disrupt nusmods.com, which relies on the same API server. In general there is no need to fetch data from the API more than once per day, as that is the frequency at which we update the data.\n\n[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers are enabled on all endpoints, so client-side JavaScript can use also use the API.\n\n## TypeScript types\n\nSince the NUSMods is written in TypeScript, typings are available in the source for the scraper. These may be easier to read than the documentation generated by Swagger.\n\n- Module types: <https://github.com/nusmodifications/nusmods/blob/master/scrapers/nus-v2/src/types/modules.ts>\n- Venue types: <https://github.com/nusmodifications/nusmods/blob/master/scrapers/nus-v2/src/types/venues.ts>\n\n## Data\n\nBelow are some notes about the data returned from the API. Feel free to talk to us or create an issue if any of it is not clear.\n\n### Module data\n\nModule endpoints return information on modules offered by NUS. Most of the module data is self-explanatory, but some of the data are more complex and is explained here.\n\n#### Lessons\n\nEach lesson in a timetable has a lesson type `lessonType` and class number `ClassNo`. Every student must take one of each lesson type offered by the module. For example, this module offers two tutorials and one lecture. That means the student must attend the lecture, and can choose one of the two tutorials to attend.\n\n```json\n{\n \"timetable\": [\n {\n \"classNo\": \"1\",\n \"lessonType\": \"Lecture\",\n \"weeks\": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13],\n \"day\": \"Tuesday\",\n \"startTime\": \"1600\",\n \"endTime\": \"1800\",\n \"venue\": \"I3-AUD\"\n },\n {\n \"classNo\": \"01\",\n \"lessonType\": \"Tutorial\",\n \"weeks\": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13],\n \"day\": \"Wednesday\",\n \"startTime\": \"1100\",\n \"endTime\": \"1200\",\n \"venue\": \"COM1-0207\"\n },\n {\n \"classNo\": \"02\",\n \"lessonType\": \"Tutorial\",\n \"weeks\": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13],\n \"day\": \"Friday\",\n \"startTime\": \"0900\",\n \"endTime\": \"1000\",\n \"venue\": \"COM1-0209\"\n }\n ]\n}\n```\n\nEach lesson has a `classNo` key. There can be multiple lessons of the same type and class number, in which case students must attend both. In this example, students can choose to attend either lecture group 1 on Tuesdays and Wednesdays, or lecture group 2 on Mondays and Wednesdays.\n\n```json\n{\n \"timetable\": [\n {\n \"classNo\": \"1\",\n \"lessonType\": \"Lecture\",\n \"weeks\": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13],\n \"day\": \"Tuesday\",\n \"startTime\": \"1600\",\n \"endTime\": \"1800\",\n \"venue\": \"I3-AUD\"\n },\n {\n \"classNo\": \"1\",\n \"lessonType\": \"Lecture\",\n \"weeks\": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13],\n \"day\": \"Wednesday\",\n \"startTime\": \"1400\",\n \"endTime\": \"1500\",\n \"venue\": \"I3-AUD\"\n },\n {\n \"classNo\": \"2\",\n \"lessonType\": \"Lecture\",\n \"weeks\": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13],\n \"day\": \"Monday\",\n \"startTime\": \"1000\",\n \"endTime\": \"1200\",\n \"venue\": \"I3-AUD\"\n },\n {\n \"classNo\": \"2\",\n \"lessonType\": \"Lecture\",\n \"weeks\": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13],\n \"day\": \"Wednesday\",\n \"startTime\": \"1500\",\n \"endTime\": \"1600\",\n \"venue\": \"I3-AUD\"\n }\n ]\n}\n```\n\n#### Lesson Weeks\n\nThe `weeks` key on lessons can return data in one of two forms.\n\nWeeks is usually a sorted array of numbers. In this case it represents the school weeks the lesson occurs on, from 1 to 13.\n\nSome classes have lessons outside of the school timetable. In this case a `WeekRange` object is returned. The object will always contain a `start` and `end` key representing the start and end date of lessons. The example below has classes every week from 17th Jan to 18th April.\n\n``` json\n\"weeks\": {\n \"start\": \"2019-01-17\",\n \"end\": \"2019-04-18\"\n}\n```\n\nOptionally it can also include `weekInterval`, a positive integer describing the number of weeks between each lesson, and `weeks`, an array of positive integers describing the weeks on which the lesson will fall, with week 1 being the starting date. If these are not present you can assume lessons will occur every week.\n\nThe following example has lessons on 17th Jan (week 1), 24th Jan (week 2), 7th Feb (week 4) and 21st Feb (week 6).\n\n``` json\n\"weeks\": {\n \"start\": \"2019-01-17\",\n \"end\": \"2019-02-21\",\n \"weeks\": [1, 2, 4, 6]\n}\n```\n\nThe following example has lessons on 17th Jan (week 1), 31st Jan (week 3), 14th Feb (week 5) and 28th Feb (week 7).\n\n``` json\n\"weeks\": {\n \"start\": \"2019-01-17\",\n \"end\": \"2019-02-28\",\n \"weekInterval\": 2\n}\n```\n\n#### Workload\n\nThe `workload` key can return data in one of two forms.\n\nWorkload is usually a **5-tuple of numbers**, describing the estimated number of hours per week the student is expected to put in for the module for **lectures, tutorials, laboratory, projects/fieldwork, and preparatory work** respectively. For example, a workload of `[2, 1, 1, 3, 3]` means the student should spend every week\n\n- 2 hours in lectures\n- 1 hour in tutorials\n- 1 hour at the lab\n- 3 hours doing project work\n- 3 hours preparing for classes\n\nEach module credit represents 2.5 hours of work each week, so the standard 4 MC module represents 10 hours of work each week. Module credit may not be integers.\n\nNote that this is only an estimate, and may be outdated or differ significantly in reality. Some modules also incorrectly lists the **total** workload hours instead of weekly, so very large values may show up.\n\nThis value is parsed from a string provided by the school, and occasionally this field will contain unusual values which cannot be parsed. In this case this field will contain the original **string** instead, which should be displayed as-is to the user.\n\n#### Prerequisite, corequisite and preclusions\n\nThese three keys determine whether a student can take a module.\n\n**Prerequisites** are requirements you have to meet before you can take a module. These are usually in the form of other modules (see prerequisite tree below for a machine readable format), but can also be things like 'taken A-level H2 math' or '70 MCs and above'.\n\n**Preclusions** refer to modules or requirements that cannot be taken if this module is taken, and vice versa. These are usually modules whose content overlaps significantly with this module, and can usually be used to replace each other to fulfill prerequisites.\n\n**Corequisites** are modules that must be taken together with this module in the same semester. This usually refer to twined modules - modules which have linked syllabuses.\n\n#### Prerequisite Tree\n\nThe `prereqTree` key is return on the individual module endpoint (`/modules/{moduleCode`). Not all modules have prerequisites, and some have prerequisites that cannot be properly represented as a tree, in which case this key will not appear.\n\nThis describes the prerequisites that need to be fulfilled before this module can be taken. The data structure is recursive and represents a tree.\n\n```json\n{\n \"and\": [\n \"CS1231\",\n {\n \"or\": [\"CS1010S\", \"CS1010X\"]\n }\n ]\n}\n```\n\nIn the example, this module requires CS1231 and either CS1010S or CS1010X. This can be visualized as\n\n```\n ┌ CS1231\n── all of ─┤\n │ ┌ CS1010\n └ one of ─┤\n └ CS1010X\n```\n\nThe module information also contains the inverse of this, that is, modules whose requirements are fulfilled by this module (taking this module will allow you to take these modules in the following semester). The data is found on the `fulfillRequirements` key as an array of module codes.\n\n### Venue data\n\nVenue data is simply the module timetable restructured to show the lessons happening at each classroom.\n\nThe venue list endpoint returns a list of all locations that are used in the semester. Note that this is not a comprehensive list of locations, but rather just a list of venues that appears in module lessons.\n\nThe venue information endpoint returns the full class and occupancy information about a venue. The `classes` key contains a list of lessons similar to the `timetable` key in module data, but without a `venue` key and with `moduleCode`.\n"
title: NUSMods Modules Venues API
version: 2.0.0
contact:
email: mods@nusmods.com
servers:
- url: https://api.nusmods.com/v2
- url: http://api.nusmods.com/v2
tags:
- name: Venues
paths:
/{acadYear}/semesters/{semester}/venues.json:
get:
summary: Get a list of all venues
parameters:
- $ref: '#/components/parameters/acadYear'
- $ref: '#/components/parameters/semester'
description: 'Get a list of all venues, including lecture theatres, seminar rooms, laboratories, etc. used in the given semester''s classes. This endpoint only returns an array of names, and is useful for searching and autocompletion.
'
tags:
- Venues
responses:
200:
description: Success
content:
application/json:
schema:
type: array
items:
type: string
example: LT19
404:
$ref: '#/components/responses/404'
/{acadYear}/semesters/{semester}/venueInformation.json:
get:
summary: Get detailed information on all venues
parameters:
- $ref: '#/components/parameters/acadYear'
- $ref: '#/components/parameters/semester'
description: 'Get detailed venue information including classes and occupancy for every venue. This is useful for displaying a timetable of the given venue as well as for checking if a venue is occupied at any given time.
'
tags:
- Venues
responses:
200:
description: Success
content:
application/json:
schema:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/VenueInformation'
example:
LT19:
- day: Monday
classes:
- classNo: '1'
startTime: '1830'
endTime: '2030'
weeks:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
day: Wednesday
lessonType: Lecture
moduleCode: CS5322
size: 40
availability:
0900: occupied
0930: occupied
1000: occupied
404:
$ref: '#/components/responses/404'
components:
parameters:
semester:
name: semester
in: path
description: semester, with 1 and 2 representing semester 1 and 2, and 3, 4 representing special term 1 and 2
required: true
schema:
type: number
enum:
- 1
- 2
- 3
- 4
acadYear:
name: acadYear
in: path
description: academic year, with the slash (/) replaced by a dash
required: true
schema:
type: string
example: 2018-2019
schemas:
Lesson:
required:
- classNo
- startTime
- endTime
- weeks
- venue
- lessonType
properties:
classNo:
type: string
example: 08
startTime:
type: string
example: '1100'
endTime:
type: string
example: '1200'
weeks:
oneOf:
- $ref: '#/components/schemas/WeekRange'
- type: array
items:
type: number
example:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
venue:
type: string
example: COM1-0208
day:
type: string
example: Friday
lessonType:
type: string
example: Tutorial
size:
type: number
example: 30
WeekRange:
required:
- start
- end
properties:
start:
type: string
format: date
example: '2019-01-17'
end:
type: string
format: date
example: '2019-06-20'
weekInterval:
type: number
example: 2
default: 1
weeks:
type: array
items:
type: number
example:
- 1
- 2
- 4
- 5
- 6
VenueInformation:
properties:
day:
type: string
enum:
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
classes:
type: array
items:
$ref: '#/components/schemas/VenueLesson'
availability:
type: object
additionalProperties:
enum:
- occupied
example:
0900: occupied
0930: occupied
1000: occupied
VenueLesson:
allOf:
- $ref: '#/components/schemas/Lesson'
- type: object
required:
- moduleCode
properties:
moduleCode:
type: string
example: CS1010S