GET/users/{userId}/calendars/events/search

Search for events across the user’s entire calendar.

  • You can specify a search period of up to 180 days. If neither startTime nor endTime is specified, the search will cover the three months before and after the current time.
  • It may take some time for newly created or modified events to appear in the search results.
  • Depending on request volume, responses may be delayed or access may be restricted.

Authorization

oauth2

OAuth 2.0 authentication.
For more information, see Authentication and Authorization.

Scope

calendar
calendar.read

HTTP Request

GEThttps://www.worksapis.com/v1.0/users/{userId}/calendars/events/search

Path Parameters

ParameterTypeDescription
userId string 

User ID


required
example : userf7da-f82c-4284-13e7-030f3b4c756x 

Query Parameters

ParameterTypeDescription
query string 

Search terms

  • Specify using URL encoding.
  • Case-insensitive.
  • If not specified, results are returned without any search criteria.
  • Required when queryFilters is specified.

minLength : 2
maxLength : 100
example : Weekly Meeting 
queryFilters string 

Search fields

  • Available values:
    • summary : Title
    • attendee : Attendee
    • location : Location
    • description : Notes
  • To specify multiple values, separate them with commas (,).
  • By default, the search covers all of the following: title, attendees, location and notes.

example : summary,attendee 
startTime string 

End time for search (format: YYYY-MM-DDThh:mm:ssTZD)

  • 「+」 must be URL-encoded to 「%2B」.

example : 2021-06-03T10:00:00%2B09:00 
endTime string 

End time for search (format: YYYY-MM-DDThh:mm:ssTZD)

  • 「+」 must be URL-encoded to 「%2B」.

example : 2021-06-03T11:00:00%2B09:00 
count integer 

Number of items returned at a time


default : 50
minimum : 1
maximum : 100
example : 50
format : int32 
cursor string 

Cursor


example : JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA== 

Header Parameters

HeadertypeDescription
Authorization string 

Bearer {token}


required 

Response

HTTP 200

OK

PropertyTypeDescription
events array (EventComponents) 

Event List

 
responseMetaData object (responseMetaData) 

Response metadata

 

EventComponents

PropertyTypeDescription
eventComponents array (Event) 

Event Information

 
organizerCalendarId string 

Calendar ID of the event

 

Event

PropertyTypeDescription
eventId string 

Event ID


required
minLength : 1
maxLength : 255 
createdTime object (createdTime) 

Date and time


readOnly : true 
updatedTime object (updatedTime) 

Date and time


readOnly : true 
summary string 

Event content


required
minLength : 0
maxLength : 200 
description string 

Event memo


minLength : 0
maxLength : 5000 
location string 

Event location


minLength : 0
maxLength : 100 
map object (map) 

Location information

 
mapUrl object (mapUrl) 

Image and URL of the attached map

 
categoryId string 

Event category ID

 
organizer object (organizer) 

Event organizer.
It refers to the calendar which the event belongs to.

  • Default calendar: Email address (if exists) or login ID of the default calendar master
  • Other calendars: Calendar's unique email address

readOnly : true 
start object (start) 

Start or end time of the event


required 
end object (end) 

Start or end time of the event

 
recurrence array (Recurrence) 

minItems : 0
maxItems : 100 
recurringEventId string 

Non-recurring event ID.
(See https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.4.4)

 
transparency string 

Indicates whether the event is busy or free

  • OPAQUE: Busy
  • TRANSPARENT: Free

default : OPAQUE
Allowed values : OPAQUE, TRANSPARENT 
visibility string 

Indicates whether the event is public or private

  • PUBLIC: Public
  • PRIVATE: Private

default : PUBLIC
Allowed values : PUBLIC, PRIVATE 
sequence integer 

Event sequence number.
For more information, see Sequence Number.


default : 0
minimum : 0
format : int32 
attendees array (Attendee) 

Attendee information


minItems : 0
maxItems : 500 
videoMeeting object (videoMeeting) 

Video conference information in the event

 
reminders array (Alarm) 

Reminder information


minItems : 0
maxItems : 100 
attachments array (File) 

Attachment information (The total size of the attached files cannot exceed 100 MB.)


readOnly : true 
viewUrl string 

URL to view events


minLength : 0
format : uri
readOnly : true 
priority integer 

Level of importance 0: Undefined 1: Most important 2: Second most important .... 9: Least important


default : 0
minimum : 0
maximum : 9 

createdTime

PropertyTypeDescription
dateTime string 

Format: YYYY-MM-DDTHH:mm:ss

 
timeZone string 

Timezone

 

updatedTime

PropertyTypeDescription
dateTime string 

Format: YYYY-MM-DDTHH:mm:ss

 
timeZone string 

Timezone

 

map

PropertyTypeDescription
type string 

Map type

  • NAVER, Google, etc.
 
geo string 

Latitude and longitude of the attached map

 

mapUrl

PropertyTypeDescription
mapUrl string 

Map URL

 
imageId string 

Map image

 

organizer

PropertyTypeDescription
email string 

Organizer's email address
Required


required 
displayName string 

Organizer name

 

start

PropertyTypeDescription
date string 

It is present if the event type is all day.

  • Format: YYYY-MM-DD

The start date is inclusive, and the end date is exclusive.

 
dateTime string 

It is present if the event type is not all day.

  • Format: YYYY-MM-DDTHH:mm:ss
 
timeZone string 

Timezone of dateTime (It is present if the event is not all day.)
Timezone

 

end

PropertyTypeDescription
date string 

It is present if the event type is all day.

  • Format: YYYY-MM-DD

The start date is inclusive, and the end date is exclusive.

 
dateTime string 

It is present if the event type is not all day.

  • Format: YYYY-MM-DDTHH:mm:ss
 
timeZone string 

Timezone of dateTime (It is present if the event is not all day.)
Timezone

 

Recurrence

PropertyTypeDescription
Recurrence string 

This property defines a recurrence rule for a recurring event.
For more information, see the following:
EXDATE: https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.5.1
RRULE: https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.10
Example) When the event recurs every Tuesday
RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=TH

 

Attendee

PropertyTypeDescription
id string 

Resource ID

  • It is required if a resource is specified.
 
email string 

Attendee's email address

  • It is required if an attendee is specified.
 
displayName string 

User or resource name

 
partstat string 

Attendance status

  • NEEDS-ACTION: No response
  • ACCEPTED: Accepted
  • TENTATIVE: Tentative
  • DECLINED: Declined

Allowed values : NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE 
isResource boolean 

Indicates whether it is a resource.


default : false 
isOptional boolean 

Indicates whether attendance is optional.


default : false 
resourceValue string 

Unique resource value

 

videoMeeting

PropertyTypeDescription
url string 

Video conference URL


format : uri 
resourceId string 

Video conference ID

 

Alarm

PropertyTypeDescription
method string 

Reminder type

  • DISPLAY: Push or service notification
  • EMAIL: Email notification

required
Allowed values : DISPLAY, EMAIL 
trigger string 

Sets a reminder for the event.

  • For more information, see Trigger. Example)
    -PT0S: at time of event
  • PT15M: 15 minutes before
  • PT12H: 12 hours before
    -P1D: 1 day before
  • P1W: 1 week before
  • P6DT12H: 6 days 12 hours before
 
triggerDateTime object (triggerDateTime) 

Date and time

 

triggerDateTime

PropertyTypeDescription
dateTime string 

Format: YYYY-MM-DDTHH:mm:ss

 
timeZone string 

Timezone

 

File

PropertyTypeDescription
fileUrl string 

File URL


readOnly : true 
fileName string 

File name


readOnly : true 
fileSize integer 

File size (in bytes)


minimum : 0
format : int64
readOnly : true 

responseMetaData

PropertyTypeDescription
nextCursor string 

Cursor


example : JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA==
nullable : true 

Response Example

example

1{2  "events": [3    {4      "eventComponents": [5        {6          "eventId": "eventr8123-wehuh324-qwejqw123",7          "createdTime": {8            "dateTime": "2021-12-12T22:44:59",9            "timeZone": "America/New_York"10          },11          "updatedTime": {12            "dateTime": "2021-12-14T21:01:31",13            "timeZone": "America/New_York"14          },15          "summary": "Weekly Meeting",16          "description": "Memo",17          "location": "CUNY Graduate Center",18          "organizer": {19            "email": "user1@example.com",20            "displayName": "userName1"21          },22          "start": {23            "dateTime": "2021-12-13T14:00:00",24            "timeZone": "America/New_York"25          },26          "end": {27            "dateTime": "2021-12-13T15:00:00",28            "timeZone": "America/New_York"29          },30          "attendees": [31            {32              "email": "attendee1@example.com",33              "displayName": "user1",34              "partstat": "NEEDS-ACTION",35              "isOptional": false,36              "isResource": false37            }38          ],39          "viewUrl": "https://calendar.worksmobile.com/permanentLink.nhn"40        }41      ],42      "organizerCalendarId": "calendar-96b8-4c74-8277-7953e0b4604a"43    }44  ],45  "responseMetaData": {46    "nextCursor": "JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA=="47  }48}

HTTP 400

Bad Request

HTTP 403

Forbidden

HTTP 404

Not Found