API Access and Documentation

Get Started
API Members
Examples
My API Key

Getting started with the Community Megaphone web service API is pretty straightforward, and requires only a few steps:

If you don't already have one, create a new account for accessing the web service. Note that you don't need an account to add events via the web site, only for the web service. Note also that you will not be able to log in or use the API until your account has been approved by the site administrator.
Click here to generate an email to notify us that you'd like API access.
Once you've created your account, and have been approved, you'll receive an email with your unique API key. Store this in a safe place. Your login credentials and API key (along with an event ID value you supply for each event) are what will allow you to access your events in Community Megaphone.
Add a reference in your development environment to the web service, and write the necessary code to access the API methods. See the API Members tab for an explanation of what each API method does, and the Examples tab for code examples for common operations.

If you are just looking for read-only access to the events that are currently in Community Megaphone, you have a couple of options (note that you do not need an account to access these feeds):

Use the RSS feed. It's filterable (it uses the same filters as the gadget, so you can head over to the gadget page, build your filters, and copy the querystring for use with the RSS feed).
Use the Community Megaphone Data Service. It is exposed via WCF Data Services, so it supports rich querying, paging, and more, with very little code.

There are three main web methods for dealing with events:

AddEvent (Key, CMEvent, ExceptionString) - takes three arguments:

Key - unique key for a given system. This is provided with the account credentials from the API page.
CMEvent - instance of the CMEvent class exposed by the web service, populated with appropriate data.
ExceptionString - Passed in by reference, will be returned with any errors produced during the operation.
Return value is a Boolean indicating success or failure of the operation.

Please note that if you omit the Latitude and Longitude values when adding an event, the lat/long will automatically be calculated when the event is added.

UpdateEvent (Key, CMEvent, ExceptionString) - takes three arguments:

Key - unique key for a given system. This is provided with the account credentials from the API page.
CMEvent - instance of the CMEvent class exposed by the web service, populated with appropriate data.
ExceptionString - Passed in by reference, will be returned with any errors produced during the operation.
Return value is a Boolean indicating success or failure of the operation.
UpdateEvent uses the combination of the unique key for the system, and the nativeID passed in when the event was created to allow updates to the event record. You can call GetEventByKeyID to return a CMEvent object containing the data for an existing event based on the unique key and nativeID values, in order to populate the CMEvent object prior to making updates.

DeleteEvent(Key, NativeEventID, ExceptionString) - takes three arguments:

Key - unique key for a given system. This is provided with the account credentials from the API page.
NativeEventID - ID of the event in your system, as passed in when the event was created in Community Megaphone.
ExceptionString - Passed in by reference, will be returned with any errors produced during the operation.
Return value is a Boolean indicating success or failure of the operation.

In addition to the main web methods, there are some additional helper methods I’ve provided:

GetEventByKeyID(Key, NativeID, ExceptionString) - takes three arguments:

Key - unique key for a given system. This is provided with the account credentials from the API page.
NativeID - ID of the event in your system, as passed in when the event was created in Community Megaphone.
ExceptionString - Passed in by reference, will be returned with any errors produced during the operation.
Return value is an object of type CMEvent with the current values for the event, if found.

GetAudiences() - returns an array of AudienceItem structures with the valid values for audienceID.
GetEventTypes() - Returns an array of EventTypeItem structures with the valid values for eventtypes.
GetStates() - Returns an array of StateItem structures with the valid values for state codes.
GetTimeZoneIDs() - Returns an array of TimeZoneItem structures with the valid values for TimeZoneIDs.

The CMEvent class, which is instantiated and passed to both the AddEvent and UpdateEvent web methods, has the following signature:

StartTime (datetime) - represents the starting date/time of the event. Required.
EndTime (datetime) - represents the ending date/time of the event. Required.
TimeZoneID (string) - ID representing the time zone in which the event will take place. Valid values can be obtained by calling GetTimeZoneIDs.
Title (string) - Title of the event. Max length is 500 characters, and title is required.
Description (string) - Event description/summary. Max length is 2000 characters. Optional.
EventUrl (string) - the URL for the event’s web site, registration, etc. Required.
EventType (string) - 2-character code representing the event type of the event. Supported values can be obtained by calling GetEventTypes.
AudienceID (integer array) - array of integers containing the audiences for the event. Valid values can be obtained by calling GetAudiences.
Address (string) - street address of the event. Max length is 100 characters. Required if the event type is an in-person event type (this can be determined by examining the properties on the EventTypeItem structure returned from GetEventTypes).
City (string) - city in which the event will take place. Max length 100 characters. Required if the event type is an in-person event type.
State (string) - state code representing the state in which the event will take place. Max length 2 characters. Either State or StateID is required if the event type is an in-person event type.
Zip (string) - 5- or 9-digit zip code for the event location. Required if the event type is an in-person event type. Digits only.
Latitude (decimal) - value describing the event location's latitude. This is optional. Please only include if you have high confidence in the value you are sending.
Longitude (decimal) - value describing the event location's longitude. This is optional. Please only include if you have high confidence in the value you are sending. For U.S., longitudes should be prefaced with a -
NativeID (string) - the native representation of the ID of the event being imported. Max length 100 characters.
PromoteViaMsdnFlash (Boolean) - optional - specifies that the event should appear in a report available to local evangelist for publishing in MSDN Flash.
PromoteViaLocalEvangelistBlog (Boolean) - optional - specifies that the event should appear in a report available to local evangelist for publishing in their blog.

Below, you'll find code examples for the most common operations on the Community Megaphone web service API:

Instantiating

Assuming a web service proxy name of CMEventManager, here's how you would instantiate the web service in Visual Basic:

Code:

Dim MyEvtMgr As CMEventManager.EventManager = New CMEventManager.EventManager()

Authenticating

Before calling certain web methods, you must first authenticate. Here's the syntax in VB:

Code:

Dim Auth As CMEventManager.SvcAuth
    
Auth = New CMEventManager.SvcAuth()
Auth.Username = "[Your Username]"
Auth.Password = "[Your Password]"

You should declare Auth such that it can be assigned to a property of your EventManager instance before calling AddEvent, UpdateEvent, or DeleteEvent.

Adding an Event

Here's the syntax for adding an event in VB. Note that you need to create and populate an instance of the CMEvent class to pass into the AddEvent web method, as shown:

Code:

Dim NewEvent As New CMEventManager.CMEvent

'Set CMEvent properties
With NewEvent
   .StartTime = [DateTime value]
   .EndTime = [DateTime value]
   .TimeZoneID = [supported TimeZoneID - get from GetTimeZoneIDs]
   .Title = [String value - max of 500 chars]
   .Description = [String value - max of 2000 chars]
   .EventUrl = [String value]
   .EventType = [supported EventType - get from GetEventTypes]
   .Address = [String value - max of 100 chars]
   .City = [String value - max of 100 chars]
   .State = [String value - max 2 chars get supported values from GetStates]
   .Zip = [String value - either 5 or 9 chars, numeric only]
   .Latitude = [Decimal value]
   .Longitude = [Decimal value]
   .AudienceID = [Integer array - get supported values from GetAudiences]
   .NativeID = [String - internal representation of event ID on your system]
   .PromoteViaMsdnFlash = [Boolean indicating whether to include in MSDN Flash]
   .PromoteViaLocalEvangelistBlog [Boolean indicating whether to blog event]
End With

Dim ExceptionString As String = ""
Dim Success As Boolean = False
Dim Key As String = "[Your API Key]"

MyEvtMgr.SvcAuthValue = Auth
Success = MyEvtMgr.AddEvent(Key, NewEvent, ExceptionString)

If Not Success Then
   MessageBox.Show(ExceptionString, "Errors Occurred")
Else
   MessageBox.Show("Event Added.", "Success!")
End If

Here's the syntax for adding an event in VB. Note that you need to create and populate an instance of the CMEvent class to pass into the AddEvent web method (for existing events you can call GetEventByKeyID to pre-populate with existing data), as shown:

Code:

Dim NewEvent As CMEventManager.CMEvent
Dim ExceptionString As String = ""

NewEvent = _
    CMEventManager.GetEventByKeyID("[Your API Key]", _
    "[Your Native Event ID]", ExceptionString)

'optionally add code to check for any 
'exceptions in retrieving the existing event

'Update Event start and end times
With NewEvent
   .StartTime = [DateTime value]
   .EndTime = [DateTime value]
End With

Dim Success As Boolean = False
Dim Key As String = "[Your API Key]"

MyEvtMgr.SvcAuthValue = Auth
Success = MyEvtMgr.UpdateEvent(Key, NewEvent, ExceptionString)

If Not Success Then
   MessageBox.Show(ExceptionString, "Errors Occurred")
Else
   MessageBox.Show("Event Updated.", "Success!")
End If

Deleting an Event

Here's the syntax for deleting an event in VB:

Code:

Dim Success As Boolean = False
Dim Key As String = "[Your API Key]"

MyEvtMgr.SvcAuthValue = Auth
Success = MyEvtMgr.DeleteEvent(Key, "[Your Native Event ID]", ExceptionString)

If Not Success Then
   MessageBox.Show(ExceptionString, "Errors Occurred")
Else
   MessageBox.Show("Event Deleted.", "Success!")
End If

Binding to a Lookup Method

Using the lookup methods exposed by the web service API, you can easily bind a drop-down in your page to the currently valid values for event types, timezones, and state codes. The markup below shows an example of using an ASP.NET ObjectDataSource control to databind a DropDownList control to display the supported timezones:

Code:

<asp:ObjectDataSource ID="TimeZoneDS" runat="server" 
   SelectMethod="GetTimeZoneIDs" TypeName="CMEventManager.EventManager">
</asp:ObjectDataSource>
<asp:DropDownList ID="TimeZoneDDL" runat="server" 
    DataSourceID="TimeZoneDS" DataTextField="Name" DataValueField="ID">
</asp:DropDownList>

Demo:

Using this technique allows you to ensure the values you provide to Community Megaphone are valid and include any new event types, timezones, etc. that may be added in the future.

Your API Key

User is not an approved API user.

Community Megaphone (RSS )

Code Camps & Roadshows & Webcasts, oh my!

Instantiating

Code:

Authenticating

Code:

Adding an Event

Code:

Updating an Event

Code:

Deleting an Event

Code:

Binding to a Lookup Method

Code:

Demo:

Your API Key