Calendar

The Calendar object describes when an event or location is open or available. It is the richest concept in the Event Connectors API — supporting everything from "always open" parks to complex recurring schedules with exception dates and per-slot booking links.

Every TRCItem (event, location, venue, route) can carry a Calendar. When you read one from the API, the first question is: which pattern am I looking at?

Decision Tree

Use this to identify the right pattern for your use case:

1. Is it always accessible (24/7)? → Set alwaysopen: true. Example: a public park.
2. Is it available only on request? → Set onrequest: true. Example: a private guided tour.
3. Does it happen on specific individual dates? → Use singleDates. Example: a three-night concert series.
4. Does it have regular recurring hours with no end date? → Use patternDates without startdate/enddate. This produces calendarType: OPENINGTIMES. Example: a museum open Tue–Sun 10:00–17:00.
5. Does it have regular recurring hours within a date range? → Use patternDates with startdate and enddate. This produces calendarType: PATTERNDATES. Example: a summer festival running every weekend in July.
6. None of the above? → calendarType will be NONE.

Local Dates (No Time Zone)

All dates and times in a Calendar are local to the event location. Do not include time-zone offsets — the system converts to UTC internally. For example, an event in Amsterdam at 20:00 should be submitted as "timestart": "20:00", not "timestart": "20:00+02:00".

Day-of-Week Numbering

This numbering is used in PatternDate.opens[].day.

Pattern: Always Open

For locations accessible 24/7 — public parks, outdoor monuments, always-available spaces.

{
  "alwaysopen": true,
  "calendarType": "ALWAYSOPEN"
}

No time slots or dates needed.

Pattern: On Request

For locations or events that require advance arrangement.

{
  "onrequest": true,
  "calendarType": "ONREQUEST"
}

Pattern: Single Dates

For events on specific individual dates. Each SingleDate has a date and an array of when time slots.

Example: a two-night concert

{
  "singleDates": [
    {
      "date": "2025-06-20T00:00:00",
      "when": [
        { "timestart": "20:00", "timeend": "23:00" }
      ]
    },
    {
      "date": "2025-06-21T00:00:00",
      "when": [
        { "timestart": "20:00", "timeend": "23:00" }
      ]
    }
  ],
  "calendarType": "SINGLEDATES"
}

A single date can have multiple time slots (e.g., morning and afternoon sessions):

{
  "date": "2025-07-01T00:00:00",
  "when": [
    { "timestart": "10:00", "timeend": "12:30" },
    { "timestart": "14:00", "timeend": "17:00" }
  ]
}

Pattern: Recurring (patternDates)

For regular, repeating schedules. Each PatternDate defines a recurrency type, an optional date range, and an array of opens entries specifying which days and times.

recurrencyType: daily

Every day (or every N days).

Example: daily opening hours for a pop-up shop running two weeks

{
  "patternDates": [
    {
      "startdate": "2025-07-01T00:00:00",
      "enddate": "2025-07-14T00:00:00",
      "recurrencyType": "daily",
      "recurrence": 1,
      "opens": [
        {
          "whens": [
            { "timestart": "10:00", "timeend": "18:00" }
          ]
        }
      ]
    }
  ],
  "calendarType": "PATTERNDATES"
}

recurrencyType: weekly

Specific days of the week. The most common pattern for regular opening hours.

Example: museum open Tuesday–Sunday, 10:00–17:00 (permanent hours)

{
  "patternDates": [
    {
      "recurrencyType": "weekly",
      "recurrence": 1,
      "opens": [
        { "day": 1, "whens": [{ "timestart": "10:00", "timeend": "17:00" }] },
        { "day": 3, "whens": [{ "timestart": "10:00", "timeend": "17:00" }] },
        { "day": 4, "whens": [{ "timestart": "10:00", "timeend": "17:00" }] },
        { "day": 5, "whens": [{ "timestart": "10:00", "timeend": "17:00" }] },
        { "day": 6, "whens": [{ "timestart": "10:00", "timeend": "17:00" }] },
        { "day": 7, "whens": [{ "timestart": "10:00", "timeend": "17:00" }] }
      ]
    }
  ],
  "calendarType": "OPENINGTIMES"
}

No startdate/enddate means these are permanent opening hours, so calendarType is OPENINGTIMES rather than PATTERNDATES.

recurrencyType: monthlySimple

Same day of the month each month.

Example: market on the 15th of every month, 08:00–14:00

{
  "patternDates": [
    {
      "startdate": "2025-01-15T00:00:00",
      "enddate": "2025-12-15T00:00:00",
      "recurrencyType": "monthlySimple",
      "recurrence": 1,
      "opens": [
        {
          "daynumber": 15,
          "whens": [{ "timestart": "08:00", "timeend": "14:00" }]
        }
      ]
    }
  ],
  "calendarType": "PATTERNDATES"
}

recurrencyType: monthlyComplex

A relative day in the month — e.g., "first Monday" or "last Friday".

Example: community meeting on the first Monday of every month

{
  "patternDates": [
    {
      "startdate": "2025-01-01T00:00:00",
      "enddate": "2025-12-31T00:00:00",
      "recurrencyType": "monthlyComplex",
      "recurrence": 1,
      "opens": [
        {
          "weeknumber": 1,
          "day": 2,
          "whens": [{ "timestart": "19:00", "timeend": "21:00" }]
        }
      ]
    }
  ],
  "calendarType": "PATTERNDATES"
}

weeknumber: 5 means "last week of the month."

recurrencyType: yearly

Annual events.

Example: Christmas market, December 25th every year

{
  "patternDates": [
    {
      "recurrencyType": "yearly",
      "recurrence": 1,
      "opens": [
        {
          "month": 12,
          "daynumber": 25,
          "whens": [{ "timestart": "10:00", "timeend": "20:00" }]
        }
      ]
    }
  ],
  "calendarType": "PATTERNDATES"
}

Exception Dates

Exception dates override the regular schedule for specific dates. The Calendar has four exception lists:

opens — Special opening dates

For dates that are unusually open (e.g., a museum normally closed on Mondays opens for a holiday).

{
  "opens": [
    {
      "date": "2025-04-21T00:00:00",
      "whens": [{ "timestart": "10:00", "timeend": "17:00" }]
    }
  ]
}

closeds — Closure dates

For dates when the location is exceptionally closed (holidays, maintenance).

{
  "closeds": [
    {
      "date": "2025-12-25T00:00:00",
      "whens": []
    }
  ]
}

soldouts — Sold-out dates

For dates when tickets or capacity is exhausted.

{
  "soldouts": [
    {
      "date": "2025-08-15T00:00:00",
      "whens": [{ "timestart": "20:00", "timeend": "23:00", "status": "soldout" }]
    }
  ]
}

cancelleds — Cancelled dates

For dates when a scheduled event is cancelled.

{
  "cancelleds": [
    {
      "date": "2025-09-01T00:00:00",
      "whens": [{ "timestart": "19:00", "timeend": "22:00", "status": "cancelled" }]
    }
  ]
}

calendarType Auto-Determination

The calendarType is set automatically based on the data present, using this priority order:

The first matching condition wins. If calendarType is already set on the object, the auto-determination does not overwrite it.

Booking URLs per Time Slot

Each When object can carry a urls array for per-slot booking links. This lets you attach a unique booking URL to a specific date and time.

{
  "singleDates": [
    {
      "date": "2025-07-10T00:00:00",
      "when": [
        {
          "timestart": "20:00",
          "timeend": "22:30",
          "urls": [
            {
              "url": "https://tickets.example.com/show-july-10",
              "urlServiceType": "booking",
              "reservations": true
            }
          ]
        }
      ]
    }
  ]
}

The urlServiceType of "booking" with reservations: true signals that this URL is a ticket/booking link for this specific time slot.

Related Schemas

• When — time slot with start/end times, status, and optional booking URLs
• SingleDate — a specific date with an array of When time slots
• PatternDate — a recurring pattern with recurrency type and Open entries
• Open — which days/times are included in a pattern (carries day, weeknumber, daynumber, month, whens)
• ExceptionDate — a date that overrides the regular schedule (carries date and whens)

See the API Reference for the full Calendar schema definition.