COVERITLIVE API - EVENT/LIST (V. 2.0)

The Request

This method provides data of all upcoming, live and completed events accessible by a user. This includes the user's own events, as well as any events that are part of Groups or Enterprise Accounts that the user belongs to. By default, the event/list request only returns events that belong to the user. To request events that belong to an Enterprise Account or Group, one of the account or group parameters must be included in the request.

URL:
https://api.coveritlive.com/remote/2/event/list
Response Format:
JSON
HTTP Method(s):
GET
API Rate Limited:
false
In addition to the parameters listed in the Request Parameters section, the event/list method also includes the following parameters:

Parameter Description Required
status

A pipe (|) delimited list of event types to retrieve. Possible values include:

upcoming - events that haven't started

live - events currently live

finished - completed events

 yes
event_code The event code at which you want to start receiving events. The event code is unique and is provided in the data for any event returned. If it's not included, it will default to the earliest possible event (by creation date). no
event_count Controls the number of events that are returned. If no value is provided, the last 500 matching events will be returned in ascending order of creation date. Set event count to an integer less than 500 to limit the number of items returned. If this value is set to an integer greater than 500, only the last 500 matching items will be returned.

If the event_code parameter is also included in the request, the event_count items directly after the event with event_code will be returned. Set event_count to a negative value to return the event_count items directly before the item with item_id. For example:

Retrieve 10 oldest events - set event_count to 10 (event_count=10)

Retrieve 10 most recent events - set event_count to -10 (event_count=-10)

Retrieve 10 events that are NEWER than event with code XXX - set event_code to XXX and event_count to 10 (event_code=XXX&event_count=10)

Retrieve 10 events that are OLDER than event with code XXX - set event_code to XXX and event_count to -10 (event_code=XXX&event_count=-10)

 no
account The account code for which you want to retrieve events. If this parameter is provided, the group parameter should not be. If the user belongs to an Enterprise Account, this code is available on the APIs and Event Feeds page. Omit this parameter and the group parameter to retrieve events that belong to the user only. no
group The group code for which you want to retrieve events. If this parameter is provided, the account parameter should not be. If the user belongs to any Groups, the codes for them are available on the APIs and Event Feeds page. Omit this parameter and the account parameter to retrieve events that belong to the user only. no

Example #1 - Retrieve all events for User


https://api.coveritlive.com/remote/2/event/list?
token=05c413a1242b409fa91f574cea05072b
&status=upcoming%7clive%7cfinished

Explanation

  • the token value identifies the user making the request.
  • the status value (upcoming%7clive%7cfinished) is the url-encoded representation of: upcoming|live|finished

Example #2 - Retrieve all events for an Enterprise Account

Assuming you want to retrieve all events for the Enterprise Account: BigPaper124


https://api.coveritlive.com/remote/2/event/list?
token=05c413a1242b409fa91f574cea05072b
&account=BigPaper124
&status=upcoming%7clive%7cfinished

Explanation

  • the account value (BigPaper124) is the Account Code of the account whose events you would like to retrieve
  • the token value ensures that the calling user has access to the events in the Account.
  • the status value (upcoming%7clive%7cfinished) is the url-encoded representation of: upcoming|live|finished

Example #3 - Retrieve only live events for your Group

Assuming you want to retrieve a list of live events for the group: SportsChat


https://api.coveritlive.com/remote/2/event/list?
token=05c413a1242b409fa91f574cea05072b
&group=SportsChat
&status=live

Explanation

  • the group value (SportsChat) is the group for which you want to retrieve all events
  • the token value ensures that the calling user has access to the events in the group.
  • the status value (live) is the url-encoded representation of: live

The Response

The event listing data is returned in the data field of a general response. This field will consist of an array of event objects.

Event objects have the following fields:

Field Name Field Value(s) Explanation
code {string} Event Code - a unique code that identifies the event.
title {string} Event Title - the title of the event.
status {string} Status of the event, one of the following:
upcoming
live
finished
group {string} Pipe-delimited list of Group names that the event is a member of. Empty if none.
group_code {string} Pipe-delimited list of unique Group codes corresponding to the entries in the <group> element.
user_name {string} Name associated with the account that created the event.
user_id {int} User ID of the creator of the event (may be required to make specific event data item requests).
host_nickname {string} The name of the event host as it appears in event chat messages.
host_avatar {string} URL of the avatar of the event host - blank if not provided.
is_ticker {string} Indicates whether the event is a ticker. Will be 'y' if the event is a ticker, and 'n' otherwise.
scheduled_starttime {int} Date and time event was scheduled to start. Value is integer representing seconds since Unix Epoch (January 1 1970 00:00:00) GMT timezone.
start_timestamp {int} Date and time event started - empty if status is upcoming. Value is integer representing seconds since Unix Epoch (January 1 1970 00:00:00) GMT timezone.
end_timestamp {int} Date and time event ended - empty if status is upcoming or live. Value is integer representing seconds since Unix Epoch (January 1 1970 00:00:00) GMT timezone
metadataList {Array} This field may contain an array of metadataItem objects.

The metadataList field of the event object may contain an array of metadataItem objects.

metadataItem objects have the following fields:

Field Name Field Value(s) Explanation
attribute {string} Metadata attribute as defined in event setup
value {string} Metadata value for attribute as defined in event setup

Example response to a successful event/list request:


{
    "result":"success",
    "type":"event",
    "action":"list",
    "version":2,
    "data":[
        {
            "code":"828751195d",
            "title":"Test Ticker",
            "status":"live",
            "group":"Group1",
            "group_code":"groupcode001",
            "user_name":"John Smith",
            "user_id":"17630",
            "host_nickname":"Johnny Boy",
            "host_avatar":null,
            "is_ticker":"y",
            "scheduled_starttime":"-62169922800",
            "start_timestamp":"1302110319",
            "end_timestamp":"-62169962400"
        },
        {
            "code":"f94d14c9c3",
            "title":"Test API Event",
            "status":"live",
            "group":"Group1",
            "group_code":"groupcode001",
            "user_name":"John Smith",
            "user_id":"17630",
            "host_nickname":"Johnny Boy",
            "host_avatar":null,
            "is_ticker":"n",
            "scheduled_starttime":"1313424000",
            "start_timestamp":"1313430770",
            "end_timestamp":"-62169962400"
        }
    ]
}

event/list Error Responses

A variety of error responses (in addition to the common error responses) to event/list requests, and instructions on how to rectify them:

result response message response solution
missing_status_param Required parameter empty: status. Ensure that the status parameter is present for event/list requests.
invalid_status_param Event status parameter contains invalid values. Ensure that the status parameter only contains valid values (pipe delimited list, which can include 'live', 'upcoming' and 'finished').
invalid_group_code The user does not belong to the group specified by the group parameter. Ensure that the user specified by the token request parameter belongs to the Group specified by the group request parameter.
invalid_account_code The user does not belong to the account specified by the account parameter. Ensure that the user specified by the token request parameter belongs to the Enterprise Account specified by the account request parameter.
invalid_event_code The event_code request parameter did not contain a valid event code. When populating the event_code request parameter, ensure it contains a valid event_code.