Timetable Generator API

An API exposing the functionality of Timetable Generator

Timetable Generator (desktop version, web version) is popular among U of T students, and over the years I've had many requests for new features, extensions, and support for other faculties/campuses or even other universities, as well as requests for a web version of Timetable Generator. While I plan to work on some of these things, I cannot possibly work on all of them, so I decided to make an API that exposes the functionality of Timetable Generator, and allows other people to build software based on this functionality.

In its current state, the API functionality is specific to the University of Toronto (more specifically, to the supported faculties within the University of Toronto, which are the Faculty of Arts and Science and the Faculty of Applied Science and engineering at the St. George campus), so the API is mainly useful for building other front-ends for the existing functionality.

However, most of the code is conceptually applicable to any faculty or university, and thus the API could be enhanced in the future to be more generic and support other faculties / universities as well. (Contributions in this area are welcome!)

As of November 2012, the Timetable Generator API is open source.

I have also released a related library called libtg-ui which contains utilities for writing UIs on top of the Timetable Generator API. The Timetable Generator API together with libtg-ui currently power the desktop and web versions of Timetable Generator.

Download

The Timetable Generator API takes the form of a C++ software library.

Get it here:

(For previous releases, I provided pre-built binary distributions as well, but I found that using them was quite error-prone. The chances of an application using the library successfully linking against the pre-built binary, and the resulting executable running correctly, were quite small, as a number of things such as compiler and library versions had to match. As a result, I discontinued distributing binary releases. Please build the library from source as instructed in the README.txt file in the source distribution.)

Don't forget to also check out libtg-ui, a library of utilities for writing UIs on top of the Timetable Generator API.

Features

Timetable Generator is built on top the Timetable Generator API, so the API has all the features that Timetable Generator has (other than UI-specific functionality, of course).

Over time, it is possible that the API will acquire features that the desktop version of Timetable Generator does not have; if that happens, I will document those features here.

FAQ

Q: What exactly is an API?

A: API stands for Application Programming Interface. It refers to the interface provided by a software component that allows other software components to interact with/use it. In the case of the Timetable Generator API, the software component (to which the API is an interface) is a software library that exposes the functionality of Timetable Generator.

Q: Is the Timetable Generator API free/open-source software?

A: Yes, it is! It is available under the GNU Lesser General Public License (LGPL), version 3 or later, with an exception that allows static linking without having to distribute the resulting program under the LGPL. For details, please see the LICENSE.txt file in the source distribution.

Q: What are the prerequisites for using the API?

A: To build the library that implements the API, you need a recent C++ compiler and some prerequisite libraries such as Boost. For details, see the README file of the source distribution.

Q: Since this is a C++ library, does my program have to be written in C++ to use it?

A: To use the API directly, your program needs to be written in C++. However, it is possible to use the API indirectly from a program written in a different language. There are two approaches for doing this.

The first approach is to wrap the API into an interface written in the other language. Such an interface is called a binding. There are currently no bindings to the Timetable Generator API for any language other than C++, and I have no immediate plans for writing any. However, I encourage people who need a binding for a particular language to write one and contribute it back to the project, so that others can use it as well. If you'd like to write a binding but don't know how, here are some links to get you started:

  • For C# bindings, you can use P/Invoke
  • For Java bindings, you can use JNI, JNA, Bridj, or SWIG
  • For scripting language bindings (python, php, etc.), you can use SWIG

If you have written a binding, and would like to share it with others, please let me know and I will link to it from here.

The second approach is to write a wrapper program in C++ which can be invoked from the program written in the other language, receives inputs for the API functions from the other program, calls the API functions, and communicates back the results to the other program. The communication between the C++ program and the other program can take various forms, such as files or sockets.

The first approach (bindings) is generally easier, and I would recommend it over the second approach. However, bindings have some limitations, and in some cases the second approach may be necessary.

Q: What is 'libtg'?

A: 'libtg' is the name of the static library that contains the implementations of the API functions. If you're wondering about the name, it is Unix convention to prefix libraries with 'lib', and 'tg' stands for Timetable Generator. I also use the name 'libtg' for the entire package (API headers + implementation).

Version History

Version 0.6.5 (released April 6, 2017)

  • Features
    • Updated timetable data parsers to support the latest timetable data (2016-2017 Fall/Winter and 2017 Summer as of the date of the release)
      • For the Faculty of Arts and Science, this involved adding support for the new JSON API their website has been using since Fall 2016
      • Since this new data format doesn't contain information about alternate-week labs in an easy-to-parse format, added support for providing this information manually by listing the courses that have alternate-week labs in a new data file, altwks.txt.
      • Also added a mechanism for collecting the information necessary to prepare altwks.txt (which is present in the data files, just not in an easy-to-parse format).
  • API
    • CourseLoad::GetConfig() and CourseLoad::GetSelectedConfig() now return configurations with the offerings sorted by activity code. Previously, the order was an order used internally by performance, which could seem arbitrary to clients.
  • Internals
    • Fixed a recurring issue where UpdateTimetableData() would sometimes hang while downloading files from the Faculty of Applied Science and Engineering website. The issue is a intermittent bug on the web server's side, which we work around by timing out and re-trying request after an interval.
    • Significantly improved error reporting during timetable data parsing. Parsing errors now contain a "trace" that pinpoints what section of the data was being parsed at the time the error occurred.
    • Numerous improvements to the robustness of timetable data parsing algorithms
    • Numerous bug fixes

Version 0.6.4 (released June 4, 2014)

  • Fixed a regression introduced in version 0.6.3 where UpdateTimetableData() produced timetable data files that could not be read (via LoadTimetableData()) using clients running version 0.6.2 or older
  • Timetable data parser now ignores courses that are exact duplicates of each other (several of these appeared in the 2014-2015 Arts and Science data)
  • Fixed a performance regression introduced in version 0.6.0 where UpdateTimetableData() would unnecessarily download Arts and Science HTML files twice

Version 0.6.3 (released May 20, 2014)

  • Added support for 2014 Arts and Science Summer data
  • Added support for 2014-2015 Arts and Science Fall/Winter timetable data
  • Improved robustness of timetable data parsing algorithms
  • Improved error reporting during timetable data parsing

Version 0.6.2 (released September 16, 2013)

  • Features
    • Added support for 2013-2014 Applied Sciences & Engineering Fall/Winter timetable data.
    • Updated timetable data parsers in accordance with changes to the websites from which the data is scraped.
    • Made the library multithreading-safe. See the Thread Safety section of the documentation for details.
  • API
    • Removed the requirement that UpdateTimetableData(), LoadTimetableData(), and ReloadData() can only be called if there are no course loads open. Now, if they are called while course loads are open, the already-open course loads will continue to use the old timetable data, and new course loads will use the newly loaded or updated timetable data.
    • Added a new version of the GenerateTimetables() API which allows specifying an upper limit on the number of timetable generated for each configuration.
    • Removed TimetableManager::GetCoursesForStudySession(). CourseLoad::GetCoursesForSelectedStudySession() should be used for accessing courses.
    • Moved GetStudySessions() from TimetableManager to CourseLoad. This is because different course loads can now have different timetable data loaded.
    • Removed Offerings::get_activity_code_part() and Offerings::get_activity_code_and_title().
    • Introduced a mechanism to specify the error-handling behaviour when opening a course load file.
    • Various other minor improvements to the API.
  • Internals
    • Improved the build system's consistency and conformance with Unix conventions.
    • Improved error reporting.
    • Numerous bug fixes and documentation improvements.

Version 0.6.1 (released April 3, 2013)

  • Added support for 2013 Arts and Science Summer data
  • Added support for 2013-2014 Arts and Science Fall/Winter timetable data
  • Fixed a bug in the ReloadData() API where inventories weren't being reloaded, leading to spurious errors
  • Added proper support for compiling with clang
  • Improved const-correctness of the API
  • Improved error reporting during the timetable data update process

Version 0.6.0 (released November 9, 2012)

  • Features
    • Added support for first-year seminar courses
    • Added proper support for courses with different titles in the fall and spring terms
    • Fixed a bug where engineering courses that ran from 9 AM - 10 AM were interpreted as running from 9 AM - 10 PM instead
  • API
    • Refactored the management of user sessions and course loads, splitting TimetableManager into 3 classes (TimetableManager, UserSession, and CourseLoad). This significantly simplified the API.
    • Added SetConfigurations() API
    • Other minor simplifications and improvements to the API
    • Renamed API classes to achieve consistency of naming convention
  • Internals
    • Significantly improved (by a factor of 2-3) the speed and memory usage of the timetable generation algorithm.
    • Dropped support for MSVC. It is too slow in it C++11 feature adoption.
    • Improved the stability of the timetable data parsing algorithm
    • Numerous bug fixes
    • Comprehensive cleanup and commenting of codebase in preparation for public source release
    • Overhauled build system in preparation for public source release
    • Released library as open source, under LGPLv3 + static linking exception

Version 0.5.4 (released April 26, 2012)

  • Added support for 2012-2013 Arts and Science Fall/Winter timetable data
  • Added support for 2012 Arts and Science Summer data
  • Improved error reporting
  • Added ReloadData() API

Version 0.5.3 (released March 17, 2012)

  • This is the first version that I made available publically

Old Versions
Version Release Date Source Release Binary Release
Linux Windows
x86 x64 x86
Latest (0.6.5) April 6, 2017 libtg-0.6.5-src.zip Discontinued. Please build the library from source.
0.6.4 June 4, 2014 See the source code repository libtg-0.6.4-linux-x86-gcc.zip libtg-0.6.4-linux-x64-gcc.zip libtg-0.6.4-win-x86-mingw.zip
0.6.3 May 20, 2014 libtg-0.6.3-linux-x86-gcc.zip libtg-0.6.3-linux-x64-gcc.zip libtg-0.6.3-win-x86-mingw.zip
0.6.2 September 16, 2013 libtg-0.6.2-linux-x86-gcc.zip libtg-0.6.2-linux-x64-gcc.zip libtg-0.6.2-win-x86-mingw.zip
0.6.1 April 3, 2013 libtg-0.6.1-linux-x86-gcc.zip libtg-0.6.1-linux-x64-gcc.zip libtg-0.6.1-win-x86-mingw.zip
0.6.0 November 9, 2012 libtg-0.6.0-linux-x86-gcc.zip libtg-0.6.0-linux-x64-gcc.zip libtg-0.6.0-win-x86-mingw.zip
0.5.4 April 26, 2012 libtg-0.5.4-linux-x86-gcc.tgz libtg-0.5.4-linux-x64-gcc.tgz libtg-0.5.4-win-x86-mingw.zip
0.5.3 March 17, 2012 libtg-0.5.3-linux-x86-gcc.tgz libtg-0.5.3-linux-x64-gcc.tgz libtg-0.5.3-win-x86-mingw.zip

Contact Info

Your suggestions (and feature requests, bug reports, etc.) are welcome.

Please send them to: