Image Charts Documentation

Image Charts - v1.1

Current Version

Released September 2018

v1.1 is the current stable release. The APIs are located here:

https://api.markitondemand.com/apiman-gateway/MOD/chartworks-image/1/Chart/price
https://api.markitondemand.com/apiman-gateway/MOD/chartworks-image/1/Chart/sparkLine

See the Change Log for previous versions.

What's New

The v1.1 release has a number of new inputs added to the price chart. With v1.1 we have also dropped the minor version from the API path. Moving forward, version bumps in the API path will only be for major breaking changes; all other changes will be backwards compatible. The /1.0/ API will continue to work but we encourage you to update to the new /1/ path.

  • Minor version was dropped from the API path.
  • Added new input params chartType and priceFillColor to the Price Chart allowing for area charts.
  • New percentChange input param for the Price Chart that when set to true shows a percent change chart.
  • Ability to add comparison symbols to the chart through compareSymbols.
  • General bug fixes

See the Change Log for previous versions.

Authentication

Before jumping into the docs make sure you understand Authentication. In the below examples we will be using demo-token as our demo authentication token. Each time any of the APIs are called this token is required to be passed as either a parameter on the URL or in the Header. This CodePen shows the two auth methods in action:

Details on how to generate a real authentication token can be found in the Authentication section. Our demo-token is only entitled for delayed data for the following securities:

  • Apple Inc (symbol: AAPL) trading on the NASDAQ
  • Microsoft (symbol: MSFT) trading on the NASDAQ

Requests to chart any other securities will fail.

Price Charts

Price charts are more detailed images with both x and y axis labels and optionally showing volume as a lower indicator.

Minimum Example

The CodePen shows the minimum inputs need to generate a price chart:

Full Example

The CodePen shows all the available inputs for a price chart:

API URL & Structure

The price chart API URL is:

https://api.markitondemand.com/apiman-gateway/MOD/chartworks-image-charts/1/imagecharts/price

The API version is contained in the URL path. Only the major version is included in the path.

Chart inputs are contained in the inputs URL parameter and consists of an URL encoded object. A final API URL would look like this:

https://api.markitondemand.com/apiman-gateway/MOD/chartworks-image/1/Chart/price?inputs=%7B%22symbol%22%3A%22AAPL%22%2C%22exchange%22%3A%22NSQ%22%7D&access_token=demo-token

See the API Inputs section for a full list of Price Chart inputs. The above CodePens also provide good examples of the API inputs.

API Inputs

Note: All images are returned with a transparent background.

chartType

string: optional

Description: Marker style used for the price chart.

Accepted Inputs:

  • "line" for line chart
  • "area" for area chart (see priceFillColor for fill color options)

Default: "line"

Example

"chartType": "area"

compareSymbols

JSON array: optional

Description: When passed a JSON array the symbols in the JSON array are loaded as comparisons in the chart.

Default: NULL

JSON Inputs for compareSymbols

The compareSymbols param accepts a JSON array composed of the following parameters:

symbol

string: required

The symbol that is to be charted as a comparison. See Symbology for more details.

exchange

string: optional/required

The exchange code for the symbol that is to be charted as a comparison. This input is required if you are utilizing the Exchange Symbol + Exchange Code as your symbol set; otherwise it is optional. See Symbology for more details.

priceLineColor

string: optional

Hex color of the comparison price line.

priceLineWidth

int: optional

Width in pixels of the comparison price line.

Example

"compareSymbols": [{
    "symbol": "SPY",
    "exchange": "NYSE",
    "priceLineColor": "#f18700",
    "priceLineWidth": 4
}, {
    "symbol": "MSFT",
    "exchange": "NSQ",
    "priceLineColor": "#fcd32e",
    "priceLineWidth": 4
}]

cultureCode

string: optional

Description: Localized language and number/date formats.

Accepted Inputs:

  • "en-US" for English (United States) [default]
  • "en-AU" for English (Australia)
  • "en-GB" for English (United Kingdom)
  • "fr-CA" for French (Canada)

Default: "en-US"

Example

"cultureCode": "en-US"

exchange

string: required/optional

Description: The financial exchange code for the passed symbol. Required only if you are using the Exchange Symbol and Exchange Code as your symbol set. See Symbology.

See the full list of available exchange codes.

Example

"exchange": "NSQ"

fontColor

string: optional

Description: Hex color of x-axis and y-axis labels.

Default: "#9d9d9d"

Example

"fontColor": "#2496f1"

fontSize

integer: optional

Description: Font size of x-axis and y-axis labels in pixels.

Default: 12

Example

"fontSize": 13

lowerPanelHeight

integer: optional

Description: Height in pixels of the lower chart panel (volume). The overall image height will be the sum of upperPanelHeight and lowerPanelHeight

Default: 75

Example

"lowerPanelHeight": 50

numDays

integer: optional

Description: The timeframe in number of days that the chart should display.

Default: 365

Example

"numDays": 1

percentChange

boolean: optional

Description: When set to true will show the chart as a percent change.

Default: false

Example

"percentChange": true

priceFillColor

string: optional

Description: Hex color of the price fill color. This color is only used when chartType is set to area.

Default: "#33336699"

Example

"priceFillColor": "#3b638a"

priceLineColor

string: optional

Description: Hex color of the price line.

Default: "#2496f1"

Example

"priceLineColor": "#2496f1"

priceLineWidth

integer: optional

Description: Width in pixels of the price line.

Default: 2

Example

"priceLineWidth": 3

realTime

boolean: optional

Description: If the user_tier (see Authentication section) is entitled to real-time exchange data the realTime parameter can be set to true to get back real-time charting data. If the realTime parameter is set to true but the user_tier is not entitled to real-time data the chart will default back to displaying delayed data. Setting the realTime parameter to false will return delayed charting data. Number of minutes intraday data is delayed varies by exchange.

Default: false

Example

"realTime": true

showVolume

boolean: optional

Description: When set to true chart will show volume as a lower indicator. When set to false chart will not show volume as a lower indicator.

Default: false

Example

"showVolume": true

symbol

string: required

Description: The financial symbol for the chart to graph. See Symbology.

Example

"symbol": "AAPL"

upperPanelHeight

integer: optional

Description: Height in pixels of the upper chart panel (price). The overall image height will be the sum of upperPanelHeight and lowerPanelHeight

Default: 250

Example

"upperPanelHeight": 200

volumeColor

string: optional

Description: Hex color of volume bars.

Default: "#2496f1"

Example

"volumeColor": "#5F6064"

width

integer: optional

Description: Width in pixels of the chart image.

Default: 500

Example

"width": 400

xGridLineColor

string: optional

Description: Hex color of x-axis grid lines.

Default: "#e1e1e1"

Example

"xGridLineColor": "#e1e1e1"

xGridLineWidth

integer: optional

Description: Width in pixels of the x-axis grid lines.

Default: 1

Example

"xGridLineWidth": 2

yGridLineColor

string: optional

Description: Hex color of y-axis grid lines.

Default: "#e1e1e1"

Example

"yGridLineColor": "#e1e1e1"

yGridLineWidth

integer: optional

Description: Width in pixels of the y-axis grid lines.

Default: 1

Example

"yGridLineWidth": 2

Spark Charts

Spark charts are small simple charts that do not have x or y axis labels. They are often used in tables or to add small visualizations to a page or app.

Minimum Example

The CodePen shows the minimum inputs need to generate a spark chart:

Full Example

The CodePen shows all the available inputs for a spark chart:

API URL & Structure

The spark chart API URL is:

https://api.markitondemand.com/apiman-gateway/MOD/chartworks-image-charts/1/imagecharts/sparkLine

The API version is contained in the URL path. Only the major version is included in the path.

Chart inputs are contained in the inputs URL parameter and consists of an URL encoded object. A final API URL would look like this:

https://api.markitondemand.com/apiman-gateway/MOD/chartworks-image/1/Chart/sparkLine?inputs=%7B%22symbol%22%3A%22AAPL%22%2C%22exchange%22%3A%22NSQ%22%7D&access_token=demo-token

See the API Inputs section for a full list of Spark Chart inputs. The above CodePens also provide good examples of the API inputs.

API Inputs

Note: All images are returned with a transparent background.

exchange

string: required/optional

Description: The financial exchange code for the passed symbol. Required only if you are using the Exchange Symbol and Exchange Code as your symbol set. See Symbology.

See the full list of available exchange codes.

Example

"exchange": "NSQ"

height

integer: optional

Description: Height in pixels of the chart image.

Default: 30

Example

"height": 50

numDays

integer: optional

Description: The timeframe in number of days that the chart should display.

Default: 365

Example

"numDays": 1

priceLineColor

string: optional

Description: Hex color of the price line. This color is only used when showChange is set to true.

Default: "#5F6064"

Example

"priceLineColor": "#2496f1"

priceLineWidth

integer: optional

Description: Width in pixels of the price line.

Default: 1

Example

"priceLineWidth": 1

priceNegativeColor

string: optional

Description: Hex color of the negative portion of the price line. This is the portion of the price line that is below the previous day's close price. For example if our priceNegativeColor is set to #C0202D the result could look like this:

Drawing
The red section is the negative portion of the price line.

Default: "#C0202D"

Example

"pricePositiveColor": "#fd0000"

pricePositiveColor

string: optional

Description: Hex color of the positive portion of the price line. This is the portion of the price line that is above the previous day's close price. For example if our pricePositiveColor is set to #76c147 the result could look like this:

Drawing
The green section is the positive portion of the price line.

Default: "#1D8343"

Example

"pricePositiveColor": "#76c147"

realTime

boolean: optional

Description: If the user_tier (see Authentication section) is entitled to real-time exchange data the realTime parameter can be set to true to get back real-time charting data. If the realTime parameter is set to true but the user_tier is not entitled to real-time data the chart will default back to displaying delayed data. Setting the realTime parameter to false will return delayed charting data. Number of minutes intraday data is delayed varies by exchange.

Default: false

Example

"realTime": true

showChange

boolean: optional

Description: When set to true chart will use the pricePositiveColor and priceNegativeColor to draw the chart. When set to false chart will only use the priceLineColor to draw the chart.

Default: true

Example

"showChange": false

symbol

string: required

Description: The financial symbol for the chart to graph. See Symbology.

Example

"symbol": "AAPL"

width

integer: optional

Description: Width in pixels of the chart image.

Default: 75

Example

"width": 90

API Errors

All API errors are handed back with the appropriate status (400, 401 etc) and an error message.

Example 401 - Unauthorized response:

{"type":"Authentication","failureCode":11004,"responseCode":401,"message":"pf token validation failed","headers":{"entries":[],"empty":true}}

Versioning

The Image Charts APIs will follow the Semantic Versioning methodology. Chartworks will only release Major and Minor versions of the Image Charts APIs.

Image Charts Log

v1.1 (current stable)

Released September 2018

What's new in v1.1:

  • Minor version was dropped from the API path.
  • Added new input params chartType and priceFillColor to the Price Chart allowing for area charts.
  • New percentChange input param for the Price Chart that when set to true shows a percent change chart.
  • Ability to add comparison symbols to the chart through compareSymbols.
  • General bug fixes

v1.0

This is the initial release of the Chartworks Image charts.