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
ordepart_from
and event has a definedrelated_event
.
- Defines the temporal relation between trips and their related event in seconds. Used when event has event_type
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-timeroute
- 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 eventnot_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 tripstate
: 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>",
}