Users Calendars Events

Users - Calendars - Events

• API documentation
• Python Regular Expressions
• Collections of Users
• Definitions
• Calendar selection
• Event selection
• Add, import and update calendar events
• Specify calendar attendees with JSON data
• Delete selected calendar events
• Delete all calendar events
• Move calendar events to another calendar
• Empty calendar trash
• Display calendar events
• Update calendar event attendees

API documentation

• https://developers.google.com/calendar/v3/reference/events
• https://developers.google.com/calendar/v3/reference/events/import

Definitions

<DomainName> ::= <String>(.<String>)+
<EmailAddress> ::= <String>@<DomainName>
<EmailAddressList> ::= "<EmailAddress>(,<EmailAddress>)*"
<EmailAddressEntity> ::= <EmailAddressList> | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector> | <CSVDataSelector>
<CalendarItem> ::= <EmailAddress>|<String>
<CalendarList> ::= "<CalendarItem>(,<CalendarItem>)*"
<CourseAlias> ::= <String>
<CourseID> ::= <Number>|d:<CourseAlias>
<CourseIDList> ::= "<CourseID>(,<CourseID>)*"
<CourseState> ::= active|archived|provisioned|declined
<CourseStateList> ::= all|"<CourseState>(,<CourseState>)*"
<ResourceID> ::= <String>
<ResourceIDList> ::= "<ResourceID>(,<ResourceID>)*"
<UniqueID> ::= uid:<String>
<UserItem> ::= <EmailAddress>|<UniqueID>|<String>

<UserGoogleSheet> ::=
        <EmailAddress> <DriveFileIDEntity>|<DriveFileNameEntity> <SheetName>

<CalendarACLRole> ::=
        editor|freebusy|freebusyreader|owner|reader|writer

<CalendarSelectProperty> ::=
        minaccessrole <CalendarACLRole>|
        showdeleted|
        showhidden

<UserCalendarEntity> ::=
        allcalendars|
        primary|
        <EmailAddress>|
        <UniqueUD>|
        (courses <CourseIDList>)|
        ((courses_with_teacher <UserItem>)|my_courses_as_teacher [coursestates <CourseStateList>])|
        ((courses_with_student <UserItem>)|my_courses_as_student [coursestates <CourseStateList>])|
        (resource <ResourceID>)|
        (resources <ResourceIDList>)|
        ((calendars <CalendarList>) | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector> | <CSVDataSelector>)|
        <CalendarSelectProperty>+

<EventAttachmentsSubfieldName> ::=
        attachments.fileid|
        attachments.fileurl|
        attachments.iconlink|
        attachments.mimetype|
        attachments.title

<EventAttendeesSubfieldName> ::=
        attendees.additionalguests|
        attendees.comment|
        attendees.displayname|
        attendees.email|
        attendees.id|
        attendees.optional|
        attendees.organizer|
        attendees.resource|
        attendees.responseStatus|
        attendees.self

<EventConferenceDataSubfieldName> ::=
        conferencedata.conferenceid|
        conferencedata.conferencesolution|
        conferencedata.createrequest|
        conferencedata.entrypoints|
        conferencedata.notes|
        conferencedata.signature

<EventCreatorSubfieldName> ::=
        creator.displayname|
        creator.email|
        creator.id|
        creator.self

<EventOrganizerSubfieldName> ::=
        organizer.displayname|
        organizer.email|
        organizer.id|
        organizer.self

<EventFieldName> ::=
        anyonecanaddself|
        attachments|
	<EventAttachmentsSubfieldName>|
        attendees|
	<EventAttendeesSubfieldName>|
        attendeesomitted|
        colorid|
        conferencedata|
	<EventConferenceDataSubfieldName>|
        created|
        creator|
	<EventCreatorSubfieldName>|
        description|
        end|
        endtimeunspecified|
        extendedproperties|
        gadget|
        guestscaninviteothers|
        guestscanmodify|
        guestscanseeotherguests|
        hangoutlink|
        htmllink|
        icaluid|
        id|
        location|
        locked|
        organizer|
	<EventOrganizerSubfieldName>|
        originalstarttime|
        privatecopy|
        recurrence|
        recurringeventid|
        reminders|
        sequence|
        source|
        start|
        status|
        summary|
        transparency|
        updated|
        visibility
<EventFieldNameList> ::= "<EventFieldName>(,<EventFieldName>)*"

<EventSelectProperty:> ::=
        (endtime|timemax <Time>)|
        (query <QueryCalendar>)|
        (privateextendedproperty <String>)|
        (sharedextendedproperty <String>)|
        showdeletedevents|
        showhiddeninvitations|
        singleevents|
        (starttime|timemin <Time>)|
        (updatedmin <Time>)

<EventMatchProperty:> ::=
        (matchfield attendees <EmailAddressEntity>)|
        (matchfield attendeespattern <RegularExpression>)|
        (matchfield creatoremail <RegularExpression>)|
        (matchfield creatorname <RegularExpression>)|
        (matchfield description <RegularExpression>)|
        (matchfield location <RegularExpression>)|
        (matchfield organizeremail <RegularExpression>)|
        (matchfield organizername <RegularExpression>)|
        (matchfield status <RegularExpression>)|
        (matchfield summary <RegularExpression>)|
        (matchfield transparency <RegularExpression>)|
        (matchfield visibility <RegularExpression>)

<EventEntity> ::=
        (id|eventid <EventId>)|
	(event|events <EventIdList> | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector> | <CSVSubkeySelector> | <CSVDataSelector>)|
        (<EventSelectProperty>* <EventMatchProperty>*)

<EventColorIndex> ::= <Number in range 1-11>
<PropertyKey> ::= <String>
<PropertyValue> ::= <String>
<TimeZone> ::= <String>
<AttendeeAttendance> ::= optional|required
<AttendeeStatus> ::= accepted|declined|needsaction|tentative

<EventAttribute> ::=
        (anyonecanaddself [<Boolean>])|
        (attachment <String> <URL>)|
        (attendee <EmailAddress>)|
        (attendeestatus [<AttendeeAttendance>] [<AttendeeStatus>] <EmailAddress>)|
        available|
        (colorindex|colorid <EventColorIndex>))|
        (description <String>)|
        (end (allday <Date>)|<Time>)|
        (guestscaninviteothers <Boolean>)|
        guestscantinviteothers|
        (guestscanmodify <Boolean>)|
        (guestscanseeotherguests <Boolean>)|
        guestscantseeotherguests|
        (jsonattendees [charset <Charset>] <JSONData>)|(jsonattendees file <FileName> [charset <Charset>])|
        (location <String>)|
        (noreminders|(reminder email|popup|sms <Number>))|
        (optionalattendee <EmailAddress>)|
        (originalstart (allday <Date>)|<Time>)|
        (privateproperty <PropertyKey> <PropertyValue>)|
        (recurrence <RRULE, EXRULE, RDATE and EXDATE line>)|
        (reminder <Number> email|popup|sms))|
        (sequence <Integer>)|
        (sharedproperty <PropertyKey> <PropertyValue>)|
        (source <String> <URL>)|
        (start (allday <Date>)|<Time>)|
        (status confirmed|tentative|cancelled)|
        (summary <String>)|
        tentative|
        (timezone <TimeZone>)|
        (transparency opaque|transparent)|
        (visibility default|public|private)

The following attributes are equivalent:
        available - transparency transparent
        guestscantinviteothers - guestscaninviteothers False
        guestscantseeothers - guestscanseeotherguests False
        tentative - status tentative

<EventNotificationAttribute> ::=
        notifyattendees|(sendnotifications <Boolean>)|(sendupdates all|enternalonly|none)

The following attributes are equivalent:
        notifyattendees - sendupdates all
        sendnotifications false - sendupdates none
        sendnotifications true - sendupdates all

<EventCreateAttribute> ::=
        <EventAttribute>|
        <EventNotificationAttribute>

<EventImportAttribute> ::=
        <EventAttribute>|
        (organizername <String>)|
        (organizeremail <EmailAddress>)

<EventUpdateAttribute> ::=
        <EventAttribute>|
        <EventNotificationAttribute>|
        clearattachments|
        (clearprivateproperty <PropertyKey>)|
        (clearsharedproperty <PropertyKey>)

<EventDisplayProperty> ::=
        (alwaysincludeemail)|
        (icaluid <String>)|
        (maxattendees <Integer>)|
        (orderby starttime|updated)|
        (timezone <TimeZone>)

Calendar selection

These are the possible values for <UserCalendarEntity>.

• allcalendars - All calendars in a user's calendar list
• primary - The user's primary calendar
• <EmailAddress> - The address of a calendar in a user's calendar list
• <UniqueID> - The uniqueid of a calendar in a user's calendar list
• courses <CourseIDList>- The calendars associated with a list of courses
• courses_with_teacher <UserItem> - The calendars associated with courses with <UserItem> as a teacher
• my_courses_as_teacher - The calendars associated with the User from <UserTypeEntity> as a teacher
• courses_with_student <UserItem> - The calendars associated with courses with <UserItem> as a student
• my_courses_as_student - The calendars associated with the User from <UserTypeEntity> as a student
• coursestates <CourseStateList> - Used with the previous four options to select courses in a particular state; the default is all
• resource <ResourceID> - The calendar associated with a resource ID
• resources <ResourceIDList> - The calendars associated with a list of resource IDs
• calendars (<CalendarList> | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector> | <CSVDataSelector>) - A collection of calendars: Collections of Items
• <CalendarSelectProperty>+ - The calendars in a user's calendar list with the specified properites

Event selection

These are the possible values for <EventEntity>; you either specify event IDs or properties used to select events.

• id|eventid <EventId> - A single event ID
• event|events <EventIdList> | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector> | <CSVSubkeySelector> | <CSVDataSelector>) - A collection of event IDs: Collections of Items
• <EventSelectProperty>* <EventMatchProperty>* - Properties used to select events

The Google Calendar API processes <EventSelectProperty>*; you may specify none or multiple properties.

• endtime|timemax <Time> - Upper bound (exclusive) for an event's start time to filter by. If timeMin is set, timeMax must be greater than timeMin.
• query <QueryCalendar> - Free text search terms to find events that match these terms in any field, except for extended properties
• privateextendedproperty <String> - A required private property; <String> must be of the form propertyName=value
• sharedextendedproperty <String> - A required shared property; <String> must be of the form propertyName=value
• showdeletedevents - Whether to include deleted events (with status equals "cancelled") in the result
• showhiddeninvitations - Whether to include hidden invitations in the result
• singleevents - Whether to expand recurring events into instances and only return single one-off events and instances of recurring events, but not the underlying recurring events themselves
• starttime|timemin <Time> - Lower bound (inclusive) for an event's end time to filter by. If timeMax is set, timeMin must be smaller than timeMax.
• updatedmin <Time> - Lower bound for an event's last modification time (as a RFC3339 timestamp) to filter by. When specified, entries deleted since this time will always be included regardless of showdeletedevents

GAM processes <EventMatchProperty>*; you may specify none or multiple properties.

• matchfield attendees <EmailAddressEntity> - All of the attendees in <EmailAddressEntity> must be present
• matchfield attendeespattern <RegularExpression> - Some attendee must match <RegularExpression>
• matchfield creatoremail <RegularExpression> - The creator email address must match <RegularExpression>
• matchfield creatorname <RegularExpression> - The creator name must match <RegularExpression>
• matchfield description <RegularExpression> - The description (summary) must match <RegularExpression>
• matchfield location <RegularExpression> - The location must match <RegularExpression>
• matchfield organizeremail <RegularExpression> - The organizer email address must match <RegularExpression>
• matchfield organizername <RegularExpression> - The orgainzer name must match <RegularExpression>
• matchfield status <RegularExpression> - The summary must match <RegularExpression>. The API documented values are:
  • confirmed
  • tentative
  • cancelled
• matchfield summary <RegularExpression> - The summary must match <RegularExpression>
• matchfield transparency <RegularExpression> - The summary must match <RegularExpression>. The API documented values are:
  • opaque - Busy. The API does not seem to return this value; use "(^$)|opaque" to match no value or opaque.
  • transparent - Free/Available
• matchfield visibility <RegularExpression> - The summary must match <RegularExpression>. The API documented values are:
  • default - The API does not seem to return this value; use "(^$)|default" to match no value or default.
  • public - The API does not seem to return this value if it is the default; use "(^$)|public" to match no value or public.
  • private - The API does not seem to return this value if it is the default; use "(^$)|private" to match no value or private.
  • confidential

Add, import and update calendar events

gam <UserTypeEntity> add event <UserCalendarEntity> [id <String>] <EventCreateAttribute>+
gam <UserTypeEntity> import event <UserCalendarEntity> icaluid <iCalUID> <EventImportAttribute>+
gam <UserTypeEntity> update events <UserCalendarEntity> <EventEntity> <EventUpdateAttribute>+

You can specify multiple attachments; <String> is the title of the attachment and <URL> is a sharable link from Google Drive. You must specify all attachments in each command, you can not incrementally add attachments. You delete all attachments with the clearattachments option.

You can specify attendees in the following ways:

• attendee <EmailAddress> - The attendee attendance is required with status `needsaction'
• optionalattendee <EmailAddress> - The attendee attendance is optional with status `needsaction'
• attendeestatus [<AttendeeAttendance>] [<AttendeeStatus>] <EmailAddress>
• If <AttendeeAttendance> is not specified, the attendee is required to attend
• If <AttendeeStatus> is not specified, needsaction is chosen

Importing events is similar to adding events; the principal difference is that you must specify an iCalUID. All instances of recurring events will have the same iCalUID but different EventIDs. The import command supports two new attributes to set the event organizer, but the API doesn't seem to honor the values; the organizer is set to the calendar owner.

Specify calendar attendees with JSON data

Calendar events can have multiple attendees, the API requires that all attendees be specified when updating the attendee list. This becomes very hard when there are many attendees and you want to add another one. Here is a method that can simplify the process. See Update calendar event attendees for an alternate method.

$ gam user testuser1@domain.com info event primary id 00003luj8mlv5skmfsfle3zzzz fields attendees
User: testuser1@domain.com, Show Info Events in 1 Calendar
  Calendar: testuser1@domain.com, Show Info 1 Event
    Event: 00003luj8mlv5skmfsfle3zzzz
      attendees:
        email: testuser3@domain.com
          responseStatus: accepted
        email: testuser4@domain.com
          responseStatus: accepted
$ gam redirect stdout ./attendees.json user testuser1@domain.com info event primary id 00003luj8mlv5skmfsfle3zzzz fields attendees formatjson
$ more attendees.json
{"calendarId": "testuser1@domain.com", "event": {"attendees": [{"email": "testuser3@domain.com", "responseStatus": "accepted"}, {"email": "testuser4@domain.com", "responseStatus": "accepted"}], "id": "00003luj8mlv5skmfsfle3zzzz"}, "primaryEmail": "testuser1@domain.com"}
# Edit attendees.json to add testuser2@domain.com as an attendee
$ more attendees.json
{"calendarId": "testuser1@rdschool.org", "event": {"attendees": [{"email": "testuser2@rdschool.org", "responseStatus": "needsAction", "optional": "True"}, {"email": "testuser3@rdschool.org", "responseStatus": "accepted"}, {"email": "testuser4@rdschool.org", "responseStatus": "accepted"}], "id": "00003luj8mlv5skmfsfle3zzzz"}, "primaryEmail": "testuser1@rdschool.org"}
$ gam user testuser1@domain.com update event primary id 00003luj8mlv5skmfsfle3zzzz jsonattendees file attendees.json sendnotifications true
User: testuser1@domain.com, Update Events in 1 Calendar
  Calendar: testuser1@domain.com, Update 1 Event
    Calendar: testuser1@domain.com, Event: 00003luj8mlv5skmfsfle3zzzz, Updated
$ gam user testuser1@domain.com info event primary id 00003luj8mlv5skmfsfle3zzzz fields attendees
User: testuser1@domain.com, Show Info Events in 1 Calendar
  Calendar: testuser1@domain.com, Show Info 1 Event
    Event: 00003luj8mlv5skmfsfle3zzzz
      attendees:
        email: testuser2@domain.com
          optional: True
          responseStatus: needsAction
        email: testuser3@domain.com
          responseStatus: accepted
        email: testuser4@domain.com
          responseStatus: accepted

You can predefine lists of attendees and use them when creating events. If you set responseStatus to accepted, no notifications are sent.

$ more attendees.json
{"attendees": [{"email": "testuser2@domain.com", "responseStatus": "needsAction", "optional": "True"}, {"email": "testuser3@domain.com", "responseStatus": "accepted"}, {"email": "testuser4@domain.com", "responseStatus": "accepted"}]}
$ gam user testuser1@domain.com create event primary start 2019-04-19T19:00:00-07:00 end 2019-04-19T19:00:00-07:00 summary "234 Meeting" jsonattendees file attendees.json sendnotifications true
User: testuser1@domain.com, Create Events to 1 Calendar
  Calendar: testuser1@domain.com, Event: 00003luj8mlv5skmfsfle3zzzz, Created
$ gam user testuser1@domain.com info event primary id 00003luj8mlv5skmfsfle3zzzz
User: testuser1@domain.com, Show Info Events in 1 Calendar
  Calendar: testuser1@domain.com, Show Info 1 Event
    Event: 00003luj8mlv5skmfsfle3zzzz
      summary: 234 Meeting
      start:
        dateTime: 2019-04-19T19:00:00-07:00
      end:
        dateTime: 2019-04-19T19:00:00-07:00
      creator:
        displayName: Test User1
        email: testuser1@domain.com
        self: True
      organizer:
        displayName: Test User1
        email: testuser1@domain.com
        self: True
      status: confirmed
      created: 2019-04-19T18:42:16-07:00
      updated: 2019-04-19T18:42:16-07:00
      iCalUID: 00003luj8mlv5skmfsfle3zzzz@google.com
      attendees:
        email: testuser2@domain.com
          optional: True
          responseStatus: needsAction
        email: testuser3@domain.com
          responseStatus: accepted
        email: testuser4@domain.com
          responseStatus: accepted

Delete selected calendar events

gam <UserTypeEntity> delete events <UserCalendarEntity> <EventEntity> [doit] [notifyattendees]
gam <UserTypeEntity> purge events <UserCalendarEntity> <EventEntity> [doit] [notifyattendees]

No events are deleted unless you specify the doit option; omit doit to verify that you properly selected the events to delete.

When events are deleted from a calendar, they are moved to the calendar's trash and are only permanently deleted (purged) after 30 days. Following a suggestion here (https://stackoverflow.com/questions/41043053/how-to-empty-calendar-trash-via-google-services) you can permanently delete calendar events. This is achieved by creating a temporary calendar, deleting the events, moving the deleted events to the temporary calendar and then deleting the temporary calendar.

Delete all calendar events

gam <UserTypeEntity> wipe events <UserCalendarEntity>

Move calendar events to another calendar

gam <UserTypeEntity> move events <UserCalendarEntity> <EventEntity> to <CalendarItem> [notifyattendees]

Empty calendar trash

A user signed in to Google Calendar can empty the calendar trash but there is no direct API support for this operation. To empty the calendar trash a temporary calendar is created, the deleted events are moved to the temporary calendar and then the temporary calendar is deleted.

gam <UserTypeEntity> empty calendartrash <UserCalendarEntity>

Display calendar events

gam <UserTypeEntity> info events <UserCalendarEntity> <EventEntity> [maxinstances <Number>] [fields <EventFieldNameList>] [formatjson]

• maxinstances -1 - Default, display base event
• maxinstances 0 - Display all instances of a recurring event
• maxinstances N - Display first N instances of a recurring event

By default, Gam displays the information as an indented list of keys and values.

• formatjson - Display the fields in JSON format.

gam <UserTypeEntity> show events <UserCalendarEntity> <EventSelectProperty>* <EventMatchProperty>* <EventDisplayProperty>* [fields <EventFieldNameList>] [formatjson]

Any <EventSelectProperty> options must precede all other options.

<EventDisplayProperty> orderby starttime is only valid with <EventSelectProperty> singleevents.

By default, Gam displays the information as an indented list of keys and values.

• formatjson - Display the fields in JSON format.

gam <UserTypeEntity> print events <UserCalendarEntity> <EventSelectProperty>* <EventMatchProperty>* <EventDisplayProperty>* [fields <EventFieldNameList>]
         [formatjson] [quotechar <Character>] [todrive <ToDriveAttribute>*]

Any <EventSelectProperty> options must precede all other options.

<EventDisplayProperty> orderby starttime is only valid with <EventSelectProperty> singleevents.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output. The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. quotechar defaults to gam.cfg/csv_output_quote_char.

Update calendar event attendees

gam <UserTypeEntity> update calattendees <UserCalendarEntity> <EventEntity> [anyorganizer] [<EventNotificationAttribute>] [doit]
        (csv <FileName>|(gsheet <UserGoogleSheet>))*
        (add <EmailAddress>)* (delete <EmailAddress>)* (replace <EmailAddress> <EmailAddress>)*
        (addstatus [<AttendeeAttendance>] [<AttendeeStatus>] <EmailAddress>)*
        (replacestatus [<AttendeeAttendance>] [<AttendeeStatus>] <EmailAddress> <EmailAddress>)*
        (updatestatus [<AttendeeAttendance>] [<AttendeeStatus>] <EmailAddress>)*

By default, only events organized by the user are selected.

• anyorganizer|allevents - All events are selected.

• csv <FileName> - A CSV file with no header row and two to four columns; the last two columns are optional

  • <EmailAddress>,add,<AttendeeAttendance>,<AttendeeStatus> - Add an attendee
  • <EmailAddress>,delete - Delete an attendee
  • <EmailAddress>,<EmailAddress>,<AttendeeAttendance>,<AttendeeStatus> - Replace the attendee in the first <EmailAddress> with the attendee in the second <EmailAddress>
  • <EmailAddress>,update,<AttendeeAttendance>,<AttendeeStatus> - Update an attendee

• gsheet <UserGoogleSheet> - A Google Sheet with no header row and two columns

  • <EmailAddress>,add,<AttendeeAttendance>,<AttendeeStatus> - Add an attendee
  • <EmailAddress>,delete - Delete an attendee
  • <EmailAddress>,<EmailAddress>,<AttendeeAttendance>,<AttendeeStatus> - Replace the attendee in the first <EmailAddress> with the attendee in the second <EmailAddress>
  • <EmailAddress>,update,<AttendeeAttendance>,<AttendeeStatus> - Update an attendee

• add <EmailAddress> - Add an attendee

• delete <EmailAddress> - Delete an attendee

• replace <EmailAddress> <EmailAddress> - Replace the attendee in the first <EmailAddress> with the attendee in the second <EmailAddress>

• addstatus [<AttendeeAttendance>] [<AttendeeStatus>] <EmailAddress> - Add an attendee

• replacestatus [<AttendeeAttendance>] [<AttendeeStatus>] <EmailAddress> <EmailAddress> - Replace the attendee in the first <EmailAddress> with the attendee in the second <EmailAddress>

• updatestatus [<AttendeeAttendance>] [<AttendeeStatus>] <EmailAddress> - Update an attendee

For add and addstatus:

• <AttendeeAttendance> - Default is required
• <AttendanceStatus> - Default isneedsaction

For replace, replacestatus and updatestatus:

• <AttendeeAttendance> - Default is no change from current value
• <AttendanceStatus> - Default is no change from current value

The attendee changes are displayed but not processed unless doit is specified.