StockMarketClock API

Welcome to the stock market clock API. We offer a Real-Time Stock Market Status API (v1) and a Stock Market Holidays & Trading Hours API (v2). API v2 gives you complete access to passed and future market holidays, regular market trading hours, and general information about each exchange.

You can sign up for access to API v1 here. If you want access to the full Market Holidays and Trading Hours API (v2) please contact our sales team.

Authentication

All endpoints require a valid API key. Visit your account settings to start a subscription and get your API key.

All requests must include your API key in a parameter called api_token. In the examples below we omit the api_token parameter but it is required.

You must have an active subscription before your API key will work.

Replace {YourApiTokenHere} with your token itself, not the token's name. E.g. VnZPKHByMhtH1s1s0nLYan3xAmpLEdOGzVpCVx2BK1.

Create your API key here.

Example

GET
https://www.stockmarketclock.com/api-v1/status?exchange=nyse&api_token={YourApiTokenHere}

Real-Time Market Status

This API gives you information about the real-time status of an stock exchange. You can see if a market is currently open or closed.

List Markets

List the ids for all available exchanges. Use these codes to specify a market in other requests.

GET
/api-v1/list

Example request

$ curl https://www.stockmarketclock.com/api-v1/list

Example response

{
    "results": [
        "adx",
        "aim",
        "amex",
        "ase-amman",
        "ase-athens",
        "asx",
        "bc",
        "bcba",
        "bde-barbados",
        "bhb",
        ...
    ]
}

Get Status

Returns the real-time stock exchange open/closed status

Request Parameters

Parameters Description
exchange (required) comma-separated list of exchange ids

Response Properties

Property Description
name Full name of the market
status Market status (open or closed)
reason Indicates if the market is closed for a holiday
until The time when the current status will change
timezone The timezone of the market
GET
/api-v1/status

Example request

$ https://www.stockmarketclock.com/api-v1/status?exchange=nyse,jpx

Example response

{
    "results": {
        "nyse": {
            "name": "New York Stock Exchange",
            "status": "open",
            "reason": null,
            "until": "Wed, 13 Mar 2019 20:00:00 +0000",
            "timezone": "America/New_York"
        },
        "jpx": {
            "name": "Tokyo Stock Exchange",
            "status": "closed",
            "reason": null,
            "until": "Thu, 14 Mar 2019 00:00:00 +0000",
            "timezone": "Asia/Tokyo"
        }
    }
}

Trading Hours & Market Holidays

Get passed and future holidays, regular trading hours, and general information about any supported market. Please contact our sales team to access the Trading Hours & Market Holidays API and get a free 30-day trial.

List Markets

List all available markets with their full name and unique ID.

Response Properties

Property Description
name Full name of the market
code MIC code for the market. This is a unique code. Use this code in all other requests to specify a market.
operating_mic Operating MIC for the exchange. If code is different than Operating MIC then this entry is a market segment.

You can learn more about MICs, "Operating MICs," and "Market Segments" on the ISO 10383 FAQ.

GET
/api-v2/markets

Example request

$ curl https://www.stockmarketclock.com/api-v2/markets

Example response

[
    {
        "name": "New York Stock Exchange",
        "code": "XNYS",
        "operating_mic": "XNYS"
    },
    {
        "name": "NASDAQ Stock Exchange",
        "code": "XNAS",
        "operating_mic": "XNAS"
    },
    {
        "name": "London Stock Exchange",
        "code": "XLON",
        "operating_mic": "XLON"
    },
    {
        "name": "Tokyo Stock Exchange",
        "code": "XJPX",
        "operating_mic": "XJPX"
    },
    {
        "name": "Shanghai Stock Exchange",
        "code": "XSHG",
        "operating_mic": "XSHG"
    },
    {
        "name": "Hong Kong Stock Exchange",
        "code": "XHKG",
        "operating_mic": "XHKG"
    },
      ...
]

Market Details

Get general information about a market.

Request Parameters

Parameters Description
code (required) Unique identifier for the market

Response Properties

Property Description
name Full name of the market
code MIC code for the market. This is a unique identifier. Use this code in all other requests to specify a market.
operating_mic Operating MIC for the exchange. If code is different than Operating MIC then this entry is a market segment.
country Country of the market
country_code 2-letter country code
continent Continent of the market
website Official website for the market
currency Currency of the market
timezone The timezone of the market
GET
/api-v2/markets/{code}

Example request

$ curl https://www.stockmarketclock.com/api-v2/markets/xnys

Example response

{
    "name": "New York Stock Exchange",
    "code": "XNYS",
    "operating_mic": "XNYS",
    "country": "United States",
    "country_code": "US",
    "city": "New York",
    "continent": "North America",
    "website": "www.nyse.com",
    "currency": "USD",
    "timezone": "America/New_York"
}

Market Trading Hours

Get the regular trading hours for the market.

Request Parameters

Parameters Description
code (required) Unique identifier for the market

Response Properties

Property Description
code Unique identifier
open Indicates if the market is open that day. "1" for open, "0" for closed.
time_start Time the market opens
time_end Time the market closes
lunch Whether or not the market closes for lunch. "1" for yes, "0" for no.
lunch_start Time lunch break starts
lunch_end Time lunch break ends
pre_hours_start Start of pre-trading (Not available for all markets)
pre_hours_end End of pre-trading (Not available for all markets)
post_hours_start Start of after-hours trading (Not available for all markets)
post_hours_end End of after-hour trading (Not available for all markets)
GET
/api-v2/markets/{code}/hours

Example request

$ curl https://www.stockmarketclock.com/api-v2/markets/xnys/hours

Example response

{
    "code": "XNYS",
    "hours": [
        {
            "day": "Saturday",
            "open": 0,
            "time_start": "",
            "time_end": "",
            "lunch": 0,
            "lunch_start": "",
            "lunch_end": "",
            "pre_hours_start": "",
            "pre_hours_end": "",
            "post_hours_start": "",
            "post_hours_end": ""
        },
        {
            "day": "Monday",
            "open": 1,
            "time_start": "9:30",
            "time_end": "16:00",
            "lunch": 0,
            "lunch_start": "",
            "lunch_end": "",
            "pre_hours_start": "4:00",
            "pre_hours_end": "9:30",
            "post_hours_start": "16:00",
            "post_hours_end": "20:00"
        },
        {
            "day": "Tuesday",
            "open": 1,
            "time_start": "9:30",
            "time_end": "16:00",
            "lunch": 0,
            "lunch_start": "",
            "lunch_end": "",
            "pre_hours_start": "4:00",
            "pre_hours_end": "9:30",
            "post_hours_start": "16:00",
            "post_hours_end": "20:00"
        },
        ...
    }
]

Market Holidays (List Available Years)

Get all the available years for a given market.

Request Parameters

Parameters Description
code (required) Unique identifier for the market
GET
/api-v2/markets/{code}/holidays

Example request

$ curl https://www.stockmarketclock.com/api-v2/markets/xnys/holidays

Example response

{
    "code": "xnys",
    "years": [
        2016,
        2017,
        2018,
        2019,
        2020,
        2021
    ]
}

Market Holidays

Get market holidays for a given market and year.

Request Parameters

Parameters Description
code (required) Unique identifier for the market
year (required) Which year to return

Response Properties

Property Description
code Unique identifier
holiday Name of the holiday
date Date the holiday is observed
observed Indicates if the market closes on a different day than the official holiday
open Whether or not the market is open for a half-day. "1" for half-day, "0" for closed.
time_start Time the market opens (if open for half-day)
time_end Time the market closes (if open for half-day)
GET
/api-v2/markets/{code}/holidays/{year}

Example request

$ curl https://www.stockmarketclock.com/api-v2/markets/xnys/holidays

Example response

{
  "code": "xnys",
  "year": "2019",
  "holidays": [
    {
      "holiday": "New Year's Day",
      "date": "2019-01-01",
      "observed": 0,
      "open": 0,
      "time_start": null,
      "time_end": null
    },
    {
      "holiday": "Martin Luther King, Jr. Day",
      "date": "2019-01-21",
      "observed": 0,
      "open": 0,
      "time_start": null,
      "time_end": null
    },
    {
      "holiday": "Washington's Birthday",
      "date": "2019-02-18",
      "observed": 0,
      "open": 0,
      "time_start": null,
      "time_end": null
    },
    {
      "holiday": "Good Friday",
      "date": "2019-04-19",
      "observed": 0,
      "open": 0,
      "time_start": null,
      "time_end": null
    },
    {
      "holiday": "Memorial Day",
      "date": "2019-05-27",
      "observed": 0,
      "open": 0,
      "time_start": null,
      "time_end": null
    },
    {
      "holiday": "Independence Day",
      "date": "2019-07-03",
      "observed": 1,
      "open": 1,
      "time_start": "9:30",
      "time_end": "13:00"
    },
    {
      "holiday": "Independence Day",
      "date": "2019-07-04",
      "observed": 0,
      "open": 0,
      "time_start": null,
      "time_end": null
    },
    {
      "holiday": "Labor Day",
      "date": "2019-09-02",
      "observed": 0,
      "open": 0,
      "time_start": null,
      "time_end": null
    },
    {
      "holiday": "Thanksgiving Day",
      "date": "2019-11-28",
      "observed": 0,
      "open": 0,
      "time_start": null,
      "time_end": null
    },
    {
      "holiday": "Thanksgiving Day",
      "date": "2019-11-29",
      "observed": 1,
      "open": 1,
      "time_start": "9:30",
      "time_end": "13:00"
    },
    {
      "holiday": "Christmas Day",
      "date": "2019-12-24",
      "observed": 1,
      "open": 1,
      "time_start": "9:30",
      "time_end": "13:00"
    },
    {
      "holiday": "Christmas Day",
      "date": "2019-12-25",
      "observed": 0,
      "open": 0,
      "time_start": null,
      "time_end": null
    }
  ]
}
Show examples in:
StockMarketClock API Docs