# Trading Hours

Overview
Single-Day Trading Hours API
Multiple-Day Trading Hours API
Simplified Trading Hours API

# 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-cases.

The APIs are:

Single-Day Trading Hours API
Multiple-Day Trading Hours API
Simplified Trading Hours API

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

Note

Our pricing is structured so you only pay for what you need. Accordingly, the Trading Hours API is not available on all plans. Contact our team for more details (opens new window).

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

Field	Format	Description
date	Date	The date for the data returned.
day_of_week	String	The day of the week for the data returned.
is_open	Boolean	Describes in true/false statement if the market is open.
has_settlement	Boolean	Describes in true/false statement if the market has settlement.
holiday	String	Describes the holiday, if any.
schedule	See schema below	Nested data of the schedule.

# Schedule Schema (Part of Response)

Field	Format	Description
phase_type	Structured Field	The 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_name	String	Describes the name for the phase type.
phase_memo	String	If applicable, will have additional description or information.
status	String	Describes what status the market is currently.
start	ISO 8601	The date the market phase type started.
end	ISO 8601	The scheduled date for the market phase type to end.

# Query String Parameters

Supported query string parameters are listed in the table below:

Parameter	Supported Values	Default	Description
fin_id	Valid FinID	N/A	Specify which market to show data for.
date	yyyy-mm-dd	Current Date	Specifies the date of the information.

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 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

Field	Format	Description
start	Date	The start date for the data returned.
end	Date	The end date for the data returned.
schedule	See schema below	Nested data of the schedule.

# Schedule Schema (Part of Response)

Field	Format	Description
phase_type	Structured Field	The 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_name	String	Describes the name for the phase type.
phase_memo	String	If applicable, will have additional description or information.
status	String	Describes what status the market is currently.
start	ISO 8601	The date the market phase type started.
end	ISO 8601	The scheduled date for the market phase type to end.

# Query String Parameters

Supported query string parameters are listed in the table below:

Parameter	Supported Values	Default	Description
fin_id	Valid FinID	N/A	Specify which market to show data for.
start	yyyy-mm-dd	N/A	Specifies the start date of the information.
end	yyyy-mm-dd	N/A	Specifies 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

Field	Format	Description
day	String	Day of the week in string format.
open	Boolean	Describes if the market is open in true/false.
time_start	Time	Describes the time the market trading session opens.
time_end	Time	Describes the time the market trading session ends.
lunch	Boolean	Describes if the market has observed lunch hours in true/false.
lunch_start	Time	If observed lunch hours, this describes when lunch hours start.
lunch_end	Time	If observing lunch hours, this describes when lunch hours end.
pre_hours_start	Time	If pre-hours, describes what time they start.
pre_hours_end	Time	If pre-hours, describes what time they end.
post_hours_start	Time	If post-hours, describes what time they start.
post_hours_end	Time	If post-hours, describes what time they end.

# Query String Parameters

Supported query string parameters are listed in the table below:

Parameter	Supported Values	Default	Description
fin_id	Valid FinID	N/A	Specify 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
    }
  ]
}

← Market Status (Enterprise) Market Holidays →

# Trading Hours

# Overview

# Single-Day Trading Hours API

# Response Schema

# Schedule Schema (Part of Response)

# Query String Parameters

# Examples

# Get Full Trading Schedule with FinID

# Get Full Trading Schedule with MIC

# Get Trading Schedule for Particular Date

# Sample JSON Responses

# Multiple-Day Trading Hours API

# Schema

# Schedule Schema (Part of Response)

# Query String Parameters

# Examples

# Get Trading Schedule for Date Range

# Sample JSON Response

# Simplified Trading Hours API

# Schema

# Query String Parameters

# Examples

# Get Simplified Trading Hours for FinID

# Get Simplified Trading Hours for MIC

# Get Simplified Trading Hours for FinID

# Sample JSON Response

# Get Full Trading Schedule with `FinID`

# Get Full Trading Schedule with `MIC`

# Get Simplified Trading Hours for `FinID`

# Get Simplified Trading Hours for `MIC`

# Get Simplified Trading Hours for `FinID`