InstantCal API:
InstantCal is configured using a very simple API (Application Programming Interface). Default configuration values are generated when you Create an Event Calendar. The configuration values may be changed to control the appearance and behaviour of InstantCal in detail.
The InstantCal API is described in the following sections:
 
1. Setup
Setup describes how to embed InstantCal in a web page.
 
2. API Overview
The InstantCal API is defined by a URI and a set of options in the HTML embed code of the InstantCal Setup.

The URI is:

http://cdn.instantcal.com/cvir.html?
 
Each option has a name and a value and is specified by a 'name=value' pair.
Multiple options are separated by an ampersand ('&').
 
Example: Calendar with a color scheme (theme) of gray-gradient (xgy) and a display format (gtype) of month (cv_monthGrid)

The URI and options:
http://cdn.instantcal.com/cvir.html?theme=xgy&file=http://instantcal.com/categories.ics&gtype=cv_monthGrid
are used in the following HTML embed code:
<iframe src='http://cdn.instantcal.com/cvir.html?theme=xgy&file=http://instantcal.com/categories.ics&gtype=cv_monthGrid' allowTransparency=1 scrolling='no' frameborder=0 height=600 width=600></iframe>
Note that the dimensions of the calendar (in pixels) are defined by the IFrame settings height=600 and width=600.
IFrame transparency is also enabled so that any background from the web page is displayed in areas not covered by the calendar.
 
3. Calendar Data Sources
Calendar data may exist in many formats (e.g. iCal, RSS).
Regardless of the format, the source (or sources) of calendar data are always specified by the file option, which has a URI as its value. The URI may contain information about the calendar data format.
The following calendar data formats are supported:
  • iCal - an iCalendar file
  • Webcal - a webcal calendar
  • RSS - an RSS feed
  • Twitter - a Twitter feed
API Data Options
Description Name Value
iCalfilehttp://...iCal file...
Webcalfilewebcal://...Webcal file...
RSSfilehttp://...RSS feed...
Twitterfilehttp://twitter.com/...?file=...&dtype=twitter
iCal format is the standard for specifying calendar data. This format is available from most web-based calendar services.
Webcal is an alternate 'scheme' for accessing iCal format data. Some web-based calendar services export calendar data using webcal.
RSS is associated with newsfeeds and blogs. These data streams frequently contain dated information that may be represented in calendar formats. InstantCal automatically translates RSS into a calendar format.
Twitter feeds in RSS or JSON format may be automatically translated into a calendar format.
Note: more than one file option may be used to 'overlay' the display of multiple calendars.
 
4. Display
 
A) Organization
Calendars are organized in one of two ways:
  • Navigated (navigate -> group -> item)
  • Grouped (group -> item)
The Navigated organization has three levels of display; navigation (ntype option), group (gtype option), and item. The navigation display allows a date to be selected, and a group of calendar events displayed. The group display shows a group of calendar events. No group is displayed if the group is empty ('gtype='). The item display shows a single calendar event in detail.
The Grouped organization has two two levels of display; group (gtype option), and item. The group display shows a group of calendar events. No group is displayed if the group is empty ('gtype='). The item display shows a single calendar event in detail.
The calendar organization is not set directly, but is controlled by the display formats described below.
 
B) Display Formats
The calendar display formats are listed in the table below.
Visual effects (described later) may be set for display formats having values in the 'Effects' column. Visual effects include scroll, slide, fade, or rotate.
API Display Options (navigation/group/item)
Description Name Value Effects
Date picker (month)ntypecv_datepicker
Date picker (quarter)ntypecv_datepicker3
Date picker (semi-annual)ntypecv_datepicker6
Date picker (annual)ntypecv_datepicker12
Monthgtypecv_monthGrid
Daygtypecv_dayGrid
3 Daygtypecv_dayGrid3
5 Daygtypecv_dayGrid5
7 Daygtypecv_dayGrid7
Multi-view (month/day/list)gtypecv_multiView
Previewgtypecv_simpleLists, l, f, r
List - Summarygtypecv_listSummarys, l, f, r
Labeled List - Summarygtypecv_labeledListSummarys, l, f, r
Labeled List Long - Summarygtypecv_labeledListSummaryLongs, l, f, r
Tablegtypecv_listTables, l, f, r
Ticker (one-liner)gtypecv_oneLiners, l, f, r
 
Sub-formats (Month)
API Display Options (month sub-format)
Description Name Value
Wrapgwrap0 or 1, display multi-line event summary (default: 0)
Bordergeborder0 or 1, hide event border (default: 1)
Timeetimes0 or 1, event time in event summary (default: 0)
 
Sub-formats (List-style)
A period and subperiod may be set for list-style display formats (cv_simpleList, cv_listSummary, cv_labeledListSummary, cv_labeledListSummaryLong, cv_listTable).
The period specifies the length of time over which a screen of events is displayed.
The subperiod further limits events displayed to either a single event (gsubperiod=event) or future events only (gsubperiod=upcoming).
API Display Options (list sub-format)
Description Name Value
Periodgperiodyear, month, week, day
Subperiodgsubperiodevent, upcoming
Dategehdate0 or 1, display day for events (1: default)
Timegehtime0 or 1, display in-line event time (1: default)
 
C) Visual Effects
Some display formats support the special visual effects scroll, slide, fade, rotate, and ticker.
Scrolling may be vertical (like a television program listing) or horizontal (like a stock ticker).
Sliding is a special form of scrolling where the scroll options are set to simulate a 'sliding door' (e.g. gspausen=0&gspaused=3000&gsrate=2000).
Fading in and out is an alternative way to update the display. Slow fades are are less obtrusive; rapid fades provide faster updates.
Rotation is a special form of fading where the fade time (or 'rotate time') is short for fast fade-in/fade-out (e.g. gfnext=10). This simulates a slide show.
Note: Ticker (or crawler) is a one-line display with horizontal scroll.
API Display Options (visual effects)
Description Name Value
Scrollgeffectscroller
- directiongsdirleft, right, up, down
- loopsgsloopsnumber of cycles before stopping
- scroll rategsratescrolling movement interval (in milliseconds)
- pause durationgspausedlength of periodic pauses while scrolling (in milliseconds)
- pause intervalgspausentime until next pause while scrolling (in milliseconds)
Slidegeffectscroller
- directiongsdirleft, right, up, down
- loopsgsloopsnumber of cycles before stopping
- scroll rategsratesliding movement interval (in milliseconds)
- pause durationgspausedlength of periodic pauses while sliding (in milliseconds)
- pause intervalgspausentime until next pause while sliding (in milliseconds, usually 0)
Fade-in/fade-outgeffectfader
- loopsgfloopsnumber of cycles before stopping
- fade timegfnextfade cycle time (in milliseconds)
- pause durationgfpausedlength of pause when faded-in (in milliseconds)
Rotategeffectfader
- loopsgfloopsnumber of cycles before stopping
- rotate timegfnextrotate cycle time (in milliseconds)
- pause durationgfpausedlength of pause while displayed (in milliseconds)
- rotate rangegfrangeperiod of events covered by rotation cycle(month, week)
 
D) Color Scheme (Theme)
General color appearance of the navigated, grouped, and item displays may be set by the theme option. Several pre-defined themes are available in blend or flat colors. Or, a custom monotone color may be selected.
API Display Options (color scheme)
Description Name Value
Graythemexgy
Redthemexre
Bluethemexbl
Yellowthemexye
Greenthemexgr
Gray (flat)themegy
Red (flat)themere
Blue (flat)themebl
Yellow (flat)themeye
Green (flat)themegr
Custom colortheme6-digit hex code (e.g. aa40cc)
Custom background colorbcolor 6-digit hex code (e.g. aa40cc)
Note: requires Custom color
 
E) Additional options
The appearance of each display may be further controlled by setting additional options. These options may depend on the type of display, according to the tables below.
API Display Options (general)
Description Name Value
Rounded cornersborder_radiusnumber of pixels for rounding (e.g. 5)
Calendar colorccolor6-digit hex code (e.g. red=ff0000, green=00ff00)
Calendar namecnameName of calendar
Event bordergeborder0 or 1, hide event border (default: 1)
Event categoriesccategoryCategory name(s)
Event category colorccategory_color6-digit hex code (e.g. red=ff0000)
Event categories selectedccategory_selDefault Category name(s) selected
Event day list orderdateorder0, late-to-early; 1, early-to-late (default)
Event time list ordertimeorder0, late-to-early; 1, early-to-late (default)
Day/Month display orderddmm1, mmdd; 0, ddmm (default)
Start day-of-weekwkstDay-of-week (e.g. Mon or 1) [month grid only]
Map Servicemapgoogle (Google Maps) or yahoo (Yahoo Maps, default)
24-hour timetime240 or 1, display event times in 24-hour format
Timezonetimezone_defArea/Location (e.g. America/New_York)
Show non-floating times in this timezone.
Reference: Wikipedia ZoneInfo
 
API Display Options (navigation-specific)
Description Name Value
Navigation day active colorn_activecolor6-digit hex code (e.g. red=ff0000)
Navigation font sizen_font_sizefont size, in pixels (e.g. 12px)
Navigation paddingn_paddingday cell padding, in pixels (e.g. 2px)
Note: Display sizes may be set in pixels or percentages.
When set in pixels, a 'px' suffix must be used (e.g. '200px').
When set in percentages, no suffix is used (e.g '100' means '100 percent').
 
5. Viewer Controls
InstantCal viewers may be given permission to customize calendars, if certain options are used in the HTML embed code.
If event category options are specified, a set of categories (defined by 'ccategory' parameters) is displayed.
If timezone options are specified, a menu of timezones is displayed (see Timezones for details)
API Viewer Control Options
Description Name Value
Event category selectorccategory_typeselect (pull-down menu) or checkbox
Timezone typetimezone_typeselect (pull-down menu)