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
  • is_suggestion
    • Specifies whether the event is autogenerated by the system, so it is a suggestion based on the preferences of the user
  • creator
  • modified
    • Date of the last modification
  • start
  • end
  • 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
  • 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
  • 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
  • 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>",
    }