Google Calendar API gebruiken voor afsprakenbeheer

Waarom de Google Calendar API?

De Google Calendar API geeft je programmatische toegang tot Google Agenda: je kunt afspraken aanmaken, lezen, bijwerken en verwijderen vanuit je eigen applicatie. Dit is handig voor:

• CRM-systemen die automatisch agenda-items aanmaken bij een verkoop
• Booking-applicaties die beschikbaarheid controleren en afspraken vastleggen
• Geautomatiseerde herinneringen of terugkerende planning
• Rapporten over vergadertijd en agenda-gebruik

Stap 1: API inschakelen en authenticatie opzetten

OAuth 2.0 of serviceaccount?

Onderstaande tabel helpt je kiezen tussen de twee authenticatiemethodes.

Stap 2: Authenticatie implementeren (Python)

Onderstaand voorbeeld gebruikt de officiele Google-clientbibliotheken (google-auth-oauthlib en google-api-python-client). Het slaat het token lokaal op zodat de gebruiker niet bij elke run opnieuw hoeft in te loggen.

from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
import os

SCOPES = ['https://www.googleapis.com/auth/calendar']

def get_calendar_service():
    creds = None
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)

    if not creds or not creds.valid:
        flow = InstalledAppFlow.from_client_secrets_file(
            'credentials.json', SCOPES
        )
        creds = flow.run_local_server(port=0)
        with open('token.json', 'w') as token:
            token.write(creds.to_json())

    return build('calendar', 'v3', credentials=creds)

Stap 3: Afspraken aanmaken

def create_event(service, calendar_id, titel, start_dt, end_dt, deelnemers=None):
    event = {
        'summary': titel,
        'start': {
            'dateTime': start_dt.isoformat(),
            'timeZone': 'Europe/Amsterdam',
        },
        'end': {
            'dateTime': end_dt.isoformat(),
            'timeZone': 'Europe/Amsterdam',
        },
    }

    if deelnemers:
        event['attendees'] = [{'email': email} for email in deelnemers]

    result = service.events().insert(
        calendarId=calendar_id,
        body=event,
        sendUpdates='all'
    ).execute()

    return result.get('htmlLink')

Met sendUpdates='all' krijgen alle deelnemers automatisch een uitnodiging. Gebruik 'none' als je geen mails wilt versturen, bijvoorbeeld bij een bulk-import.

Stap 4: Afspraken ophalen

from datetime import datetime, timezone

def get_upcoming_events(service, calendar_id, max_results=10):
    now = datetime.now(timezone.utc).isoformat()

    events_result = service.events().list(
        calendarId=calendar_id,
        timeMin=now,
        maxResults=max_results,
        singleEvents=True,
        orderBy='startTime'
    ).execute()

    return events_result.get('items', [])

Zet singleEvents=True zodat terugkerende afspraken worden uitgesplitst naar losse instanties. Alleen dan werkt orderBy='startTime' correct.

Beschikbaarheid controleren met FreeBusy

De FreeBusy-query is ideaal om beschikbaarheid te controleren voordat je een afspraak plant. Je krijgt per agenda de bezette tijdsblokken terug, zonder de details van de afspraken zelf.

def check_availability(service, email_addresses, start_dt, end_dt):
    body = {
        'timeMin': start_dt.isoformat(),
        'timeMax': end_dt.isoformat(),
        'timeZone': 'Europe/Amsterdam',
        'items': [{'id': email} for email in email_addresses]
    }

    result = service.freebusy().query(body=body).execute()
    return result.get('calendars', {})

Webhooks voor real-time updates

In plaats van periodiek de API te pollen, kun je een notificatiekanaal instellen dat je applicatie een POST-verzoek stuurt zodra er iets in de agenda wijzigt.

def setup_calendar_watch(service, calendar_id, webhook_url):
    channel = {
        'id': 'mijn-unieke-channel-id',
        'type': 'web_hook',
        'address': webhook_url,
    }

    result = service.events().watch(
        calendarId=calendar_id,
        body=channel
    ).execute()

    return result

Het kanaal verloopt na verloop van tijd (de vervaldatum staat in het antwoord). Plan een proces dat het kanaal op tijd vernieuwt en de oude weer afsluit met service.channels().stop(). Je webhook_url moet publiek bereikbaar zijn via HTTPS met een geldig certificaat.