📅 Calendar API Documentation

Overview

The Calendar API allows you to fetch and parse ICS (iCalendar) files from URLs and retrieve meeting details for a specified date range. The API automatically handles recurring events and converts times to your specified timezone.

Endpoint

Request Parameters

Response Format

Success Response

When the request is successful, the API returns a JSON object with the following structure:

{
  "success": true,
  "data": [
    {
      "name": "Team Standup",
      "start_time": "2025-10-08 09:00:00",
      "end_time": "2025-10-08 09:30:00",
      "participants": [
        "John Doe",
        "Jane Smith",
        "bob@example.com"
      ],
      "details": "Daily team sync meeting to discuss progress and blockers.",
      "location": "Conference Room A",
      "timezone": "America/New_York"
    },
    ...
  ],
  "count": 15
}

Response Fields

Meeting Object Fields

Error Response

When an error occurs, the API returns:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Examples

Example 1: Basic Request

GET /calendar.php?ics_url=https://example.com/calendar.ics&start_date=2025-10-01&end_date=2025-10-31&timezone=America/New_York

{
  "success": true,
  "data": [
    {
      "name": "Weekly Team Meeting",
      "start_time": "2025-10-01 10:00:00",
      "end_time": "2025-10-01 11:00:00",
      "participants": [
        "Alice Johnson",
        "Bob Smith",
        "carol@company.com"
      ],
      "details": "Weekly sync to discuss project progress",
      "location": "Room 301",
      "timezone": "America/New_York"
    },
    {
      "name": "Client Presentation",
      "start_time": "2025-10-03 14:00:00",
      "end_time": "2025-10-03 15:30:00",
      "participants": [
        "John Doe",
        "client@external.com"
      ],
      "details": "Q3 results presentation for major client",
      "location": "Zoom: https://zoom.us/j/123456",
      "timezone": "America/New_York"
    }
  ],
  "count": 2
}

Example 2: Single Day Query

GET /calendar.php?ics_url=https://example.com/calendar.ics&start_date=2025-10-08&end_date=2025-10-08&timezone=Europe/London

{
  "success": true,
  "data": [
    {
      "name": "Morning Standup",
      "start_time": "2025-10-08 09:00:00",
      "end_time": "2025-10-08 09:15:00",
      "participants": ["Team"],
      "details": "",
      "location": "",
      "timezone": "Europe/London"
    }
  ],
  "count": 1
}

Example 3: Using JavaScript Fetch

const params = new URLSearchParams({
  ics_url: 'https://example.com/calendar.ics',
  start_date: '2025-10-01',
  end_date: '2025-10-31',
  timezone: 'America/Los_Angeles'
});

fetch(`/calendar.php?${params}`)
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log(`Found ${data.count} meetings:`);
      data.data.forEach(meeting => {
        console.log(`${meeting.name} at ${meeting.start_time}`);
      });
    } else {
      console.error('Error:', data.error);
    }
  })
  .catch(error => console.error('Request failed:', error));

Example 4: Using PHP as a Function

// Include the calendar.php file
require_once 'calendar.php';

// Call the function directly
$result = get_calendar_events([
    'ics_url' => 'https://example.com/calendar.ics',
    'start_date' => '2025-10-01',
    'end_date' => '2025-10-31',
    'timezone' => 'America/Chicago'
]);

if ($result['success']) {
    echo "Found " . $result['count'] . " meetings:\n";
    foreach ($result['data'] as $meeting) {
        echo $meeting['name'] . " - " . $meeting['start_time'] . "\n";
    }
} else {
    echo "Error: " . $result['error'];
}

Recurring Events

The API automatically handles recurring events based on RRULE specifications in the ICS file. Supported recurrence patterns include:

• DAILY: Events that repeat every day or every N days
• WEEKLY: Events that repeat weekly, with optional specific days (BYDAY)
• MONTHLY: Events that repeat monthly
• YEARLY: Events that repeat annually

Example Recurring Event

If your ICS file contains a weekly recurring meeting every Monday at 10:00 AM, and you query for October 2025, the API will return all Monday occurrences in that month:

{
  "success": true,
  "data": [
    {
      "name": "Weekly Sync",
      "start_time": "2025-10-06 10:00:00",
      ...
    },
    {
      "name": "Weekly Sync",
      "start_time": "2025-10-13 10:00:00",
      ...
    },
    {
      "name": "Weekly Sync",
      "start_time": "2025-10-20 10:00:00",
      ...
    },
    {
      "name": "Weekly Sync",
      "start_time": "2025-10-27 10:00:00",
      ...
    }
  ],
  "count": 4
}

Timezone Support

The API supports all standard PHP timezone identifiers. Some common examples:

Best Practices

• Date Range: Keep date ranges reasonable (e.g., 1-3 months) to ensure optimal performance
• URL Encoding: Always URL-encode the ICS URL parameter if it contains special characters
• Timezone Consistency: Use the same timezone throughout your application for consistency
• Error Handling: Always check the success field in the response before processing data
• Caching: Consider caching results for frequently accessed date ranges to reduce server load
• Public URLs: Ensure ICS URLs are publicly accessible (not behind authentication)

Limitations

• The ICS file must be publicly accessible via HTTP/HTTPS
• Files requiring authentication are not supported
• Maximum 1000 iterations for recurring events (safety limit)
• Attachment information is not included in the response
• Some complex RRULE patterns may not be fully supported
• The API has a 30-second timeout for fetching ICS files

Testing the API

You can test the API using various methods:

Using cURL

curl "https://yourdomain.com/calendar.php?ics_url=https://example.com/calendar.ics&start_date=2025-10-01&end_date=2025-10-31&timezone=UTC"

Using Browser

Simply paste the URL with parameters into your browser's address bar:

https://yourdomain.com/calendar.php?ics_url=https://example.com/calendar.ics&start_date=2025-10-01&end_date=2025-10-31&timezone=America/New_York

Using Postman

1. Create a new GET request
2. Enter the base URL: https://yourdomain.com/calendar.php
3. Add query parameters in the Params tab
4. Click Send