Visualizations
WhenHub API
Event Object
Events are the core pieces of the schedules that make everything work. They are served as JSON objects, which have multiple layers to them. The values that are stored within them, is the data and settings that a user has input when he/she created the event. In order to access the information you need, you may have to traverse the tree-like structure. To help you better navigate the Event Object, here's the basic structure:
Below is an example of the event object in the form you will receive it in (JSON), as well as some additional information of its components to help you better understand it's information.
id
Event Id
name
Name of event
description
Description of event
When Object
The "when" object contains the information about the time the event is going to start, and optionally if an end date is present, the length of time an event will last.
when.period
Has several enum values:
- Minute
- Day
- Month
- Year
Each of which is used to represent the increment of the values stored in startDate and endDate. This field is required in order to create an event.
when.startDate & when.endDate
when.startDate is required for an event. Based on the value selected in the period field, the start date is represented as a string in one of the following formats
- Minute: YYYY-MM-DDTHH:mm:ssZ
- Day: YYYY-MM-DD
- Month: YYYY-MM
- Year: YYYY
If an endDate is not selected, the value will be null. Additionally, only the startDate field is required to create an event. The date parameter follows the ISO standard.
when.startTimeZone & when.endTimeZone
These fields specify which timezone the start and end date are in. The acceptable values can be found here Moment.js TimeZones.
Location Object
The "location" object is made of either a simple name property OR a complex object in the format provided by the Google Places API.
(see sample location object below)
Media object
The media object is created by uploading an image and associating that media with the event.
(See below for a more detailed example of the media object).
Custom Field Object
Custom field data is presented as an object of key/value pairs. The keys are the GUIDs of the corresponding custom field as defined in the schedule. Values vary based on the type of custom field. For more information, refer to the Understanding Custom Fields page .
primaryAction
This object contains the label and url of the primary action of the event. This link will be exposed in the Whencast if the visualization supports it. It will also be displayed in the Event Details.
{
"name": "Meet at Starbucks", // "string"
"description": "<p>Let's meet at our <strong>normal</strong> Starbucks!</p>", // "string"
"cleanDescription": "Let's meet at our normal Starbucks!", // "string"
"id": "58dd6bc3e42e4f8e34f0f98c", // "string"
"icon": "3d-glasses-blue-64", // "string" Icon from WhenHub icon library
"location": {
"name": "Starbucks", // "string"
"locality": null, // "string"
"address": "3595 California Street", // "string"
"streetNumber": "3595", // "string"
"streetName": "California Street", // "string"
"city": "San Francisco", // "string"
"postalCode": "94118", // "string"
"country": "United States", // "string"
"geolocation": {
"lat": 37.7861747, // float
"lng": -122.4531843 // float
},
"region": "CA", // "string"
"telephone": null, // "string"
"timezone": "America/Los_Angeles" // "string"
},
"tags": [
"Design", // "string"
"Development" // "string"
],
"customFieldData": {
// keys are defined by custom events being created in schedules
// value structures are defined by which custom field is defined in schedule
// Chart Field
"d92b2631-c28b-4261-86a0-ce2b50829b8e": {
"value": 7
},
// Label Value Fields
"ac516741-1a8e-42f0-961d-404dd111fcc6": {
"text": "test", // "string"
"value": "My Option A" // "string"
},
// Required Field
"8e3edf34-d036-41c0-8e51-733b0354bccf": {
"value": "Required Field value of mine." // "string"
},
// Select Fields
"88b9cc1e-4f2c-403f-a5df-640e9db50c36": {
"fields": [
{
"label": "My Test Label 1", // "string"
"value": "My Test Value 2" // "string"
},
{
"label": "My Test Label 2", // "string"
"value": "My Test Value 2" // "string"
}
]
},
// Repeat Fields
"d43d763f-d4fa-3684-91a8-2ce2e7be3237": {
"fields": [
{
"My Repeat Label 1": "Repeat Value 1 A", // "string"
"My Repeat Label 2": "Repeat Value 2 A", // "string"
"My Repeat Label 3": "Repeat Value 3 A" // "string"
},
{
"My Repeat Label 1": "Repeat Value 1 B", // "string"
"My Repeat Label 2": "Repeat Value 2 B", // "string"
"My Repeat Label 3": "Repeat Value 3 B" // "string"
},
{
"My Repeat Label 1": "Repeat Value 1 C", // "string"
"My Repeat Label 2": "Repeat Value 2 C", // "string"
"My Repeat Label 3": "Repeat Value 3 C" // "string"
}
]
}
},
"primaryAction": {
"url": "https://www.whenhub.com/", // "url"
"label": "WhenHub Website" // "string"
},
"gridImageUrl": "https://whenhub.blob.core.windows.net/media/57c443f4e899ed5809ffc36e/100/whenhub.jpg", // "url"
"media": {
"type": "video", // "string" ("video", "image", "file", or "link")
"url": "https://www.youtube.com/watch?v=XXXXXXXXXXX", // url to file (only YouTube and Vimeo supported for video)
"name": "My Video", // "string"
"sources": [
"My video source" // "string"
],
"autoScaled": true, // boolean
"id": "5913405ac2c16d50a1c2982d5", // "string" media id
"eventId": "58dd665be45e4f9e34f0f987", // "string" associated event id
"createdAt": "2017-05-22T15:37:16.000Z", // Date (moment.js format)
"updatedAt": "2017-05-22T15:37:16.000Z", // Date (moment.js format)
"createdBy": "************************", // "string"
"updatedBy": "************************" // "string"
},
"when": {
"period": "minute", // "string" ("minute", "day", "month", or "year")
"relative": null, // "string" for timeshift
"startDate": "2017-05-17T21:22:28Z", // "string" (moment.js format)
"startTimezone": "America/New_York", // "string"
"endDate": "2017-05-18T21:22:28Z", // "string" (moment.js format)
"endTimezone": "America/New_York", // "string"
"recurrenceRule": null, // "string"
"recurrenceException": null // "string"
},
"createdAt": "2017-03-30T20:34:10.000Z", // Date (moment.js format)
"updatedAt": "2017-03-30T20:34:10.000Z", // Date (moment.js format)
"createdBy": "************************", // "string"
"updatedBy": "************************", // "string"
"scheduleId": "58dd665be45e4f9e34f0f987" // "string"
}Below is a sample of a simple and complex location object that is used within the Event Object.
// Simple location object
{
"name": "Home"
}
// Complete location object
{
"name": "Starbucks",
"locality": null,
"address": "3595 California Street",
"city": "San Francisco",
"postalCode": "94118",
"country": "United States",
"geolocation": {
"lat": 37.7861747,
"lng": -122.4531843
},
"region": "CA",
"telephone": null,
"timezone": "America/Los_Angeles",
"id": null,
"streetNumber": "3595",
"streetName": "California Street"
}"media": [
{
"type": "video",
"url": "https://vimeo.com/XXXXXXXXX",
"name": "",
"sources": [],
"id": "542302ac4c16d20a1c2932d4",
"eventId": "58dd6bc3e42e4f8e34f0f98c",
"createdAt": "2017-05-22T15:37:16.000Z",
"updatedAt": "2017-05-22T15:37:16.000Z",
"createdBy": "************************",
"updatedBy": "************************"
},
{
"type": "video",
"url": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
"name": "",
"sources": [],
"id": "542302ac4c16d20a1c2932d5",
"eventId": "58dd6bc3e42e4f8e34f0f98c",
"createdAt": "2017-05-22T15:37:16.000Z",
"updatedAt": "2017-05-22T15:37:16.000Z",
"createdBy": "************************",
"updatedBy": "************************"
},
{
"type": "file",
"url": "https://whenhub.blob.core.windows.net/media/542302ac4c16d20a1c2932d6/design-header.jpg",
"name": "",
"sources": [],
"id": "542302ac4c16d20a1c2932d6",
"eventId": "58dd6bc3e42e4f8e34f0f98c",
"createdAt": "2017-05-22T15:42:13.000Z",
"updatedAt": "2017-05-22T15:42:13.000Z",
"createdBy": "************************",
"updatedBy": "************************"
},
{
"type": "link",
"url": "http://www.whenhub.com",
"name": "Additional test link",
"sources": [
"My source"
],
"id": "542302ac4c16d20a1c2932d7",
"eventId": "58dd6bc3e42e4f8e34f0f98c",
"createdAt": "2017-05-22T15:37:16.000Z",
"updatedAt": "2017-05-22T15:47:39.000Z",
"createdBy": "************************",
"updatedBy": "************************"
},
{
"type": "image",
"url": "https://whenhub.blob.core.windows.net/media/542302ac4c16d20a1c2932d8/web-design-web-development.jpg",
"name": "Image Caption",
"autoScaled": true,
"sources": [
"Test Source"
],
"id": "542302ac4c16d20a1c2932d8",
"eventId": "58dd6bc3e42e4f8e34f0f98c",
"createdAt": "2017-05-22T15:42:35.000Z",
"updatedAt": "2017-05-22T21:33:21.000Z",
"createdBy": "************************",
"updatedBy": "************************"
}
]What's Next?
WhenHub API Reference
Updated 2 years ago