Manage events and schedules

Venues often play host to shows, special celebrations, or other scheduled activities. These events may be regularly recurring (like a daily parade or regular 5pm occurrence of a show) or special one-time activities.

Getting schedule data by venue

All scheduled activities at a venue are retrieved using the following API:

1
2
3
curl -X GET \
  'https://api.{region}.te2.io/api/v2/venues/{id}/calendars/events?days={days}&date={date}' \
    -H 'Authorization: Bearer {token}'

Where:

• id: The venue id, as described in the Setup venues and POI guide.
• days: Optional. The number of days in the future to retrieve. If this parameter is excluded, the featuredEvents and trendingEvents will not be populated.
  * Although this field is optional, we recommend including it to ensure that your app does not get too much or too little data.
• date: Optional. The start date to retrieve schedule data, in the format YYYY-MM-DD (for example “2020-02-28”). This defaults to the current date.
• token: JWT token returned during authentication.

The resulting payload contains blocks for events, schedules, featuredEvents, and trendingEvents. Each is described in the following sections.

Event metadata

The events array contains metadata for all events that are scheduled to occur in the next nn days.

The most commonly used attributes are:

• id: The unique identifier for this event. Apps will use this id to match the metadata to schedules, featuredEvents, and trendingEvents.
• title: The guest-friendly name for this event.
• description: The guest-friendly description for this event.
• associatedPois: An array of POI ids where this event will occur; may be empty.
• displayCategories: An array of display categories that show this event; may be empty.
• images: An array of images for this event.
  • the type tells the app how to use the image.
  • the src relative URL and crop attributes are used as inputs to the image service to produce images for a particular user device (for example “https://img.te2.io/unsafe/1x0:1128x744/customer/cust-VenueID/poi/2eff1444-0e92-4f8e-8662-8f293fb42912/SampleImage.jpg”).

Schedules

The schedules array contains start and end timestamps in ISO 8601 format for every instance of a scheduled event. Recurring events will be repeated multiple times in the schedule, with one entry for each instance.

For example, a 30-minute show that is repeated at 08:30 AM, 10:00 AM, and 12:30 PM today would appear as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "events": [
    {
      "id": "event_big_show",
      "title": "The Big Show",
      "description": "This is the big event... don't miss it!"
    }
  ],
  "schedules": [
    {
      "eventId": "event_big_show",
      "start": "2019-03-15T08:30:00-05:00",
      "end": "2019-03-15T09:00:00-05:00",
      "isFullDay": false
    },
    {
      "eventId": "event_big_show",
      "start": "2019-03-15T10:00:00-05:00",
      "end": "2019-03-15T10:30:00-05:00",
      "isFullDay": false
    },
    {
      "eventId": "event_big_show",
      "start": "2019-03-15T12:30:00-05:00",
      "end": "2019-03-15T13:00:00-05:00",
      "isFullDay": false
    }
  ]
}

Featured events

Events that display in the featuredEvents array have been selected by the venue operator for extra attention. These events are typically shown as a hero image on the guest’s home screen or given special highlighting when they appear on an event list. Each featured event record has one or more scheduledInstances and an eventId that is used to get detailed metadata from the events array.

Trending events

Similarly, events that appear in the trendingEvents array have been identified as popular with guests and may be highlighted in guest applications. Trending events records also include scheduledInstances and eventId attributes for easy lookup.

Getting schedule data by POI

Scheduled activity data can also be retrieved for a single point of interest (POI). This is useful for applications that want to link from a detailed view of a POI to events that include that location.

1
2
3
curl -X GET \
  'https://api.{region}.te2.io/api/v2/pois/{id}/events?days={days}' \
    -H 'Authorization: Bearer {token}'

Where:

• id: The POI id, as described in the Fetching points of interest section of the Setup venues and POI guide.

This response includes title, description, images, schedules, and associatedPois as described above.