YourIR EZ API Documentation

The EZ API is intended to be used with Javascript Frameworks like React and NextJS in cases that the YourIR Javascript library cannot be made to work with the framework.

Whereas the YourIR Javascript library provides components for all your Investor Relations needs, the EZ API provides data only.

You can start using the EZ API right away without any setup.

Our servers set requests from localhost or unknown *.dev domains to an example config with a random stock (currently ).

You can prototype your Investor Relations and then contact us to set you up properly.

Quick Start

The following requests cover your Investor Relations data needs.

There is no need to specify a stock code or to authenticate, you can just fetch these URLs.

Click on a request for documentation and examples.

https://yourir.info/ezapi/quote
https://yourir.info/ezapi/trades
https://yourir.info/ezapi/prices
https://yourir.info/ezapi/announcements
https://yourir.info/ezapi/histquote?date=2020-01-01
https://yourir.info/ezapi/indexquote
https://yourir.info/ezapi/indexprices

Authorization

The Origin header is used to determine the client.

For example, if your website's URL is https://example.com, then we will associate example.com and www.example.com with your configuration.

You can advise us of other domains, such as your developer or staging domains and we will add them to your configuration.

In the curl examples below, the origin is set to https://example.com, whereas browsers will set it automatically.

If the Origin header cannot be used for whatever reason, we can issue you an application identifier that you can provide with each request:

https://yourir.info/ezapi/quote?appID=...

Responses

All responses (with the exception of announcement PDFs) have content type application/json; charset=utf-8

Successful responses are a JSON object with a result field, and optionally a paging field.

The result field is either an object or an array depending on the type of request.

The paging field is present when the request allows paged responses and a page is requested. If you don't supply the page parameter, all results are returned without paging unless otherwise stated.

                
{
    "result": array or object,
    "paging": {
        "page": number,
        "pageSize": number,
        "pageCount": number,
        "totalItems": number
    }
}

Error responses are a JSON object with en error field.

                
{
    "error": {
        "status": number,
        "code": short description,
        "message": helpful description
    }
}

Stock Code Selection

Rather than using ticker codes which can change, the EZ API uses numbers to identify your stocks.

We will configure your main stock as number 1 and that is the default stock for all requests.

Most companies only need to display a single stock so you don't need to specify it.

You can also choose to manually specify the code.

Multiple Stocks

If you do have multiple stocks, then we will configure them in the order you like and you request a particular stock by setting the stock parameter to its number.

For example, if your main ticker code is AAA and you also have two warrants AAAWB and AAAWC, then we would configure your stocks as follows:

Stock: Number
AAA: 1
AAAWB: 2
AAAWC: 3

And you would then request different stocks by setting the stock parameter:

URI: Stock
/quote: AAA
/quote?stock=1: AAA
/quote?stock=2: AAAWB
/quote?stock=3: AAAWC

Name Changes

In the event that your ticker code changes, your configuration will update automatically to reflect the new codes.

You will not need to make any changes.

Manually specifying the stock code

If you have a lot of stocks, then you may find it easier to pass the stock's code rather than its number:

URI: Stock
/quote?stock=aaa: AAA
/quote?stock=aaawb: AAAWB
/quote?stock=aaawc: AAAWC

If your stock is listed on different exchanges, then you will need to add the exchange:

URI: Stock
/quote?stock=aaa.asx: AAA on ASX
/quote?stock=aaa.nzx: AAA on NZX

Note that you will will have to make changes in the event of a name change.

Indices

If you want to compare your stock with an index, we can configure indices for you too.

Similar to stocks, the default index is number 1 and you request a different index by setting the index parameter to its number.

For example, if you want to compare your stock against All Ords and Mining, then we would configure XAO and XMM as your indices.

You would then request different indices by setting the index parameter:

URI: Index
/indexquote: XAO
/indexquote?index=1: XAO
/indexquote?index=2: XMM

Manually specifying the index code

As for stocks, you can pass the index code instead of its number:

URI: Index
/indexquote?index=xjo: XJO

Quotes


                GET /quote

Parameters

stock optional: The stock number to request

Returns

The result field is an object containing 20 minute delayed quote information:

code

The ticker code of the stock

name

The name of the stock

bid

The top bid

ask

The top ask

open

The first traded price today

high

The highest price today

low

The lowest price today

close

The last traded price today

volume

The total volume traded today

value

The total value traded today

tradeCount

The total number of trades today, minus any trade cancellations

tradeCancellationCount

The total number of trade cancellations today

change

The change in price

pctChange

The percentage change in price

price

The last traded price today or the previous close if it has not traded

vwap

The Volume Weighted Average Price

prevClose

The previous closing price

status

The trading status

time

The time that the quote was last updated

lastTradeTime

The time of the last trade today

lastTradeVenue

The venue of the last trade today (e.g asx or chia)

quoteBases

The quote bases today

dividendPerShare

Dividend per share

earningsPerShare

Earnings per share

netTangibleAssetsPerShare

Net Tanglible Assets per share

averages

Figures:

open: First traded price
high: Highest traded price
low: Lowest traded price
volume: Average daily volume

Time periods:

week: Over the last 7 days
month: Over the last calendar month
year: Over the last year
ytd: Since Jan 1st this year

units

Trading units, e.g. PRICE

currency

Currency, e.g. AUD

tz

Current timezone (abbreviated)

Trades


                GET /trades

Parameters

stock optional: The stock number to request
page optional: The page number to request
pageSize optional: The number of trades per page, Default page size is 25
tradeCount optional: The tradeCount field from the quote, used to synchronize the trade list and quote, see below
tradeCancellationCount optional: The tradeCancellationCount field from the quote, as for tradeCount

Returns

The result field is an array of trade objects:

time: The time of the trade
price: The price of the trade
volume: The volume of the trade
venue: The venue of the trade (e.g asx or chia)
conditionCodes optional: An array of condition codes attached to the trade

Trades are always returned in descending time order.

Note that the maximum number of trades returned is 10,000. Paging should be used for this request for large cap stocks.

Synchronizing with a quote

When you page through a large number of trades, the list of trades can change as new trades occur.

Similarly, if there is a delay between requesting the quote and requesting the trades, the trades could be ahead of the quote.

You can workaround these problems by providing the tradeCount and tradeCancellationCount fields that you received in the quote response to anchor the trade list to the same point in time.

Historical Prices


                GET /prices

Parameters

stock optional: The stock number to request
adjustment optional: capital or none. Prices are adjusted for reconstructions by default
order optional: asc or desC. Prices are returned in descending date order by default
page optional: The page number to request
pageSize optional: The number of days per page, Default page size is 25

Returns

The result field is an array of objects.

The prices and volumes are adjusted for splits.

date: The date
open: The first traded price on the day
high: The highest price on the day
low: The lowest price on the day
close: The closing price on the day
volume: The total volume traded on the day

Announcements


                GET /announcements

Parameters

stock optional: The stock number to request
order optional: asc or desc. Announcements are returned in descending time order by default
page optional: The page number to request
pageSize optional: The number of announcements per page, Default page size is 25

Returns

The result field is an array of objects:

time: The time of the announcement
heading: The announcement heading
priceSensitive: Whether the announcement is price sensitive
pageCount: The number of pages in the PDF
fileSize: The size of the PDF
types: An array of exchange specific announcement types
path: The path to the announcement document

Announcement PDFs


                GET /announcements/appID/fileID/filename

Parameters

Use the path from the announcements request.

Returns

A PDF.

Historical Quotes

Historical quotes allow you to implement a return calculator.


                GET /histquote?date=YYYY-MM-DD

Parameters

date required: The date to request a quote for

Returns

An object containing quote information for the requested date.

If the requested date is not a trading date, then data for the first trading date prior to date is returned.

open: The opening price on the day
high: The highest price on the day
low: The lowest price on the day
close: The closing price on the day
volume: The total volume traded on the day
value: The total value traded on the day
tradeCount: The total number of trades on the day
change: The change in price on the day
pctChange: The percentage change in price on the day
price: The closing price on the day or the previous close if it did not trade
adjustedPrice: The price adjusted for any reconstructions since that day
vwap: The Volume Weighted Average Price on the day
prevClose: The previous close before the day
time: The time at the end of the day
quoteBases: The quote bases on the day

Index Quotes


                GET /indexquote

Parameters

index optional: The index number to request

Returns

An object containing 20 minute delayed quote information.

code: The ticker code of the index
name: The name of the index
open: The first value today
high: The highest value today
low: The lowest value today
close: The last value today
change: The change in value
pctChange: The percentage change in value
time: The time that the value was last updated
tz: Current timezone (abbreviated)

Historical Index Prices


                GET /indexprices

Parameters

index optional: The index number to request
order optional: asc or desc. Prices are returned in descending date order by default
page optional: The page number to request
pageSize optional: The number of days per page, Default page size is 25

Returns

The result field is an array of objects.

date: The date
open: The first value on the day
high: The highest value on the day
low: The lowest value on the day
close: The closing value on the day

This example also demonstrates how to select something other than the default when multiple indexes are configured — it selects the 2nd index.