iCloud Calendar

Interact with iCloud Calendar via CalDAV.

Actions6

Overview

The "FreeBusy Query" operation of the iCloud Calendar node allows users to check the availability of a specified calendar within a given time range. It queries the calendar for events overlapping with the requested period and returns information about free or busy slots.

This operation is useful in scenarios such as scheduling meetings, booking appointments, or coordinating events where you need to know if a calendar has existing commitments during certain times. For example, before creating a new event, you can query the calendar's free/busy status to avoid conflicts.

Practical examples:

Checking if a team member's calendar is free during a proposed meeting time.
Retrieving all booked slots within a date range to display availability on a booking system.
Getting raw calendar data for custom processing or integration.

Properties

Name	Meaning
Calendar Name or ID	Select the calendar to query from a list of available calendars or specify its ID via expression.
Start Date	The start date and time of the period to check for availability.
End Date	The end date and time of the period to check for availability. Must be strictly after the start date.
Additional Fields:	Collection of optional parameters:
- Output Format	Defines the format of the output. Options are: • Availability: Returns whether there are any events overlapping with the given time slot (boolean). • Booked Slots: Returns detailed booked time slots. • RAW: Returns the raw API response data.
- Timezone Name or ID	The timezone to use for interpreting and returning the results. If not set, the node's configured timezone is used. Choose from a list or specify via expression.

Output

The output JSON structure depends on the selected output format:

Availability:
```
{
  "available": true|false
}
```
Indicates if the calendar is free (true) or busy (false) during the queried time range.

Booked Slots:

{
  "busy": [
    {
      "start": "YYYY-MM-DDTHH:mm:ss±HH:mm",
      "end": "YYYY-MM-DDTHH:mm:ss±HH:mm",
      "summary": "Event title or 'Busy'"
    },
    ...
  ]
}

Lists all busy periods (events) overlapping with the queried time range, including their start/end timestamps and summaries.

RAW:
Returns the raw calendar data retrieved from the iCloud CalDAV API for advanced or custom processing.

No binary data output is produced by this operation.

Dependencies

Requires an active iCloud API credential with username and password for CalDAV access.
Uses the iCloud CalDAV service endpoint https://caldav.icloud.com.
Relies on n8n's timezone configuration or user-specified timezone for date/time handling.
Requires network connectivity to iCloud CalDAV servers.
Uses XML parsing libraries internally to process CalDAV responses.

Troubleshooting

Common Issues:
- Invalid or expired credentials will cause authentication failures.
- Incorrect calendar ID selection may result in empty or error responses.
- Specifying an end date that is not strictly after the start date will throw validation errors.
- Network issues or iCloud service outages can cause request failures.
Error Messages:
- "Could not determine user principal URL": Indicates failure to retrieve the authenticated user's CalDAV principal URL; usually caused by invalid credentials or API changes.
- "Failed to get user principal": Authentication or network error when fetching user info.
- "Free Busy Request Error": General failure during the free/busy query request; check network and credentials.
- "End date must be strictly after start date": Input validation error; ensure end date is later than start date.
Resolutions:
- Verify and re-enter valid iCloud API credentials.
- Confirm the calendar ID is correct and accessible.
- Ensure the start and end dates are logically ordered.
- Check network connectivity and iCloud service status.