Events

Events are, admittedly, a little confusing. To help alleviate this confusion, keep the following in mind when working with events:

Events can be either one-time events or recurring.
Events can have a specific start and end time or last all day. The values of the start and end properties will depend on whether the event has a specific start and end time or lasts all day.

Get a collection

      Endpoint
    
GET /events HTTP/1.1

Query string parameters

All query string parameters are optional.

callback string

Wraps the response in a callback function of the given name. Use this parameter to facilitate JSONP requests.

channels comma-separated list of IDs

Return events assigned to the given channels.

date string

Return events that take place on a specific date or within a date range. If specifying a range, separate start and end dates with a comma.

Format: YYYY-MM-DD[,YYYY-MM-DD]

divisions comma-separated list of IDs

Return events assigned to the given divisions.

event_categories comma-separated list of IDs

Return events assigned to the given event categories.

excluded_ids comma-separated list of IDs

Returns events, except those with the given IDs.

ids comma-separated list of IDs

Return events with the given IDs.

include_subterms comma-separated list of IDs

Works in conjunction with hierarchical taxonomy parameters to ensure returned events are assigned to either the specified term(s) or the children of the specified term(s). Hierarchical taxonomy parameter(s) available on events: event categories and locations

For example, /events?locations=668&include_subterms=668 will return events assigned to term #668 (Homewood Campus) and any other location whose parent is Homewood Campus.

locations comma-separated list of IDs

Return events assigned to the given locations.

open_to comma-separated list

Return events that may be attended by the given audience(s). Options: faulty, staff, students, everyone

Default value: everyone

order_by comma-separated list

Sort events by one or more ORDER_BY and ORDER parameter pairs. Options:

ORDER:
- asc: order from lowest to highest values
- desc: order from highest to lowest values
ORDER_BY:
- id: order by event ID
- list: order by the order of IDs given in the ids parameter
- publish_date: order by publish date
- score: order by popularity
- start_date: order by the starting date

Format: ORDER_BY|ORDER[,ORDER_BY|ORDER,...]

Default value: start_date|asc,id|asc

page integer

Return events from a specific page of a collection.

Default value: 1

per_page integer

Number of events to return per page of a collection. Maximum: 100

Default value: 5

single_events boolean

When true, recurring events are expanded into individual event objects. For example, an event that recurs 10 times will be represented with 10 separate objects in the event collection.

When false, recurring events are returned as a single event object. For example, an event that recurs 10 times will be represented with 1 object in the event collection. Inspect _embedded.event_instances for a list of all instances of the event.

Default value: true

source comma-separated list

Return events published by the specified source(s). Options:

all: returns all events in the database.
hub: returns only events published to the Hub calendar. Events excluded from the Hub calendar consist mostly of HR-related events.

Default value: hub

start_date string

Return events that start on a specific date.

Format: YYYY-MM-DD

tags comma-separated list of IDs

Return events assigned to the given tags.

type comma-separated list

Return events of a specific type. Options:

all: every event in the system (past and present).
past: events that have already occurred.
upcoming: events that are currently taking place or have yet to occur.

Default value: upcoming

Response

In the example response, embedded events are truncated for illustrative purposes. In the real-world version of the response, "...event object..." is an entire event resource.

      The event collection
    
{
   "_embedded": {
      "events": [
         "...event object...",
         "...event object...",
         "...event object...",
         "...event object...",
         "...event object..."
      ]
   },
   "_links": {
      "find": {
         "href": "/events/{?id}",
         "templated": true
      },
      "next": {
         "href": "/events?page=3"
      },
      "prev": {
         "href": "/events?page=1"
      },
      "self": {
         "href": "/events?page=2"
      }
   },
   "page": 1,
   "per_page": 5,
   "return_count": 5,
   "total_available": 100
}

Attributes

_embedded hash: Embedded resources.
_links hash: Links to resources associated with the event collection.
page integer: The page number of the returned collection.
per_page integer: The number of events requested per page.
return_count integer: Number of events returned.
total_available integer: Total number of events available in the collection.

Get one

      Endpoint
    
GET /events/:id HTTP/1.1

Endpoint parameters

id integer required: The unique identifier of the event.

Response

      GET /events/52177
    
{
   "_embedded": {
      "divisions": null,
      "event_categories": null,
      "event_instances": null,
      "image_thumbnail": null,
      "locations": null,
      "tags": null
   },
   "_links": {
      "self": {
         "href": "/events/52177"
      }
   },
   "end": {
      "dateTime": "2023-05-17T16:00:00-04:00",
      "timestamp": 1684353600
   },
   "end_date": "2023-05-17",
   "end_time": "16:00",
   "excerpt": "Inspired by archival photographs from over 100 years ago, current Gilman photography students working under teacher Sarah Sachs have created original art that merges the past with the present. Exhibition on view from May 17 to Sept. 17.",
   "id": 52177,
   "name": "Gilman: A Pictured History",
   "open_to": [
      "everyone",
      "faculty",
      "staff",
      "students"
   ],
   "publish_date": 1683572302,
   "short_url": "https://hub.jhu.edu/events/2023/05/17/gilman-a-pictured-history/",
   "slug": "gilman-a-pictured-history",
   "start": {
      "dateTime": "2023-05-17T11:00:00-04:00",
      "timestamp": 1684335600
   },
   "start_date": "2023-05-17",
   "start_time": "11:00",
   "type": "event",
   "url": "https://hub.jhu.edu/events/2023/05/17/gilman-a-pictured-history/"
}

Attributes

_embedded hash

Embedded resources.

_embedded.divisions[] array|null

An array of divisions assigned to the event or null if none are assigned.

_embedded.event_categories[] array|null

An array of event categories assigned to the event or null if none are assigned.

_embedded.event_instances[] array

An array of instances of the event. Will consist of multiple instances if the event is recurring.

Note: This attribute is not present when the event object is part of a collection where the single_events query string parameter is true (the default). See the event’s start and end attributes instead.

_embedded.event_instances[].end hash: The end date and/or time of the event instance.
_embedded.event_instances[].id string: Unique ID of the event instance.
_embedded.event_instances[].start hash: The start date and/or time of the event instance.
_embedded.event_instances[].type string: Type of resource.
_embedded.event_instances[].url string: Full URL of the event instance.

_embedded.image_thumbnail[] array|null

An array containing the file assigned as the thumbnail image of the event or null if not assigned

_embedded.locations[] array|null

An array of locations assigned to the event or null if none are assigned.

_embedded.tags[] array|null

An array of tags assigned to the event or null if none are assigned.

_links hash

Links to resources associated with the event.

_links.self link object: A link that identifies the current resource.

end hash

The end date and/or time of the event instance.

If the event is part of a collection where the single_events query string parameter is true (the default), this attribute’s value reflects the event instance represented by this object in the collection. Otherwise, it reflects the first upcoming instance of this event.

end.date string: The date in YYYY-MM-DD format. Present on events that are all day events.
end.dateTime string: The date and time in ISO 8601 format. Present on events that have specific start/end times.
end.timestamp timestamp: The date and time as a Unix timestamp. Present on events that have specific start/end times.

end_date deprecated

end_time deprecated

excerpt string

A short summary of the event.

id integer

Unique identifier of the event.

name string

The title of the event.

open_to array

A list of audiences that can attend the event. Possible values: faulty, staff, students, everyone

publish_date timestamp

The date of publication as a Unix timestamp in seconds.

short_url deprecated

slug string

The last part of the URL that identifies the resource.

start hash

The start date and/or time of the event instance.

start.date string: The date in YYYY-MM-DD format. Present on events that are all day events.
start.dateTime string: The date and time in ISO 8601 format. Present on events that have specific start/end times.
start.timestamp timestamp: The date and time as a Unix timestamp. Present on events that have specific start/end times.

start_date deprecated

start_time deprecated

type string

Type of resource.

url string

Full URL of the event.

Get a subcollection

A subcollection is a collection of objects contained within an event.

      Endpoint
    
GET /events/:id/:subcollection HTTP/1.1

Endpoint parameters

id integer: The unique identifier of the event.
subcollection string: The name of the subcollection to retrieve. Options: channels, divisions, event_categories, locations, or tags

Query string parameters

To filter the subcollection, see the list of available parameters associated with the chosen subcollection:

Response

See the response associated with the chosen subcollection: