WhenHub

Welcome to the WhenHub Developer Platform

Here, you'll find comprehensive guides and documentation to help you start working with WhenHub as quickly as possible, as well as support if you get stuck. Let's jump right in!

If you are new to WhenHub, please take a moment to learn more.

Build VisualizationsVisualizations

Create interesting interactive visualizations for Whencasts.

Get Started

Use the WhenHub APIWhenHub API

Programmatically interact with the WhenHub platform.

Get Started
WhenHub Developer Platform

Understanding the Event Object

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:

Try it out!

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.

Event Object Parameters

Name
Description
Read Only(?)

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.

Event Object Sample

{
  "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"
}

Location Object Sample

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 Object Sample

"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