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