API.Events

This part of the API is used to search for events matching a set of filters. The starting point for all requests should be one of the URL's below.
http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj
http://api.activecalendar.com/json/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj

Basic Filtering

The URLS's above (once actual tokens and secrets are added) will pull back a weeks worth of event data from the calendar. The parameters below allow for pulling back events matching the exact criteria specified.
  • StartRange
    • Optional with a default, date (yyyy-mm-dd)
      If this value is omitted, this filter will default to today.
  • EndRange
    • Optional with a default, date, (yyyy-mm-dd)
      If this value is omitted, this filter will default to 7 days from today.
      If this value is before the StartRange, this filter will default to 7 days after the StartRange.
      The StartRange and EndRange are special in that they work together to find matching data. Events that are taking place anytime during the range supplied will be returned. There is no native method to return events starting after a specific date or coming before a spefic date.
      The following API request would find all events that are taking place between January 1-23, 2014.
      http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&StartRange=2014-01-01&EndRange=2014-01-23
      The following API request would find all events that are taking place between today and 7 days from today.
      http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj
  • Private
    • Optional, Y/N
      If "Y", only private events will be returned.
      If "N", only public events will be returned.
      If omitted, public and private events will be returned.
      http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&Private=Y
      http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&Private=N
  • Highlighted
    • Optional, Y/N
      If "Y", only highlighted events will be returned.
      If "N", only non-highlighted events will be returned.
      If omitted, highlighted and non-highlighted events will be returned.
      http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&Highlighted=Y
      http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&Highlighted=N
  • Keywords
    • Optional, Text
      This value allows searching event data by a keyword. The event name, description, summary and keywords are included in the search.
      http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&Keywords=entertainment
  • Categories
    • Optional, Comma delimited list of Guids
      This value allows for searching for events based on their classification.
      http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&Categories=60EAD9BB-067C-460E-89D8-988635AB06D3,D47B0C32-56EE-44E1-8F11-3FC4610C9430
  • Locations
    • Optional, Comma delimited list of Guids
      This value allows for searching for events based on their location.
      http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&Locations=513CB2BB-8741-48AC-AC68-32D37FDC07DD,F1F169ED-0D72-48FE-ABAA-96BAE4F8580C

Advanced Filtering

The basic filters can be used in any order and combination to find the exact set of events needed.
  • The API request to pull back events that are highlighted and public would look like the following.
    http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&Highlighted=Y&Private=N
  • The API request to pull back events that are highlighted, public and in specific categories would look like the following.
    http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&Highlighted=Y&Private=N&Categories=60EAD9BB-067C-460E-89D8-988635AB06D3,D47B0C32-56EE-44E1-8F11-3FC4610C9430
  • The API request to pull back events that are highlighted, public, specific categories that fall between January 1-23, 2014 would look like the following.
    http://api.activecalendar.com/xml/events/?token=ZDDE...cGI0&secret=OWNT...Z5Nj&Highlighted=Y&Private=N&Categories=60EAD9BB-067C-460E-89D8-988635AB06D3,D47B0C32-56EE-44E1-8F11-3FC4610C9430&StartRange=2014-01-01&EndRange=2014-01-23

Event Lookup API

This part of the API is used to lookup a single event. The starting point for all requests should be one of the URL's below.
http://api.activecalendar.com/xml/event/event-route-param/?token=ZDDE...cGI0&secret=OWNT...Z5Nj
http://api.activecalendar.com/json/event/event-route-param/?token=ZDDE...cGI0&secret=OWNT...Z5Nj

Find One Event

The URLS's above (once actual tokens and secrets are added) will pull back a single events information. There is a single value needed in the API request to get all the details associated to a single event.
  • event-route-param
    • Required, alpha-numeric with dashes
      A route might look like any of the following strings and be up to 265 characters long.
      • my-event-route
      • my-event-route-1
      • my-event----route
      • 1-my-event-route
      The API request for a single event that had the event-route-param of "my-event-route" would look like the following.
      http://api.activecalendar.com/xml/event/my-event-route/?token=ZDDE...cGI0&secret=OWNT...Z5Nj

Event Add API

This part of the API is used to add events to a site. The starting point for all requests should be one of the URL's below.
http://api.activecalendar.com/xml/event/add/?token=ZDDE...cGI0&secret=OWNT...Z5Nj
http://api.activecalendar.com/json/event/add/?token=ZDDE...cGI0&secret=OWNT...Z5Nj

Add An Event

The fields below are required for all events added using the API.
  • Event Name
  • Event Description
  • Event Text Only Summary
  • Local Start Date/Time
  • Local End Date/Time
All other event fields besides the ones shown above can be omitted from the XML or key/value pairs when adding events.

Add An Event Using XML

The XML below shows all nodes and constraints for the data that can be used used when adding an event. An XML block containing the event information must be sent to the API as body of the request (as show in the next section).
  • <events>
    • <event>
      • <name> 255 character event title </name>
      • <description> unlimited length event description </description>
      • <summary> 255 character text only event summary </summary>
      • <keywords> 4000 character comma delimited list of keywords </keywords>
      • <timezone-id> Windows Timezone Identifier </timezone-id>
      • <local-start-date-time> LOCAL yyyy-mm-dd , LOCAL yyyy-mm-dd hh:mm </local-start-date-time>
      • <local-end-date-time> LOCAL yyyy-mm-dd , LOCAL yyyy-mm-dd hh:mm </local-end-date-time>
      • <all-day> True, False </all-day>
      • <private> True, False </private>
      • <highlighted> True, False </highlighted>
      • <contact>
        • <name> 255 character contact name </name>
        • <email> 255 character contact email </email>
        • <phone> 100 character phone number </phone>
        • <extension> 100 character contact phone extension </extension>
        </contact>
      • <categories>
        • <category>
          • <id> GUID of category to link </id>
          </category>
        </categories>
      • <locations>
        • <location>
          • <id> GUID of location to link </id>
          </location>
        </locations>
      • <images>
        • <image>
          • <name> 255 character file name </name>
          • <content-type> 255 character content type </content-type>
          • <alt-text> 255 character alternate text </alt-text>
          • <data> Base 64 encoded image </data>
          </image>
        </images>
      • <attachments>
        • <attachment>
          • <name> 255 character file name </name>
          • <content-type> 255 character content type </content-type>
          • <alt-text> 255 character alternate text </alt-text>
          • <data> Base 64 encoded image </data>
          </attachment>
        </attachments>
    • </event>
  • </events>
The code below shows how to make an API call using C# to add an event using XML.
//Setup the API request
String Token = "MzgwZGE.....Y2MTVjZGFhYTU3";
String Secret = "ZjU3OThlZGY.....zOGZhNGEw";
String APIRequestUrl = String.Format("http://api.activecalendar.com/xml/event/add/?token={0}&secret={1}", Token, Secret);

//Holds the API response
Byte[] APIResponse = null;

using (WebClient client = new WebClient())
{
//Set the content type being sent to the server
client.Headers.Add(HttpRequestHeader.ContentType, "text/xml");

using (MemoryStream stream = new MemoryStream())
{
using (XmlWriter writer = XmlWriter.Create(stream, new XmlWriterSettings() { CloseOutput = false }))
{
//Open events and event container nodes
writer.WriteStartElement("events");
writer.WriteStartElement("event");

//Write nodes of event data
writer.WriteElementString("name", "Event Name");
writer.WriteElementString("summary", "Event Summary");
writer.WriteElementString("description", "Event Description");
writer.WriteElementString("local-start-date-time", "2014-10-29 15:30");
writer.WriteElementString("local-end-date-time", "2014-10-29 16:30");

//Close event and events container nodes
writer.WriteEndElement();
writer.WriteEndElement();
}

//Send the content to the server
APIResponse = client.UploadData(APIRequestUrl, stream.ToArray());
}
}

//At this point APIResponse holds the response from the server

Add And Event Using Key/Value Pairs

  • Key: Name, 255 character event title
  • Key: Description, unlimited length event description
  • Key: Summary, 255 character text only event summary
  • Key: Keywords, 4000 character comma delimited list of keywords
  • Key: TimeZone, Windows Timezone Identifier
  • Key: StartDate, LOCAL yyyy-mm-dd , LOCAL yyyy-mm-dd hh:mm
  • Key: EndDate, LOCAL yyyy-mm-dd , LOCAL yyyy-mm-dd hh:mm
  • Key: AllDay, True, False
  • Key: Private, True, False
  • Key: Highlighted, True, False
  • Key: Contact_Name, 255 character contact name
  • Key: Contact_Email, 255 character contact email
  • Key: Contact_Phone, 100 character phone number
  • Key: Contact_Extension, 100 character contact phone extension
  • Key: Categories, GUID of category to link
  • Key: Locations, GUID of location to link
Using the key-value method, an event can be added using a browser and query string parameters as show in the URL below. Once all the URL parts once joined together to form a single URL a browser could be used to add an event to a site.
  • http://localhost:22221/xml/event/add/
  • ?token=ZDDE...cGI0&secret=OWNT...Z5Nj
  • &Name=KVP+Event+Name
  • &Description=KVP+Event+Description
  • &Summary=KVP+Event+Summary
  • &StartDate=2014-11-16+8%3a00
  • &EndDate=2014-11-16+9%3a00
http://localhost:22221/xml/event/add/?token=ZDDE...cGI0&secret=OWNT...Z5Nj &Name=KVP+Event+Name&Description=KVP+Event+Description&Summary=KVP+Event+Summary&StartDate=2014-11-16+8%3a00&EndDate=2014-11-16+9%3a00