# Trading Hours

# Trading Hours API

The Trading Hours API endpoint allows you to see the full trading schedule for a market on a given day.

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.

Note

Our pricing is structured around what data you need. This results in different plans with different levels of access. The Trading Hours API is not available on all plans. Contact our team for more details (opens new window).

Notice

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

# Schema

Field Format Description
date Datetime 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 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"
      }
    ]
  }
}

# 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
    }
  ]
}