IoT Calendar Service

Note: The IoT Calendar service is currently a beta product. We are continuing to improve the service but you may experience some hiccups while we iron out the kinks.

The Internet of Things (IoT) has brought about the ability for many non-traditional devices to access the internet. Digital assistants, smart buttons, even kitchen appliances can connect to the internet. These devices are typically smaller, low-powered devices with more limited computational capacities than PCs and smart phones. Parsing calendar data can be too computationally complex for these devices. The IoT Calendar Service from iCalendar.org allows these devices to retrieve calendar data that would otherwise be impossible for a small device to handle. Two services are available with the IoT Calendar Service:

  • iotevents - Retrieve a list of events for the current day or specified days in JSON format.
  • iottzoffset - Retrieve the timezone offset of the current time for a specified timezone in JSON format. Typically used when retrieving time information from an NTP (Network Time Protocol) server, this service takes into account Daylight Savings Time (DST).

More details of these services are described below.

iotevents Service

The iotevents service displays the events for a day in JSON format from an iCalendar stream. The service takes the following into account when determining the day's events:

  • Search for events for the specified day
  • Expand all repeating events to see if they fall on the specified day
  • Check for exceptions where events have been cancelled or rescheduled.
  • Show the event in the timezone as specified in the iCalendar stream

 An API key is required to use this service. A free API key is available and can be obtained by creating an account at iotcalendar.org . The free key allows checking for calendar events an average of once per day.

To retrieve the events for the current day, the IoT device sends a URL to the service in the following format:

http[s]://iotcalendar.org/iotevents?apikey={apikey}&tzoffset={tzoffset}&url={url}

where:

  • {apikey} = The API key created when creating an account at iotcalendar.org. Check the subscription page for your API key.
  • {tzoffset} = The timezone that matches the timezone in the iCalendar file. The service ignores the VTIMEZONE definition in an iCalendar stream and instead relies on the name and definition the tz database, which is used in PHP. Valid PHP timezone names can be found on the page http://php.net/manual/en/timezones.php . Some streams include timezone names in the DTSTART and DTEND tags that are not in the tz database (notably in Outlook). These have been aliased to the appropriate tz database name as they have been found. Please send a message using the "Contact Us" link above if you find a timezone name is not supported.
  • {url} = This is the URL of the calendar stream. If the URL represents a subscription, then subsequent checks will include updated calendar information.

Other options include:

  • days={days} - display events for the specified day. This is a specific day formatted either as an absolute date "YYYYMMDD" or as a relative date. A relative date is relative to today, so days=0 (the default) represents today, day=1 represents tomorrow, day=-1 represents yesterday, etc. You can specify more than one date using a comma separated list, or a day range using a semi-colon. For example, a day range of 0:2 will match events occuring today, tomorrow and the next day. Up to 60 dates can be specified, however, the size option will limit how many events are returned.
  • mtime - show timestart in military format (i.e. "13" instead of "1p"). Add "&mtime" to the URL.
  • pretty - format the JSON results in a pretty way for debugging purposes. Add "&pretty" to the URL.
  • rdays={rdays} - (Deprecated, use days instead) display events for the specified day. This day is relative to today, so rdays=0 (the default) represents today's events, rday=1 represents tomorrow's events, rday=-1 represents yesterday's events, etc. You can specify more than one day using a comma separated list, however, 3 days at most are allowed (for rdays and days options combined). This option is deprecated, use days option instead.
  • size={size} - return at most {size} events, to reduce the amount of memory a device may need to process the JSON string. If not specified, a maximum of 10 events is returned.

"http" and "https" URLs are supported, however, "https" is preferred if the IoT device supports it (some do not). The service will return a JSON formated return stream. Here is an example:

{
    "events": [
        {
            "summary": "Work Anniversary ",
            "ldstart": "20190124",
            "ldend": "20190124",
            "duration": 1440,
            "rday": 0,
            "allday": 1
        },
        {
            "summary": "Teacher Appointment",
            "ldstart": "20190124",
            "ldend": "20190124", 
            "duration": 30,
            "rday": 0,
            "allday": 0,
            "timestart": "10:30a"
        },
        {
            "summary": "Project Status Meeting",
            "ldstart": "20190124",
            "ldend": "20190124",
            "duration": 60,
            "rday": 0,
            "allday": 0,
            "timestart": "3p"
        }
    ]
}

The following event fields are returned for each event:

  • summary - The title of the event
  • ldstart - The start date of the event in the local timezone. The format is YYYYMMDD
  • ldend - The end date of the event in the local timezone. The format is YYYYMMDD
  • duration - The length of the event in minutes
  • rday - day of the event relative to today (zero  = today)
  • allday - set to 1 if it is an all day event
  • timestart - string representation of the meeting start time.

Errors and warnings may also be returned under "errors" and "warnings", respectively. Here is an example of an error response:

{
    "events": [],
    "errors": [
        "No URL specified"
    ]
}

 

iottzoffset Service

The iottzoffset service was created by the need to determine the appropriate timezone difference when retrieving the time from an NTP (Network Time Protocol) server. The NTP protocol returns the current time in the UTC timezone.

The syntax for using  the iottzoffset service is:

http[s]://iotcalendar.org/iottzoffset/?apikey={apikey}&tzid={tzid}

where:

  • {apikey} = The API key created when creating an account at iotcalendar.org. Check the subscription page for your API key.
  • {tzoffset} = The timezone as defined in PHP. Valid PHP timezone names can be found on the page http://php.net/manual/en/timezones.php

For example,

https://iotcalendar.org/iottzoffset/?apikey=1234-1234-1234&tzid=America/New_York

Options include:

  • pretty - format the JSON results in a pretty way for debugging purposes. Add "&pretty" to URL.

"http" and "https" URLs are supported, however, "https" is preferred if the IoT device supports it (some do not). For this example, the iottzoffset service returns the current timezone offset for the New York timezone in JSON format, as in the following:

{
    "offset": -300
}

"offset" is in minutes from the UTC timezone.  This value will vary during the year depending when Daylight Savings TIme (DST) is in effect.

Errors and warnings may also be returned under "errors" and "warnings", respectively. Here is an example of an error response when the tzid value is misspelled (missing underscore character):

{
    "errors": [
        "Invalid tzid specified (America\/NewYork)"
    ]
}