gcal-fetcher

Fetch events from the Google Calendar JSON API using only an API key — no OAuth required.

Prerequisites

Google Calendar Api Key
Google Calendar ID (The Calendar ID looks like your_email@gmail.com for a primary calendar or xxxx@group.calendar.google.com for other calendars.)

Notes

Only works for public Google Calendars (no support for private calendars with auth)
All timestamps are in chrono::Utc, the client will have to take care of timezones.
This crate exposes chrono::DateTime<Utc> in its public API. The chrono crate is re-exported as gcal-fetcher::chrono so you don't need a direct dependency on it. If you do depend on chrono directly, pin a version compatible with 0.4 to avoid type-mismatch errors.
DateTime is accessible as gcal_fetcher::DateTime/gcal_fetcher::Utc, so if not needed otherwise you don't need to import chrono yourself.

Installation

[dependencies]
gcal-fetcher = "0.1"

Usage

use std::num::NonZeroI32;
use gcal_fetcher::fetch_events;

fn main() {
    let calendar_id = "your-calendar-id@group.calendar.google.com";
    let api_key     = "YOUR_GOOGLE_API_KEY"; // your API Key should not be public!
    let days_ahead  = NonZeroI32::new(30).unwrap();

    match fetch_events(calendar_id, api_key, days_ahead) {
        Ok(events) => {
            for event in &events {
                println!("{} — {} to {}", event.summary, event.start, event.end);
                if event.is_whole_day_event {
                    println!("  (All-day event)");
                }
                if let Some(loc) = &event.location {
                    println!("  📍 {}", loc);
                }
            }
            println!("{} event(s) found.", events.len());
        }
        Err(e) => eprintln!("Error: {}", e),
    }
}

API

Functions

`fetch_events`

pub fn fetch_events(
    calendar_id: &str,
    api_key: &str,
    fetch_days: NonZeroI32,
) -> Result<Vec<CalendarEvent>, FetchError>

Fetches all events from now up to fetch_days days into the future. Recurring events are expanded server-side (singleEvents=true). Results are sorted by start time. Negative values for fetch_days are technically supported to fetch past events.

`fetch_events_starting_from`

pub fn fetch_events_starting_from(
    calendar_id: &str,
    api_key: &str,
    fetch_days: NonZeroI32,
    now: DateTime<Utc>,
) -> Result<Vec<CalendarEvent>, FetchError>

Same as fetch_events, but accepts an explicit now timestamp. Useful for testing or when you need a reproducible time window.

`CalendarEvent`

Encompasses the interesting information from a Google Calendar Event:

pub struct CalendarEvent {
    pub id:                 String,
    pub etag:               String,
    pub summary:            String,
    pub start:              DateTime<Utc>,
    pub end:                DateTime<Utc>,
    pub description:        Option<String>,
    pub location:           Option<String>,
    pub is_whole_day_event: bool,
}

Field	Description
`id`	Unique event ID from the Google Calendar API
`etag`	Entity tag for cache-validation; changes whenever the event is edited
`summary`	Event title (`"(No title)"` if absent)
`start`	Start time in UTC. All-day events are normalised to `00:00:00 UTC` on their start date
`end`	End time in UTC. All-day events are normalised to `00:00:00 UTC` on their end date
`description`	Optional event description
`location`	Optional location string
`is_whole_day_event`	`true` if the event is an all-day event (Google provided a date only, not a date-time)

Note on all-day events: Google represents all-day events with a plain date (2026-05-01) rather than a date-time. gcal-fetcher converts these to 2026-05-01T00:00:00Z. Keep this in mind when displaying or comparing times for all-day events.

`FetchError`

pub enum FetchError {
    Http(ureq::Error),
    Io(std::io::Error),
    Parse(serde_json::Error),
}

Variant	Cause
`Http`	The HTTP request failed (network error, non-2xx status, invalid API key, etc.)
`Io`	Failed to read the response body
`Parse`	The response body could not be parsed as JSON

License

MIT — see LICENSE or https://opensource.org/licenses/MIT.

gcal-fetcher 0.1.0