Page Comparison

...

The resources support both JSON and XML output. By default, the returned format depends on the HTTP Accept header. Use application/json for JSON and application/xml for XML. It is also possible to specify the output format in the URL, by appending .json or .xml to the resource name, before the query string. Dates and times are returned in ISO 8601 format (yyyy-MM-ddTHH:mm:ss±HH:mm) when retrieving results in XML, and in Unix timestamp format when retrieving JSON (in milliseconds, instead of the default seconds). 

In the future, the API will only support JSON output, so we strongly recommend to implement your API client based on the JSON output.

Output can be available in multiple languages. Use the Accept-Language HTTP header to specify the locale, for example nl-NL. When the specified locale is not available, the default locale will be used.

Input can be provided in the form of HTTP GET URL parameters (which should be URL encoded properly) or an HTTP POST/PUT body that is in application/x-www-form-urlencoded. Most parameters are optional, when this is not the case this is mentioned in the documentation. Dates and times can be specified in one of the following format:

• 'today' or 'tomorrow' for the current or next day at 0:00;
• Unix timestamp format (in milliseconds sinds 1970, so don't forget to multiply/divide by 1000);
• ISO 8601 format (yyyy-MM-ddTHH:mm:ss±HH:mm): elements on the right side (time, time zone) are optional;
• Legacy format (yyyy/MM/dd HH:mm): the time is optional.

Authentication and authorisation

...

• The API-token is a secret, and should only be used in back-end services. Do not include it in your end-user application.
• Enable GZIP-compression in your API library. Support for non-compressed responses may be dropped in the future.
• Make sure your client supports TLS v1.2, older versions may not be available.
• Do not cache data for long periods of time (or at all), but do make sure end-users cannot trigger useless API requests (e.g., cache while the user is in the same view, and do not let the user refresh 100's of times by simply spamming a button).
• The schema may change as fields may be added. Be sure to ignore unknown fields in your data mapper.
• Do not 'scrape' the API and store data locally. It causes a high load and stale data.
• Do not perform unnecessarily large requests or a large number of requests. E.g., if you want to show the upcoming 5 activities of a location, just request the upcoming 5 activities and not the timetable for the whole year. Also, do not refresh that view every minute, as the timetable will not change every minute.
• In the future, the API will only support JSON output, so we strongly recommend to implement your API client based on the JSON output.

Version numbering

The API uses a version numbering scheme and the base URL of the API is: $base_url/api/v$version. The current API version is version 0. Non-breaking changes (like the addition of extra information or methods) will be done without incrementing the version number. On breaking changes the version number will be increased. Multiple API versions may exist at the same time. Eveoh will try to support older API versions when technically and economically feasible, but users are encouraged to always use the latest API version.

...

{
    "timetableType": [
        "location", 
        "zone", 
        "module", 
        "student", 
        "staff", 
        "pos", 
        "posss", 
        "studentset", 
        "studentsetgroup", 
        "modulegroup", 
        "user",
		"tag"
    ]
}

/timetabletypesdetails   (since MyTimetable 3.0)

Method: GET

Description: Query all possible timetable types and return them including some details regards naming, whether or not they can include child timetables and their ordering in the menus. 

...

/timetables/{key}/options    (since MyTimetable 3.1)

Method: GET

Description: Query the available options for the specified timetable. These options can be set on the subscription using the PUT call on a subscription. The allEquivalent boolean in the output will be true if any choice of options results in the same timetable.

...

/timetables/{parent}/{key}/options    (since MyTimetable 3.1)

Method: GET

Description: Query the available options for the specified child of a timetable. These options can be set on the subscription using the PUT call on a subscription. The allEquivalent boolean in the output will be true if any choice of options results in the same timetable.

...

/subscriptions/{key}/options     (since MyTimetable 3.1)

Method: PUT

Description: Set selected options of a subscription. Specifying all possible options will cause the list of selected options to be cleared, showing the complete timetable to the user.

...

/subscriptions/{parent}/{key}/options     (since MyTimetable 3.1)

Method: PUT

Description: Set selected options of a subscription nested under a parent. Specifying all possible options will cause the list of selected options to be cleared, showing the complete timetable to the user.

...

{
    "feedUrl": "http://myuniversity/ical?eu=FKW92Fawier&t=556cf8a1-704a-4997-bc4d-5acf395eccaf",
    "username": "testuser"
}

/weeklabels   (deprecated since MyTimetable 2.7, replaced by: /weeklabelmaps)

Method: GET

Description: Query the weeklabels. This provides custom labels for the weeks when available. The response includes a value (the custom label) and a week (year - 1900 + the ISO week number).

...

{
    weeklabel: [
        {
            "week": 11223,
            "value": "23"
        },
        {
            "week": 11224,
            "value": "24"
        }
    ]
}

/weeklabelmaps   (since MyTimetable 2.7)

Method: GET

Description: Query the weeklabel maps. This provides the available maps with custom labels for the weeks. Per weeklabel map, the response includes a key and a boolean which indicates whether the map is the default weeklabel map for the requested user.

...

{
    "weeklabelmaps": [
        {
            "key": "SYLLABUS",
            "isDefault": true
        }
    ]
}

/weeklabelmaps/{key}   (since MyTimetable 2.7)

Method: GET

Description: Retrieve the specified weeklabel map. This provides the key, a boolean which indicates if this is the default weeklabel map for the requested user and the actiual map with custom labels for the weeks.

...

{
    "key": "SYLLABUS",
    "isDefault": true,
    "weeklabels": [
        {
            "year": 2014,
            "week": 4,
            "description": "wk 4"
        },
        {
            "year": 2014,
            "week": 5,
            "description": "wk 5"
        }
    ]
}

/databases    (deprecated since MyTimetable 3.1, replaced by: /databasedetails)

Method: GET

Description: Query the available datasources, see 3114172430 for more information. For MyTimetable 3.1+, please use the /databasedetails call, which also provides the labels of the databases.

...

{
    "database": [
        "2011"
    ]
}

/databasedetails   (since MyTimetable 3.1)

Method: GET

Description: Query the available datasources, see 3114172430 for more information. The key (to be used in the query string of other calls) and the label are returned.

...

{
    "databases": [
        {
            "key": "2015",
            "label": "2015/2016"
        },
        {
            "key": "2016",
            "label": "2016/2017"
        },
        {
            "key": "TimetableDB",
            "label": "Custom"
        }
    ]
}

/eventtypegroups   (since MyTimetable 3.0)

Method: GET

Description: Query the event type groups and event filtering settings.

...

$base_url/api/v0/eventtypegroups

Request Content-Type

application/x-www-form-urlencoded

Example request body

eventTypeGroups%5BExcursie%5D%5BisFiltered%5D=true&eventTypeGroups%5BHoorcollege%5D%5BisFiltered%5D=false&eventTypeGroups%5BOther%5D%5BisFiltered%5D=false

...

204 (No content), 403 (Forbidden) if filtering is disabled.

/terms   (since MyTimetable 3.4)

Method: GET

Description: Query the available terms. Returns a list of terms, each containing of a unique id, a key (may be null), a name and a list of date ranges.

...

{
    "terms": [
        {
            "dateRanges": [
                {
                    "endDate": 1513983600000,
                    "startDate": 1504476000000
                },
                {
                    "endDate": 1535925600000,
                    "startDate": 1514847600000
                }
            ],
            "id": "2017!492E26C5A6F3BDE74C11240C046C2FB1",
            "key": null,
            "name": "[2017/2018] All year"
        },
        {
            "dateRanges": [
                {
                    "endDate": 1535925600000,
                    "startDate": 1504476000000
                }
            ],
            "id": "TermTime!13",
            "key": "All",
            "name": "[Term Time] All year"
        }
    ]
}

/user/messages   (since MyTimetable 4.0)

Note: this API endpoint always returns application/json as Content Type. XML is not supported.

Method: GET

Description: Query the active messages for the current user (as identified by the OAuth token or elevated API token). Requires scope messages_read.

...

Response code

200 (OK)

/messages   (since MyTimetable 4.0)

Note: this API endpoint always returns application/json as Content Type. XML is not supported.

Method: GET

Description: Retrieves messages. Requires API token scope ROLE_API_MESSAGES.

...

Request Content-Type header

application/x-www-form-urlencoded

Example request body

title=This%20is%20the%20title%20of%20a%20non-expiring%20message%20targeted%20to%20students%20marked%20as%20important.&body=%23%20This%20is%20a%20header%20formatted%20with%20Markdown%0AThis%20is%20some%20content.&important=true&publicationDate=2019-01-02&expirationDate=&targetRoles=ROLE_STAFF&targetRoles=ROLE_STUDENT

...

201 (Created) if the message is created, 400 (Bad Request) if input validation fails

/messages/{id}   (since MyTimetable 4.0)

Note: this API endpoint always returns application/json as Content Type. XML is not supported.

Method: GET

Description: Retrieves the message with the given ID. Requires API token scope ROLE_API_MESSAGES.

...

Request Content-Type header

application/x-www-form-urlencoded

Example request body

title=This%20is%20the%20edited%20title%20of%20a%20non-expiring%20message%20targeted%20to%20students%20marked%20as%20important.&body=%23%20This%20is%20an%20edited%20header%20formatted%20with%20Markdown%0AThis%20is%20some%20content.&important=false&publicationDate=2019-03-11&expirationDate=&targetRoles=ROLE_STAFF&targetRoles=ROLE_STUDENT

...