Calendars

Payment-system and public-holiday calendars: business days and date arithmetic.

Operation	Summary
`GET /v1/calendars`	List the business-day calendars
`GET /v1/calendars/{calendar_ids}/add-business-days`	Add business days to a date
`GET /v1/calendars/{calendar_ids}/adjust`	Adjust a date to a business day
`GET /v1/calendars/{calendar_ids}/holidays`	List the holidays of a year
`GET /v1/calendars/{calendar_ids}/is-business-day`	Check whether a date is a business day
`GET /v1/calendars/{calendar_id}`	Get a calendar

`GET /v1/calendars`

List the business-day calendars

The available payment-system and public-holiday calendars.

data lists each calendar with its id (use it in the other calendar endpoints), jurisdiction, weekend days, the holiday rules and one-off adjustments the dates are generated from, the first date it answers for (coverage_from) and its sources. A jurisdiction with no calendar gives an empty list.


Authentication	an API key, where the server requires one
Operation id	`list_calendars_v1_calendars_get`

Parameters

In	Name	Type	Required	Description
query	`jurisdiction`	string or null		Only calendars that apply in this jurisdiction: its own, its parents' and its groups' (e.g. 'DE' -> eu.target2, 'US-CA' -> us.fedwire). ISO 3166 code, case-insensitive. Default: all calendars.
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/calendars" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_list_Calendar__`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": [
    {
      "sources": [
        null
      ],
      "id": "string",
      "name": "string",
      "jurisdiction": "string",
      "description": "string",
      "weekend": [
        "friday"
      ],
      "rules": [
        null
      ],
      "adjustments": [
        null
      ],
      "coverage_from": "2019-01-01",
      "ingest_source": "string",
      "notes": [
        "string"
      ]
    }
  ],
  "meta": {
    "dataset_version": "string",
    "as_of": "2026-09-21",
    "known_at": "2026-09-21",
    "sources": [
      {
        "authority": null,
        "url": null,
        "reference": null,
        "verified_at": null,
        "kind": null
      }
    ],
    "notes": [
      "string"
    ]
  }
}

`GET /v1/calendars/{calendar_ids}/add-business-days`

Add business days to a date

Move a date forwards or backwards by a number of business days.

Each step skips weekends and the holidays of every named calendar. The start date is not counted: one business day after a Wednesday is Thursday. data.result is the new date. 404 for an unknown calendar id; 422 for a date outside the coverage or days beyond +-2500.


Authentication	an API key, where the server requires one
Operation id	`add_business_days_v1_calendars__calendar_ids__add_business_days_get`

Parameters

In	Name	Type	Required	Description
path	`calendar_ids`	string	yes	A calendar id, or several separated by commas (business day in all of them), e.g. 'ch.six.sic,eu.target2'. Ids are in GET /v1/calendars; unknown ids give 404.
query	`date`	string (date)	yes	Start date (ISO 8601).
query	`days`	integer	yes	Business days to move; negative moves back. 0 returns the date if it is a business day, otherwise the next business day. Limited to +-2500.
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/calendars/ch.six.sic/add-business-days?date=2026-11-25&days=1" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_ShiftedDate_`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": {
    "calendars": [
      "us.fedwire"
    ],
    "date": "2026-11-25",
    "days": 1,
    "result": "2026-11-27"
  },
  "meta": {
    "dataset_version": "3f2a9c1b7d4e",
    "sources": [
      {
        "authority": "Board of Governors of the Federal Reserve System",
        "url": "https://www.federalreserve.gov/aboutthefed/k8.htm",
        "reference": "K.8 Holidays Observed by the Federal Reserve System 2026-2030",
        "verified_at": "2026-10-01",
        "kind": "official"
      }
    ],
    "notes": []
  }
}

`GET /v1/calendars/{calendar_ids}/adjust`

Adjust a date to a business day

Roll a due date or value date onto a business day.

A date that already is a business day is returned unchanged. Otherwise the convention decides the direction: following and modified_following roll forwards, preceding and modified_preceding backwards; the modified conventions go the other way when the first result would fall into another month. 404 for an unknown calendar id, 422 for a date outside the coverage.


Authentication	an API key, where the server requires one
Operation id	`adjust_v1_calendars__calendar_ids__adjust_get`

Parameters

In	Name	Type	Required	Description
path	`calendar_ids`	string	yes	A calendar id, or several separated by commas (business day in all of them), e.g. 'ch.six.sic,eu.target2'. Ids are in GET /v1/calendars; unknown ids give 404.
query	`date`	string (date)	yes	Date to adjust (ISO 8601).
query	`convention`	`"following"` \| `"modified_following"` \| `"modified_preceding"` \| `"preceding"`		Business day convention for a date that is not a business day: 'following', 'preceding', 'modified_following' (following unless that crosses into the next month) or 'modified_preceding'. Default 'following'. (default `"following"`)
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/calendars/ch.six.sic/adjust?date=2026-08-01" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_AdjustedDate_`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": {
    "calendars": [
      "ch.six.sic"
    ],
    "date": "2026-08-01",
    "convention": "following",
    "result": "2026-08-03"
  },
  "meta": {
    "dataset_version": "3f2a9c1b7d4e",
    "sources": [
      {
        "authority": "SIX Interbank Clearing",
        "url": "https://www.six-group.com/en/products-services/banking-services/interbank-clearing/online-services/clearing-day-calendar.html",
        "reference": "Clearing Day Calendar (CSV and API), service PCR_P (SIC CHF production)",
        "verified_at": "2026-10-01",
        "kind": "official"
      }
    ],
    "notes": []
  }
}

`GET /v1/calendars/{calendar_ids}/holidays`

List the holidays of a year

Holidays in a year. origin says whether a date comes from the publisher's feed or from the curated rules.

With several calendars data merges their holidays, sorted by date then calendar; each row names its calendar. 404 for an unknown calendar id, 422 for a year outside the coverage.


Authentication	an API key, where the server requires one
Operation id	`holidays_v1_calendars__calendar_ids__holidays_get`

Parameters

In	Name	Type	Required	Description
path	`calendar_ids`	string	yes	A calendar id, or several separated by commas (business day in all of them), e.g. 'ch.six.sic,eu.target2'. Ids are in GET /v1/calendars; unknown ids give 404.
query	`year`	integer or null		Calendar year, e.g. 2027. Defaults to the current year. Years before the calendar's coverage and after 2199 give 422.
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/calendars/ch.six.sic/holidays" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_list_Holiday__`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": [
    {
      "calendar": "gb.england_wales",
      "date": "2027-01-01",
      "name": "New Year's Day",
      "origin": "feed"
    },
    {
      "calendar": "gb.england_wales",
      "date": "2027-03-26",
      "name": "Good Friday",
      "origin": "feed"
    }
  ],
  "meta": {
    "dataset_version": "3f2a9c1b7d4e",
    "sources": [
      {
        "authority": "GOV.UK",
        "url": "https://www.gov.uk/bank-holidays",
        "reference": "UK bank holidays: England and Wales (also published as /bank-holidays.json)",
        "verified_at": "2026-10-01",
        "kind": "official"
      }
    ],
    "notes": []
  }
}

`GET /v1/calendars/{calendar_ids}/is-business-day`

Check whether a date is a business day

Whether a date is a business day in every named calendar, and why not.

data.business_day is false on a weekend or holiday of any of the calendars, and reasons names each calendar and the holiday or weekend. The nearest business days before and after are included for convenience. 404 for an unknown calendar id, 422 for a date before the calendar's coverage or after 2199.


Authentication	an API key, where the server requires one
Operation id	`is_business_day_v1_calendars__calendar_ids__is_business_day_get`

Parameters

In	Name	Type	Required	Description
path	`calendar_ids`	string	yes	A calendar id, or several separated by commas (business day in all of them), e.g. 'ch.six.sic,eu.target2'. Ids are in GET /v1/calendars; unknown ids give 404.
query	`date`	string (date)	yes	The date to check (ISO 8601).
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/calendars/ch.six.sic/is-business-day?date=2026-05-14" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_BusinessDay_`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": {
    "calendars": [
      "ch.six.sic",
      "eu.target2"
    ],
    "date": "2026-05-14",
    "business_day": false,
    "reasons": [
      "ch.six.sic: Ascension Day"
    ],
    "previous_business_day": "2026-05-13",
    "next_business_day": "2026-05-15"
  },
  "meta": {
    "dataset_version": "3f2a9c1b7d4e",
    "sources": [
      {
        "authority": "SIX Interbank Clearing",
        "url": "https://www.six-group.com/en/products-services/banking-services/interbank-clearing/online-services/clearing-day-calendar.html",
        "reference": "Clearing Day Calendar (CSV and API), service PCR_P (SIC CHF production)",
        "verified_at": "2026-10-01",
        "kind": "official"
      }
    ],
    "notes": []
  }
}

`GET /v1/calendars/{calendar_id}`

Get a calendar

One calendar with its holiday rules, one-off adjustments, weekend days and coverage.

meta.sources and meta.notes repeat the calendar's sources and notes. 404 for an unknown calendar id.


Authentication	an API key, where the server requires one
Operation id	`get_calendar_v1_calendars__calendar_id__get`

Parameters

In	Name	Type	Required	Description
path	`calendar_id`	string	yes	Calendar id, e.g. 'ch.six.sic' (see GET /v1/calendars).
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/calendars/ch.six.sic" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_Calendar_`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": {
    "sources": [
      {
        "authority": null,
        "url": null,
        "reference": null,
        "verified_at": null,
        "kind": null
      }
    ],
    "id": "string",
    "name": "string",
    "jurisdiction": "string",
    "description": "string",
    "weekend": [
      "friday"
    ],
    "rules": [
      {
        "name": null,
        "kind": null,
        "month": null,
        "day": null,
        "offset": null,
        "weekday": null,
        "nth": null,
        "observance": null,
        "from_year": null,
        "to_year": null
      }
    ],
    "adjustments": [
      {
        "date": null,
        "action": null,
        "name": null,
        "reference": null
      }
    ],
    "coverage_from": "2019-01-01",
    "ingest_source": "string",
    "notes": [
      "string"
    ]
  },
  "meta": {
    "dataset_version": "string",
    "as_of": "2026-09-21",
    "known_at": "2026-09-21",
    "sources": [
      {
        "authority": null,
        "url": null,
        "reference": null,
        "verified_at": null,
        "kind": null
      }
    ],
    "notes": [
      "string"
    ]
  }
}

Schemas

`AdjustedDate`

Field	Type	Required	Description
`calendars`	array of string	yes	The calendar ids the answer is for, as resolved.
`date`	string (date)	yes	The date that was adjusted (ISO 8601).
`convention`	`"following"` \| `"modified_following"` \| `"modified_preceding"` \| `"preceding"`	yes	The business day convention that was applied.
`result`	string (date)	yes	The adjusted date; equal to `date` when it already is a business day.

`BusinessDay`

Field	Type	Required	Description
`calendars`	array of string	yes	The calendar ids the answer is for, as resolved.
`date`	string (date)	yes	The date that was checked (ISO 8601).
`business_day`	boolean	yes	True if the date is a business day in every calendar.
`reasons`	array of string	yes	Why the date is not a business day, per calendar, e.g. 'ch.six.sic: Ascension Day' or 'eu.target2: weekend'. Empty for a business day.
`previous_business_day`	string (date) or null	yes	The last business day before the date, in all calendars. Null when it would fall before the calendar's coverage.
`next_business_day`	string (date) or null	yes	The first business day after the date, in all calendars. Null when it cannot be found (beyond the supported years).

`Calendar`

Field	Type	Required	Description
`sources`	array of `Source`	yes	Where the rules come from (at least one), e.g. the authority's page. (min items 1)
`id`	string	yes	Dotted slug: jurisdiction, publisher or system, e.g. 'ch.six.sic'. (pattern `^[a-z0-9_]+(\.[a-z0-9_]+)+$`)
`name`	string	yes	Name of the calendar, e.g. 'SIC clearing days (Swiss franc payments)'.
`jurisdiction`	string	yes	Jurisdiction or group, e.g. 'CH', 'EU'.
`description`	string	yes	What the calendar is for and who publishes it.
`weekend`	array of `"friday"` \| `"monday"` \| `"saturday"` \| `"sunday"` \| `"thursday"` \| `"tuesday"` \| `"wednesday"`		Weekdays that are never business days (default saturday and sunday).
`rules`	array of `HolidayRule`		Recurring holidays that generate dates for any year.
`adjustments`	array of `HolidayAdjustment`		One-off additions or removals the publisher announced for a year.
`coverage_from`	string (date)		First date the calendar answers for; earlier dates are rejected. (default `"2019-01-01"`)
`ingest_source`	string or null		Feed connector that stores the publisher's own list of dates. For years the feed covers its dates are used; the rules cover every other year.
`notes`	array of string		Caveats about the calendar's coverage or rules.

`Envelope_AdjustedDate_`

Field	Type	Required	Description
`data`	`AdjustedDate`	yes
`meta`	`Meta`	yes

`Envelope_BusinessDay_`

Field	Type	Required	Description
`data`	`BusinessDay`	yes
`meta`	`Meta`	yes

`Envelope_Calendar_`

Field	Type	Required	Description
`data`	`Calendar`	yes
`meta`	`Meta`	yes

`Envelope_ShiftedDate_`

Field	Type	Required	Description
`data`	`ShiftedDate`	yes
`meta`	`Meta`	yes

`Envelope_list_Calendar__`

Field	Type	Required	Description
`data`	array of `Calendar`	yes
`meta`	`Meta`	yes

`Envelope_list_Holiday__`

Field	Type	Required	Description
`data`	array of `Holiday`	yes
`meta`	`Meta`	yes

`Holiday`

Field	Type	Required	Description
`calendar`	string	yes	Id of the calendar the holiday belongs to.
`date`	string (date)	yes	The holiday (ISO 8601).
`name`	string	yes	Name of the holiday, e.g. 'Good Friday'.
`origin`	`"adjustment"` \| `"feed"` \| `"rule"`	yes	'rule' or 'adjustment': generated from the curated calendar; 'feed': the publisher's own list.

`HolidayAdjustment`

A one-off change the publisher announced: an extra closing day, or a rule date that does not apply in that year (a moved holiday is a removal plus an addition).

Field	Type	Required	Description
`date`	string (date)	yes	The date affected (ISO 8601).
`action`	`"add"` \| `"remove"`	yes	'add': an extra closing day; 'remove': a rule date that does not apply.
`name`	string	yes	Name of the added holiday, or of the removed rule date.
`reference`	string or null		Announcement or legal basis.

`HolidayRule`

One recurring holiday.

fixed: month and day (25 December).
easter: offset days from Western (Gregorian) Easter Sunday; Good Friday is -2.
nth_weekday: the nth weekday of month; nth: -1 is the last one.

observance says what happens when the date falls on a weekend:

none: nothing; the day is simply not an extra closing day.
sunday_to_monday: a Sunday holiday closes the following Monday (US Federal Reserve Banks; a Saturday holiday does not close the Friday).
substitute_weekday: the next weekday that is not already a holiday is a substitute day (UK bank holidays: Christmas on Saturday moves to Monday and Boxing Day on Sunday to Tuesday).

Field	Type	Required	Description
`name`	string	yes	Name of the holiday, e.g. 'Good Friday'.
`kind`	`"easter"` \| `"fixed"` \| `"nth_weekday"`	yes	How the date is derived: fixed (month and day), easter (offset from Easter Sunday) or nth_weekday (nth weekday of a month).
`month`	integer or null		Month 1-12 (fixed and nth_weekday rules). (min 1; max 12)
`day`	integer or null		Day of the month (fixed rules). (min 1; max 31)
`offset`	integer or null		Days from Easter Sunday.
`weekday`	`"friday"` \| `"monday"` \| `"saturday"` \| `"sunday"` \| `"thursday"` \| `"tuesday"` \| `"wednesday"` or null		Weekday name in lower case (nth_weekday rules).
`nth`	integer or null		1-4, or -1 for the last. (min -1; max 4)
`observance`	`"none"` \| `"substitute_weekday"` \| `"sunday_to_monday"`		What happens when the date falls on a weekend: none, sunday_to_monday or substitute_weekday. (default `"none"`)
`from_year`	integer or null		First year the rule applies.
`to_year`	integer or null		Last year the rule applies.

`ShiftedDate`

Field	Type	Required	Description
`calendars`	array of string	yes	The calendar ids the answer is for, as resolved.
`date`	string (date)	yes	The start date (ISO 8601).
`days`	integer	yes	Business days moved; negative means backwards.
`result`	string (date)	yes	The resulting business day (ISO 8601).