Trading Hours

Overview

There are three API endpoints that provide information on market trading hours. The endpoints provide the same information in different formats. Each endpoint is designed for a different use-case.

The APIs are:

  1. Single-Day Trading Hours API
  2. Multiple-Day Trading Hours API
  3. Simplified Trading Hours API

The sections below will explain the intended use-case for each API.

Notice

Unlike our other API endpoints, the trading hours endpoints do not support CSV format or multiple FinIDs. This is due to the nested structure of the API results.

Single-Day Trading Hours API

The Single-Day Trading Hours API endpoint allows you to see the full trading schedule for a market on a specific date. The API returns detailed information containing the start and end times for all trading phases throughout the day.

Some markets have overnight trading. This endpoint will return all trading phases that overlap the specified date even if the trading phase starts on the previous day or ends on the following day. When working with markets that have overnight trading schedules we recommend you use the Multi-Day Trading Hours API.

You can specify a particular date by passing the date query string parameter. The date format must be yyyy-mm-dd. If the date parameter is omitted, the current date is used.

The date will always be converted into the timezone of the specified market.

Response Schema

FieldFormatDescription
dateDateThe date for the data returned.
day_of_weekStringThe day of the week for the data returned.
is_openBooleanDescribes in true/false statement if the market is open.
has_settlementBooleanDescribes in true/false statement if the market has settlement.
holidayStringDescribes the holiday, if any.
scheduleSee schema belowNested data of the schedule.

Schedule Schema (Part of Response)

FieldFormatDescription
phase_typeStructured FieldThe options for this field are Primary Trading Session, Pre-Trading Session, Post-Trading Session, Pre-Open, Pre-Close, Call Auction, Intermission, Trading-at-Last, and Other. Primary Trading Session is the only session type that is considered "open". phase_name is free-form and will match the terminology used by the market itself.
phase_nameStringDescribes the name for the phase type.
phase_memoStringIf applicable, will have additional description or information.
statusStringDescribes what status the market is currently.
startISO 8601The date the market phase type started.
endISO 8601The scheduled date for the market phase type to end.

Query String Parameters

Supported query string parameters are listed in the table below:

ParameterSupported ValuesDefaultDescription
fin_idValid FinIDN/ASpecify which market to show data for.
dateyyyy-mm-ddCurrent DateSpecifies the date of the information.

Examples

Remember to use your authentication token for all requests.

Get Full Trading Schedule with FinID

https://api.tradinghours.com/v3/markets/hours?fin_id=us.nyse

Get Full Trading Schedule with MIC

https://api.tradinghours.com/v3/markets/hours?fin_id=XNYS

Get Trading Schedule for Particular Date

https://api.tradinghours.com/v3/markets/hours?fin_id=us.nyse&date=2020-12-24

Sample JSON Responses

{
  "data": {
    "date": "2020-09-24",
    "day_of_week": "Thursday",
    "is_open": true,
    "has_settlement": true,
    "holiday": null,
    "schedule": [
      {
        "phase_type": "Pre-Trading Session",
        "phase_name": "Pre-Trading Session",
        "phase_memo": null,
        "status": "Closed",
        "start": "2020-09-24T04:00:00-04:00",
        "end": "2020-09-24T09:30:00-04:00"
      },
      {
        "phase_type": "Pre-Open",
        "phase_name": "Pre-Opening Session",
        "phase_memo": null,
        "status": "Closed",
        "start": "2020-09-24T06:30:00-04:00",
        "end": "2020-09-24T09:30:00-04:00"
      },
      {
        "phase_type": "Call Auction",
        "phase_name": "Core Open Auction",
        "phase_memo": null,
        "status": "Closed",
        "start": "2020-09-24T09:30:00-04:00",
        "end": "2020-09-24T09:30:00-04:00"
      },
      {
        "phase_type": "Primary Trading Session",
        "phase_name": "Core Trading Session",
        "phase_memo": null,
        "status": "Open",
        "start": "2020-09-24T09:30:00-04:00",
        "end": "2020-09-24T16:00:00-04:00"
      },
      {
        "phase_type": "Pre-Close",
        "phase_name": "Closing Imbalance Period",
        "phase_memo": null,
        "status": "Closed",
        "start": "2020-09-24T15:45:00-04:00",
        "end": "2020-09-24T16:00:00-04:00"
      },
      {
        "phase_type": "Post-Trading Session",
        "phase_name": "Extended Hours",
        "phase_memo": null,
        "status": "Closed",
        "start": "2020-09-24T16:00:00-04:00",
        "end": "2020-09-24T20:00:00-04:00"
      }
    ]
  }
}
{
  "data": {
    "date": "2020-12-24",
    "day_of_week": "Thursday",
    "is_open": true,
    "has_settlement": true,
    "holiday": "Christmas",
    "schedule": [
      {
        "phase_type": "Pre-Trading Session",
        "phase_name": "Pre-Opening Session",
        "phase_memo": null,
        "status": "Closed",
        "start": "2020-12-24T06:30:00-05:00",
        "end": "2020-12-24T09:30:00-05:00"
      },
      {
        "phase_type": "Primary Trading Session",
        "phase_name": "Core Trading Session",
        "phase_memo": null,
        "status": "Open",
        "start": "2020-12-24T09:30:00-05:00",
        "end": "2020-12-24T13:00:00-05:00"
      },
      {
        "phase_type": "Post-Trading Session",
        "phase_name": "Crossing Session",
        "phase_memo": null,
        "status": "Closed",
        "start": "2020-12-24T13:00:00-05:00",
        "end": "2020-12-24T13:30:00-05:00"
      }
    ]
  }
}

Multiple-Day Trading Hours API

The Multiple-Day Trading Hours API is intended for use with markets that have overnight trading phases. This endpoint will return all trading phases between the specified start and end dates.

Only certain derivative markets have overnight trading phases. Equity markets do not have overnight trading.

Single-Day Trading Hours API returns all trading phases on a particular date, including phases that start the previous day or end the following day. If there is an overnight phase, that phase will be included in the response for both days. This duplication can be difficult to work with. The Multiple-Day Trading Hours API avoids this problem.

Schema

FieldFormatDescription
startDateThe start date for the data returned.
endDateThe end date for the data returned.
scheduleSee schema belowNested data of the schedule.

Schedule Schema (Part of Response)

FieldFormatDescription
phase_typeStructured FieldThe options for this field are Primary Trading Session, Pre-Trading Session, Post-Trading Session, Pre-Open, Pre-Close, Call Auction, Intermission, Trading-at-Last, and Other. Primary Trading Session is the only session type that is considered "open". phase_name is free-form and will match the terminology used by the market itself.
phase_nameStringDescribes the name for the phase type.
phase_memoStringIf applicable, will have additional description or information.
statusStringDescribes what status the market is currently.
startISO 8601The date the market phase type started.
endISO 8601The scheduled date for the market phase type to end.

Query String Parameters

Supported query string parameters are listed in the table below:

ParameterSupported ValuesDefaultDescription
fin_idValid FinIDN/ASpecify which market to show data for.
startyyyy-mm-ddN/ASpecifies the start date of the information.
endyyyy-mm-ddN/ASpecifies the end date of the information. Max 7 days after start date.

Examples

Remember to use your authentication token for all requests.

Get Trading Schedule for Date Range

https://api.tradinghours.com/v3/markets/hours-multiday?fin_id=jp.jpx.indextop3&start=2022-02-20&end=2022-02-27

Sample JSON Response

{
  "data": {
    "start": "2022-02-20",
    "end": "2022-02-27",
    "schedule": [
      {
        "phase_type": "Pre-Close",
        "phase_name": "Pre Closing",
        "phase_memo": null,
        "status": "Closed",
        "start": "2022-02-21T05:25:00+09:00",
        "end": "2022-02-21T05:29:00+09:00"
      },
      {
        "phase_type": "Other",
        "phase_name": "No-Cancel",
        "phase_memo": null,
        "status": "Closed",
        "start": "2022-02-21T05:29:00+09:00",
        "end": "2022-02-21T05:30:00+09:00"
      },
      {
        "phase_type": "Call Auction",
        "phase_name": "Closing Auction",
        "phase_memo": null,
        "status": "Closed",
        "start": "2022-02-21T05:30:00+09:00",
        "end": "2022-02-21T05:30:00+09:00"
      },
      {
        "phase_type": "Pre-Open",
        "phase_name": "Pre-Opening",
        "phase_memo": null,
        "status": "Closed",
        "start": "2022-02-21T08:00:00+09:00",
        "end": "2022-02-21T08:44:00+09:00"
      },
      {
        "phase_type": "Other",
        "phase_name": "No-Cancel",
        "phase_memo": null,
        "status": "Closed",
        "start": "2022-02-21T08:44:00+09:00",
        "end": "2022-02-21T08:45:00+09:00"
      },
      ...
    ]
  }
}

Simplified Trading Hours API

Sometimes, you don't need information on every trading phase.

If you just want to know the regular trading hours, pre-trading hours, and post-trading hours, you can use the Simplified Trading Hours API Endpoint.

Overnight Trading Sessions

Some markets have overnight trading sessions. To represent this in the API, we use what we call "24hr+ time". In some cases, the end time may exceed 24:00. This indicates that the market closes the following day.

For example, if the start time is 16:00 and the end time is 32:00, the market opens at 4:00 pm and closes the next day at 8:00 am.

Schema

FieldFormatDescription
dayStringDay of the week in string format.
openBooleanDescribes if the market is open in true/false.
time_startTimeDescribes the time the market trading session opens.
time_endTimeDescribes the time the market trading session ends.
lunchBooleanDescribes if the market has observed lunch hours in true/false.
lunch_startTimeIf observed lunch hours, this describes when lunch hours start.
lunch_endTimeIf observing lunch hours, this describes when lunch hours end.
pre_hours_startTimeIf pre-hours, describes what time they start.
pre_hours_endTimeIf pre-hours, describes what time they end.
post_hours_startTimeIf post-hours, describes what time they start.
post_hours_endTimeIf post-hours, describes what time they end.

Query String Parameters

Supported query string parameters are listed in the table below:

ParameterSupported ValuesDefaultDescription
fin_idValid FinIDN/ASpecify which market to show data for.

If you use a query string parameter that isn't supported, the API will ignore the invalid query string parameters and execute the ones it recognizes.

Examples

Remember to use your authentication token for all requests.

Get Simplified Trading Hours for FinID

https://api.tradinghours.com/v3/markets/hours-simplified?fin_id=us.nyse

Get Simplified Trading Hours for MIC

https://api.tradinghours.com/v3/markets/hours-simplified?fin_id=XNYS

Get Simplified Trading Hours for FinID

https://api.tradinghours.com/v3/markets/hours-simplified?fin_id=JP.JPX.INDEXSPECIAL

Sample JSON Response

{
  "data": [
    {
      "day": "Sunday",
      "open": false,
      "time_start": null,
      "time_end": null,
      "lunch": false,
      "lunch_start": null,
      "lunch_end": null,
      "pre_hours_start": null,
      "pre_hours_end": null,
      "post_hours_start": null,
      "post_hours_end": null
    },
    {
      "day": "Monday",
      "open": true,
      "time_start": "09:30",
      "time_end": "16:00",
      "lunch": false,
      "lunch_start": null,
      "lunch_end": null,
      "pre_hours_start": "04:00",
      "pre_hours_end": "09:30",
      "post_hours_start": "16:00",
      "post_hours_end": "20:00"
    },
    {
      "day": "Tuesday",
      "open": true,
      "time_start": "09:30",
      "time_end": "16:00",
      "lunch": false,
      "lunch_start": null,
      "lunch_end": null,
      "pre_hours_start": "04:00",
      "pre_hours_end": "09:30",
      "post_hours_start": "16:00",
      "post_hours_end": "20:00"
    },
    {
      "day": "Wednesday",
      "open": true,
      "time_start": "09:30",
      "time_end": "16:00",
      "lunch": false,
      "lunch_start": null,
      "lunch_end": null,
      "pre_hours_start": "04:00",
      "pre_hours_end": "09:30",
      "post_hours_start": "16:00",
      "post_hours_end": "20:00"
    },
    {
      "day": "Thursday",
      "open": true,
      "time_start": "09:30",
      "time_end": "16:00",
      "lunch": false,
      "lunch_start": null,
      "lunch_end": null,
      "pre_hours_start": "04:00",
      "pre_hours_end": "09:30",
      "post_hours_start": "16:00",
      "post_hours_end": "20:00"
    },
    {
      "day": "Friday",
      "open": true,
      "time_start": "09:30",
      "time_end": "16:00",
      "lunch": false,
      "lunch_start": null,
      "lunch_end": null,
      "pre_hours_start": "04:00",
      "pre_hours_end": "09:30",
      "post_hours_start": "16:00",
      "post_hours_end": "20:00"
    },
    {
      "day": "Saturday",
      "open": false,
      "time_start": null,
      "time_end": null,
      "lunch": false,
      "lunch_start": null,
      "lunch_end": null,
      "pre_hours_start": null,
      "pre_hours_end": null,
      "post_hours_start": null,
      "post_hours_end": null
    }
  ]
}