This chapter describes the different object models that can be expected within the Calendar42 REST API.

Event

The event object returned by the API always contains two types of fields:

• Fields that describe the general event and are shared between all subscribers
• Fields that describe the relation between the event and the requestor of the event, which are unique to any subscriber

Schema

    {
        # Fields describing the general event
        "id": string,                       # read only
        "sync_token": int,                  # read only
        "creator": person_object,           # read only
        "created": datetime,                # read only
        "modified": datetime,               # read only
        "event_type": event_type_constant,  # write
        "is_suggestion": bool,              # write
        "start": datetime,                  # write
        "end": datetime,                    # write
        "start_timezone": string,           # write
        "end_timezone": string,             # write
        "due": datetime,                    # write
        "all_day": bool,                    # write
        "title": string,                    # write
        "description": string,              # write
        "color": string,                    # write
        "icon": url,                        # write
        "logo": url,                        # write
        "source_url": url,                  # write
        "start_location": location_object,  # write
        "end_location": location_object,    # write
        "related_event": array,             # write
        "time_buffer": int,                 # write
        "length": float,                    # read only
        "trip": trip_object,                # read only @todo: should be write
        "recurrence": bool,                 # read only @todo: should be write
        "recurrence_parent": string,        # read only @todo: should be write

        # Fields describing the relation between the event and the requestor
        "permission": permission,           # read only
        "previous_permission": permission,  # read only
        "is_invitation": bool,              # read only
        "invitation": invitation_object,    # read only
        "calendar_ids": array,              # write
        "rsvp_status": rsvp_status_constant,# write
    }

Fields describing the general event

• id
  • Specifies the unique id that identifies the event
• event_type
  • Specifies the event type, e.g. todo or route
• is_suggestion
  • Specifies whether the event is autogenerated by the system, so it is a suggestion based on the preferences of the user
• creator
  • Person object that created that event
• modified
  • Date of the last modification
• start
  • Specifies the start Datetime
• end
  • Specifies the end Datetime
• start_timezone
  • Specifies the Timezone of the start time
• end_timezone
  • Specifies the Timezone of the end time
• all_day
  • Specifies whether the event is an all day event this should have a true as a value
• due
  • Specifies the Due Datetime
• title
  • Specifies the title
• description
  • Specifies the description
• color
  • Specifies the color, this color should be in hsla format
• icon
  • Specifies the url where to reach the event icon
• logo
  • Specifies the url where to reach the event image
• source_url
  • Specifies the Url source of the event
  • If the event is imported from an external service (ics) this attribute contains the URL where to reach the event information from the source
• start_location
  • Specifies the Location where the event starts
• end_location
  • Specifies the Location where the event ends
• recurrence
  • Specifies whether the event is a recurrence event
• recurrence_parent
  • Specifies the ID of the related recurrence event
• related_event
  • Specifies the list of events ID's related to this event
• sync_token
  • Specifies the sync token
• time_buffer
  • Defines the temporal relation between trips and their related event in seconds. Used when event has event_type arrive_by or depart_from and event has a defined related_event.
• trip
  • Specifies all the Trip data for trip.
  • Present when event_type equals arrive_by, depart_from or route
• length
  • Specifies the length of the trip in meters
  • Present when event_type equals arrive_by, depart_from or route

Fields describing the relation between the event and the requestor

• is_invitation
  • Specifies whether the event is an invitation.
• invitation
  • Specifies meta information about the invitation: Invitation object
• rsvp_status
  • Specifies the string that defines the RSVP status of the user at this event.
• calendar_ids
  • Specifies the list of calendar ID's that requestor has this event in
• permission
  • Specifies the string that defines the Permission that the user have over this event. This is an user related attribute
• previous_permission
  • Specifies the previous Permission that the user had over this event. This is an user related attribute

Event.event_type

• todo - an unplanned event.
• time_block - a time indication.
• normal - a regular planned in event.
• arrive_by - a trip planned with the end time set as arrival time. The start-time is read-only and follows the duration needed to travel between start & end locations based on the end-time.
• depart_from - a trip planned with the start time set as departure time. The end-time is read-only and follows the duration needed to travel between start & end locations based on the start-time
• route - a trip without a start or end time and duration. in development

Event types and their field dependencies

• √ = allowed
• x = not allowed
• ~ = read-only
• Required = Required
• * = Notes

	todo	time_block	normal	depart_from	arrive_by	route
start	x	√Required	√Required	√Required	~* calculated departure time	x
end	x	√Required	√Required	~* calculated arrival time	√Required	x
due	√	√	√	√	√	√
start_location	√	√	√	√Required	√Required	√Required
end_location	x	x	x	√Required	√Required	√Required
duration	√	√* =<(end-start)	√* ==(end-start)	√* ==(end-start)	√* ==(end-start)	√* ==(end-start)

Note on the difference between time_block and normal events

Though the field dependencies are similar between time_block and normal events, the objects do have different meaning:

• the start and end times of the time_block are only indicative, the actual event will happen somewhere in between these times
• one single time_block will not result into user a being marked busy for that period.
  • Only if multiple time_blocks occur in the same period a person will be marked as busy
  • This number of time_blocks is determined on a per service basis, it defaults to: the time period divided through 30 minutes.

Event.rsvp_status

• null - You can't set attendance to this status as this is the default.
• not_replied - Indicating you haven't replied.
• attending - Indicating you're attending the event
• not_attending - Indicating you're not attending the event

Event.trip

Events with an Event Type that equals either arrive_by, depart_from or route will contain trip-data existing of three main elements:

• query_parameters: containing the send in parameters that resulted in the trip
• state: the state of the trip request (loading, error, success)
• data: the actual data belonging to the trip

Next to this trip-data, the event itself will also reflect the start-location, end-location, start-time and end-time of the trip. Other data and relationships are completely similar to regular events.

Event.trip.data

The trip data contains an array of legs depicting the different parts of the trip.

Example of a trip containing one leg:

"data": {
    "legs":[
        {
            "mode": "<transport_type>",
            "start_time": "<date>",
            "end_time": "<date>",
            "length": "<float>",
            "duration": "<float>",
            "real_time": "<boolean>",
            "departure_delay": "<int>",
            "arrival_delay": "<int>",
            "transit_leg": "<boolean>",
            "agency_time_zone_offset": "<int>",
            "leg_geometry": {
                "length": "<int>",
                "points": "<string>"
            },
            "from_location": {
                "location_id": "<string>",
                "text": "<string>",  // was "name"
                "geo": { // was in root as lat & lon
                    "latitude": "<float>",
                    "longitude": "<float>"
                },
                "departure": "<date>",
                "arrival": "<date>"
            },
            "to_location": {
                "location_id": "<string>",
                "text": "<string>",  // was "name"
                "geo": { // was in root as lat & lon
                    "latitude": "<float>",
                    "longitude": "<float>"
                },
                "departure": "<date>",
                "arrival": "<date>"
            },
            "steps": [
                {
                    "street_name": "<string>",
                    "length": "<int>",
                    "elevation": "<array>",
                    "area": "<boolean>",
                    "absolute_direction": "<string>",
                    "relative_direction": "<string>",
                    "stay_on": "<boolean>",
                    "bogus_name": "<boolean>",
                    "geo": { // was in root as lat & lon
                        "latitude": "<float>",
                        "longitude": "<float>"
                    }
                }
            ]
            // Deprecated:
            // "interline-with-previous-leg": "<boolean>",
            // "route": "<string>",
            // "rented-bike": "<boolean>",
            // "pathway": "<boolean>",
        }
    ]
}

Calendar

The calendar data model

Attribute name	Type	Required	Editable	Default	Description	Valid value/s
id	String	false	false	true	Unique id that identifies the calendar
created	Date	false	false		Date were the calendar was created
modified	Date	false	false		Date of the last modification of the calendar
creator	Object	true	false	Person	Person object that created that calendar
inviter	Object	true	false	Person	Person object that invited to this calendar
permission	String	false	false		Type of permission that the user have in this calenda. This is an used related attribute	Permission
name	String	true	true		Name of the calendar
description	String	false	true		Description of the calendar
category	String	false	true		Category of the calendar (will be lowercased and stripped from spaces by default)
color	String	false	true		Calendars can have a color related, this color should be in hsla format
icon	String	false	true		the url where to reach the calendar icon
logo	String	false	true		the url where to reach the calendar image
sync_token	Integer	false	false		The sync token
url	String	false	false		The url where to reach the calendar information
calendar_type	String	false	false		The type of the calendar	Calendar type
first_import	Date	false	false		Date of first successfull import, not send if never imported
import_failed	Date	false		true	Date of last failure, not send if imported successfull afterwards

    {
        "id": "<string>",

        "created": "<date>",
        "modified": "<date>",

        "creator": "<person>",
        "inviter": "<person>",

        "permission": "<permission>",
        "previous_permission": "<permission>",

        "name": "<string>",
        "description": "<string>",
        "category": "<string>",
        "color": "<string>",
        "icon": "<url>",
        "logo": "<url>",

        "sync_token": "<int>",

        "url": "<string>",
        "calendar_type": "<calendar-type>",

        "first_import": "<date>",

        "import_failed": "<date>" 
    }

Location

    {
        "id": "<string>",
        "text": "<string>",
        "address": "<string>",
        "postcode": "<string>",
        "city": "<string>",
        "country": "<string>",
        "geo": {
            "latitude": "<float>",
            "longitude": "<float>"
        },
        "labels": [
            {
                "id": "<string>",
                "name": "<string>",
                "location_type": "<location-type>",
                "service_id": "<string>",  // null if not a service related place
                "description": "<string>",
                "weight": "<int>"
            }
        ]
    }

Position

    {
        // Position meta data
        "source"        : "<the client app name>",
        "type"          : "<normal || forced>",
        "timestamp"     : "<string representation of date and time>",
        "user_info"     : "<An object containing information of user>",

        // Position data
        "latitude"      : "<string representation of latitude value (double)>",
        "longitude"     : "<string representation of longitude value (double)>",
        "accuracy"      : "<string representation of accurracy value (double)>",
        "heading"       : "<string representation of heading value (double)>",
        "speed"         : "<string representation of speed value (double)>",
        "altitude"      : "<string representation of altitude value (double)>",
        "altitude_accuracy": "<string representation of altitude_accuracy value (double)>"
    }

Invitation

    {
        "actor": "<person>",
        "message": "<string>",
        "created": "<date>",
    }

Person

    {
        "id": "<string>",
        "first_name": "<string>",
        "last_name": "<string>",
        "photo": "<url>",
        "email": "<email>",
        "phonenumber": "<phonenumber>",
    }