API Overview

Account Settings

Within local Helios Calendar accounts are users' unique API settings for access to that calendar's API.

• API Endpoint - The URL where users access the calendar's API. (Documentation examples use the Helios Calendar Demo.)
• Username - Username for the calendar.
• Key - API Key for the calendar.

API Key can be reset by checking the Regenerate API Key when saving account settings.

Note: Username for a given calendar account will depend on which account type the user signs in with (Facebook, Twitter or Google).

Authentication

To read data from the API users are required to authenticate their request using their username and api key.

Sample Request

http://demo.helioscalendar.com/api/?u=YOUR_USERNAME&k=YOUR_KEY

Methods

The API currently supports the following methods.

Events

• Current Events - events_c
• Billboard Events - events_b
• Popular Events - events_p
• New Events - events_n

Categories

• Hierarchical - categories_h
• Alphabetical - categories_a
• Event Count - categories_e

Newsletters

• Recent (Newest First) - newsletters_c
• Most Popular - newsletters_p

Response Header

Due to potential variations in version (or customization) of the API in use from one Helios Calendar to another each API response includes a summary header containing relevant information about the calendar providing the response. This information is provided to permit API developers to account for variations that may arise.

• version - Version of the API in use on the calendar.
• cal_url - Full URL of the public calendar.
• encoding - Character set in use on the calendar (and API).
• generated - Timestamp (ISO 8601) when the response data was generated. Calendar's using one of the API cache options will contain the timestamp when the cache was last rebuilt.
• contents - Description of the response contents (events/categories/error/etc.).

Errors

If an API call results in something other then a valid returned dataset a detailed error response will be provided.

Sample Response

{
   "api":{
      "version":"1.0",
      "cal_url":"URL",
      "encoding":"CHARACTER_SET",
      "generated":"ISO_8601_TIMESTAMP",
      "contents":"RESPONSE_DESC"
   },
   "error":{
      "error_id":"ERROR_ID",
      "msg":"ERROR_MESSAGE",
      "help":"HELP_MESSAGE"
   }
}

API Changelog

• Version 1.0