Read Available Periods

Description #

Returns a list of available periods for the authorized account.

The returned available periods will start before the given to Date and will end on or after the given from Date.

Example Request #

The parameters are encoded in the querystring as specified in appendix B of RFC 6749. Additional linebreaks are added to the request’s path for clarity.

GET /v1/available_periods?from={FROM_DATE}&to={TO_DATE}&tzid={TZID} HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}

Example Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "pages": {
    "current": 1,
    "total": 2,
    "next_page": "https://api.cronofy.com/v1/available_periods/pages/08a07b034306679e"
  },
  "available_periods": [
    {
      "available_period_id": "qTtZdczOccgaPncGJaCiLg",
      "start": "2024-11-19T15:30:00Z",
      "end": "2024-11-19T17:00:00Z"
    }
  ]
}

Request parameters #

from optional  #

The minimum Date from which to return available periods.

to optional  #

The Date to return available periods up until.

Note that the results will not include available periods occurring on this date.

tzid optional  #

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

• Etc/UTC
• Europe/Paris
• America/Chicago

It is recommended that you use the same tzid for all requests made for an individual user in order to ensure all their available periods are returned to you.

Required if specifying either from or to

localized_times optional  #

A Boolean specifying whether the available periods should have their start and end times returned with any available localization information.

If not provided the start and end times will be returned as simple Time values.

Response parameters #

pages.current  #

An Integer specifying which page of the result set the current request is for.

pages.total  #

An Integer specifying the total number of pages in the result set.

pages.next_page optional  #

When present, a String specifying the URL for the next page of results.

The next page of results can be retrieved by issuing a GET request to this URL and you will receive a response in the same format as a regular read events request.

available_periods.available_period_id  #

The available_period_id you specified when creating the available period.

available_periods.start  #

When localized_times is not specified or is false, the Time or Date representing when the available period starts.

When localized_times is true, an object with two attributes, time and tzid:

{
  "time": "2024-11-18T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date representing when the available period starts. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

• Etc/UTC
• Europe/Paris
• America/Chicago

available_periods.end  #

When localized_times is not specified or is false, the Time or Date by which the available period ends.

When localized_times is true, an object with two attributes, time and tzid:

{
  "time": "2024-11-18T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date by which the available period ends. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

• Etc/UTC
• Europe/Paris
• America/Chicago