19
304 Hudson Street (2 nd Fl) New York, NY 10013 212-896-4400 (Main) 212-868-3848 (Fax) www.pinksheets.com [email protected] API - Real-Time Level II Quotes and Trade Information Version 1.0 November 2007 For implementation technical help and support please contact Issuer Services at 212.896.4420.

API - Real-Time Level II Quotes and Trade Information

  • Upload
    others

  • View
    3

  • Download
    0

Embed Size (px)

Citation preview

304 Hudson Street (2nd Fl) New York, NY 10013 212-896-4400 (Main) 212-868-3848 (Fax) [email protected]

API - Real-Time Level II Quotes and Trade Information

Version 1.0

November 2007

For implementation technical help and support please contact Issuer Services at 212.896.4420.

Pink Sheets Real-Time Level II Quotes and Trade Information API

Table of Contents: Table of Contents: .......................................................................................................................................... 2

1. Introduction ............................................................................................................................................ 3

2. HTML Output Option ............................................................................................................................. 3 HTML Output Data Levels and Examples .............................................................................................. 4 Applying Styles to HTML Output........................................................................................................... 6 Sample Code ........................................................................................................................................... 9

3. XML/MDDL Output Option ................................................................................................................ 11 Example MDDL Output........................................................................................................................ 11 MDDL Tag Descriptions....................................................................................................................... 15 Display Guidelines and Important Data Identifying Conventions......................................................... 19

4. Implementation..................................................................................................................................... 19

11/14/07 Version 1.0

2

Pink Sheets Real-Time Level II Quotes and Trade Information API

1. Introduction This document describes the Pink Sheets Real-time Level 2 Quote and Trade montage application program interface (API). This feature is a JAVA service that allows client applications to access Pink Sheets real-time market maker quote and trade data through a simple HTML - or XML - based interface by means of an HTTP call for the purposes of displaying the data on a website. The application can be accessed through any development environment that supports HTTP.

The quote and trade data output is obtained when a client makes a call to a specified URL with specified inputs comprised of a series of ‘field=value’ pairs. Subscribers to this service choose whether to receive the quote and trade data in HTML or MDDL format:

HTML “result” data is returned in the latest standard compliant XHTML format. The HTML format is less flexible for display customization, but is an easier way to integrate the data without extensive technical knowledge.

XML “result” data is returned in the MDDL format, an XML-based interchange format for financial data. The XML format allows for complete user control over the display preferences and requires more programming expertise and efforts.

See the detailed information for each output type below.

2. HTML Output Option The HTML version of the Pink Sheets Level II Quote and Trade Montage offers an easy way to integrate Pink Sheets data into a website. The HTML output may be customized by specifying font type, font size, font color and background color (see ‘Applying Styles to HTML Output’ section below) via CSS styles. The amount of data displayed may also be customized using the ‘type’ attribute (see HTML Output Data Levels’ below).

The following URL sample outputs an HTML file with real-time level II market maker quote montage and trade information:

http://www.otciq.com/otciq/showOutsideQuotes?securityId=XXXX&token=YYYYYY&format=html&type=complete

where the inputs are:

securityId - Required - Specifies the ID of the security whose information is sought

(provided by Pink Sheets)

token - Required - Specifies individual token by which the request is authenticated

(provided by Pink Sheets)

format - Specified the format of the returned data - Values may be either ‘HTML’ or ‘MDDL’

type - Specifies the level of detail of returned data - Values may be ‘TradeH’, ‘TradeV’, ‘TradeInside’ or Complete

style - Specifies whether to display custom style or default one for the

HTML output - Values may be ‘own’ or ‘default’

11/14/07 Version 1.0

3

Pink Sheets Real-Time Level II Quotes and Trade Information API

HTML Output Data Levels and Examples

Level II quote information and trade information is available through the HTML output option. The data points available in the HTML output for a specific security includes: security symbol, company name, inside quote, date and time of last inside change, market maker id, bid price, ask price, bid size, ask size, quote update date/time, last sale price, change, time of last sale, percentage change, open, previous close, volume, daily range, 52 week range. Note: trade data is delayed 15 minutes while quote information is real-time. The level of detail for data output depends on the “type” parameter set in the called URL: TradeH Type The TradeH type displays Security Symbol, Last Sale Price and Change in a horizontal format. The default URL is: http://www.otciq.com/otciq/showOutsideQuotes?format=html&securityId=YYYY&token=XXXX&type=tradeH TradeH Output

TradeV Type The TradeV type displays Security Symbol, Last Sale Price and Change in a vertical format. The default URL is: http://www.otciq.com/otciq/showOutsideQuotes?format=html&securityId=XXXX&token=YYYY&type=tradeV TradeV Output

TradeInside Type The TradeInside type displays Company Name, Symbol, detailed Trade Data and Inside Quote information. The default URL is: http://www.otciq.com/otciq/showOutsideQuotes?format=html&securityId=YYYY&token=YYYY&type=tradeInside

11/14/07 Version 1.0

4

Pink Sheets Real-Time Level II Quotes and Trade Information API

TradeInside Output

Complete Type The Complete type displays Company Name, Symbol, detailed Trade Data and complete quote information (inside and full montage). The default URL is: http://www.otciq.com/otciq/showOutsideQuotes?format=html&securityId=XXXX&token=YYYY&type=complete Complete Type Output

11/14/07 Version 1.0

5

Pink Sheets Real-Time Level II Quotes and Trade Information API

Applying Styles to HTML Output

The HTML output may be customized by applying custom CSS styles to match the look-and-feel of a website. Depending on the ‘type’ of output selected, font-size, font-color, background-color and borders may be customized. To customize styles, set style=own in the called URL, e.g.: http://www.otciq.com/otciq/showOutsideQuotes?format=html&securityId=XXXX&token=YYYY&type=complete&style=ownand then add the applicable styles to the css style sheet for the page in which the data will appear.

Important: Each ‘type’ has specific class names that apply to that type. The class name used in style customization must be exactly the same as the class names used within this document.

TradeH Type Applicable class name: psTradeTable

11/14/07 Version 1.0

6

Pink Sheets Real-Time Level II Quotes and Trade Information API

Style used for example:

.psTradeTable {font-size: 16px; color: #007D3F; border-top: 1px solid #CCCCCC; border-bottom: 1px solid #CCCCCC;}

TradeV Type Applicable class name: psTradeTable

Style used for example:

.psTradeTable {font-size: 16px; color: #007D3F; border-top: 1px solid #CCCCCC; border-bottom: 1px solid #CCCCCC;}

TradeInside Type Applicable class name: psTradeTable, psInsideTable, psHeaderBGColor, psCompanyNmae

11/14/07 Version 1.0

7

Pink Sheets Real-Time Level II Quotes and Trade Information API

Style used for example:

.psTradeTable {font-size: 12px; color: #000000;}

.psInsideTable { font-size:12px; color:#000000; width:400px; padding-top:10px; margin-left:5px;}

.psHeaderBGColor { background-color: #FFFFB7;}

.psCompanyName {font-weight: bold; font-size:24px; padding-left:3px; color:#007D3F;}

Complete Type Applicable class name: psTradeTable, psInsideTable, psHeaderBGColor, psCompanyName, psMontageTable

11/14/07 Version 1.0

8

Pink Sheets Real-Time Level II Quotes and Trade Information API

Style used for example:

.psTradeTable {font-size: 12px; color: #000000;}

.psInsideTable {font-size: 12px; color:#000000; width:400px; padding-top:10px; margin-left:5px;}

.psMontageTable { font-size:12px; color:#000000; padding: 2px; width:99%;}

.psHeaderBGColor { background-color: #FFFFB7;}

.psCompanyName {font-weight: bold; font-size:24px; padding-left:3px; color:#007D3F;}

Sample Code

To help with the implementation of the HTML output display, sample code is displayed below. Note, this code requires server-side processing – it cannot simply be pasted into an html document.

11/14/07 Version 1.0

9

Pink Sheets Real-Time Level II Quotes and Trade Information API

Using PHP <?php $handle = fopen("http://www.otciq.com/otciq/showOutsideQuotes?securityId=XXXX&token=YYYYYY&format=html&type=complete ", "rb"); $contents = ""; do { $data = fread($handle, 8192); if (strlen($data) == 0) { break; } $contents .= $data; } while (true); fclose($handle); echo $contents; ?>

Using JSP (Java) <% try { String urlString = "http://www.otciq.com/otciq/showOutsideQuotes?securityId=XXXX&token=YYYYYY&format=html&type=complete "; java.net.URL url = new java.net.URL(urlString); URLConnection urlConn = url.openConnection(); DataInputStream input = new DataInputStream(urlConn.getInputStream() ); %> <% // read in each character until end-of-stream is detected for (int c = input.read(); c != -1; c = input.read() ) { out.print( (char)c ); } input.close(); } catch( Exception e ) { out.println( "<p><b>Pink Sheets quote and trade data is currently not available</b></p>" ); e.printStackTrace(); } %> Using ASP <% GotothisURL=http://www.otciq.com/otciq/showOutsideQuotes?securityId=XXXX&token=YYYYYY&format=html&type=completeSet GetConnection = CreateObject("Microsoft.XMLHTTP") GetConnection.Open "get", GotothisURL, False on error resume next GetConnection.Send ResponsePage = GetConnection.responseText

11/14/07 Version 1.0

10

Pink Sheets Real-Time Level II Quotes and Trade Information API

NewR = replace (ResponsePage, "javascript:location.reload()","http://www.YOURSITE.com/YOURPAGE.asp") Response.write (NewR ) Set GetConnection = Nothing %>

3. XML/MDDL Output Option MDDL is an XML-based interchange format for financial data. This option outputs data in an XML format which allows for complete control over the display of the returned data. In all likelihood, implementing the MDDL format will require more programming time and resources than the HTML option. For more information on MDDL, please refer to http://www.mddl.org. The following URL outputs a MDDL file with real-time level 2 market maker quote montage and trade information: http://www.otciq.com/otciq/showMDDLMontage?securityId=XXXX&token=YYYYYY&format=MDDLwhere securityId and token are provided by Pink Sheets.

Example MDDL Output

<?xml version="1.0" encoding="UTF-8"?><mddl version="3.0-beta" xmlns="http://www.mddl.org/mddl/3.0-beta" xmlns:mddl="http://www.mddl.org/mddl/3.0-beta" xmlns:schemaLocation="http://www.mddl.org/mddl/3.0-beta mddl-3.0-beta-lite.xsd" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <header> <dateTime>2007-11-06 12:14:28</dateTime> <source>Pink Sheets</source> </header> <snap> <dateTime>2007-11-06 12:14:28</dateTime> <snapType>Real-time Quote and Trade data</snapType> <instrumentDomain> <instrumentIdentifier> <code scheme="http://www.mddl.org/ext/scheme/identifier?MIC=PINX">CSVI</code> <name>Computer Services, Inc.</name> <instrumentData> <instrumentType>Common</instrumentType> <instrumentType>PiggyBack Qualified</instrumentType> </instrumentData> </instrumentIdentifier> <issueData> <placeOfListing> <name>Pink Sheets</name> </placeOfListing> </issueData> <orderbook> <orderbookType>Inside Quote</orderbookType> <bid> <last> <mdString>34.5</mdString> </last> <size>

11/14/07 Version 1.0

11

Pink Sheets Real-Time Level II Quotes and Trade Information API

<NonNegativeDecimal>200</NonNegativeDecimal> </size> </bid> <ask> <last> <mdString>35.25</mdString> </last> <size> <mdNonNegativeDecimal>200</mdNonNegativeDecimal> </size> </ask> <lastDate> <mdDateTime>11:09 AM</mdDateTime> </lastDate> </orderbook> <orderbook> <orderbookType>Quote Montage</orderbookType> <bid> <last> <mdString>34.50</mdString> <marketCenter> <code>HDLY</code> </marketCenter> <dateTime>11:05</dateTime> </last> <size> <mdNonNegativeDecimal>200</mdNonNegativeDecimal> </size> </bid> <ask> <last> <mdString>35.25</mdString> <marketCenter> <code>HDLY</code> </marketCenter> <dateTime>11:05</dateTime> </last> <size> <mdNonNegativeDecimal>200</mdNonNegativeDecimal> </size> </ask> <bid> <last> <mdString>33.55</mdString> <marketCenter> <code>NITE</code> </marketCenter> <dateTime>12:09</dateTime> </last> <size> <mdNonNegativeDecimal>200</mdNonNegativeDecimal> </size> </bid> <ask> <last> <mdString>35.25</mdString> <marketCenter> <code>HILL</code> </marketCenter> <dateTime>11:09</dateTime> </last> <size>

11/14/07 Version 1.0

12

Pink Sheets Real-Time Level II Quotes and Trade Information API

<mdNonNegativeDecimal>200</mdNonNegativeDecimal> </size> </ask> <bid> <last> <mdString>33.50</mdString> <marketCenter> <code>HILL</code> </marketCenter> <dateTime>11:09</dateTime> </last> <size> <mdNonNegativeDecimal>200</mdNonNegativeDecimal> </size> </bid> <ask> <last> <mdString>35.45</mdString> <marketCenter> <code>NITE</code> </marketCenter> <dateTime>12:09</dateTime> </last> <size> <mdNonNegativeDecimal>200</mdNonNegativeDecimal> </size> </ask> <bid> <last> <mdString>U</mdString> <marketCenter> <code>VNDM</code> </marketCenter> <dateTime>08/29</dateTime> </last> <size> <mdNonNegativeDecimal/> </size> </bid> <ask> <last> <mdString>U</mdString> <marketCenter> <code>DOMS</code> </marketCenter> <dateTime>10/11</dateTime> </last> <size> <mdNonNegativeDecimal/> </size> </ask> <bid> <last> <mdString>U</mdString> <marketCenter> <code>AUTO</code> </marketCenter> <dateTime>08:33</dateTime> </last> <size> <mdNonNegativeDecimal/> </size>

11/14/07 Version 1.0

13

Pink Sheets Real-Time Level II Quotes and Trade Information API

</bid> <ask> <last> <mdString>U</mdString> <marketCenter> <code>AUTO</code> </marketCenter> <dateTime>08:33</dateTime> </last> <size> <mdNonNegativeDecimal/> </size> </ask> <bid> <last> <mdString>U</mdString> <marketCenter> <code>ETRD</code> </marketCenter> <dateTime>10:38</dateTime> </last> <size> <mdNonNegativeDecimal/> </size> </bid> <ask> <last> <mdString>U</mdString> <marketCenter> <code>ETRD</code> </marketCenter> <dateTime>10:38</dateTime> </last> <size> <mdNonNegativeDecimal/> </size> </ask> </orderbook> <trade> <last> <mdDecimal>35.0</mdDecimal> <dateTime>11:08 AM</dateTime> </last> <volume> <volumeType>total</volumeType> <last> <mdNonNegativeDecimal>2997.0</mdNonNegativeDecimal> </last> </volume> <close> <mdDecimal>35.75</mdDecimal> </close> <open> <mdDecimal>35.1</mdDecimal> </open> <high> <mdDecimal>35.1</mdDecimal> <period> <periodType>daily</periodType> </period> </high> <high>

11/14/07 Version 1.0

14

Pink Sheets Real-Time Level II Quotes and Trade Information API

<mdDecimal>42.0</mdDecimal> <period> <periodType>annual</periodType> </period> </high> <low> <mdDecimal>34.0</mdDecimal> <period> <periodType>daily</periodType> </period> </low> <low> <mdDecimal>28.05</mdDecimal> <period> <periodType>annual</periodType> </period> </low> <change> <mdDecimal>-0.75</mdDecimal> <changeType scheme="http://www.mddl.org/mddl/scheme/changeType.xml"> <code>previousClose</code> </changeType> </change> <change> <mdDecimal>-2.0979</mdDecimal> <changeType> <code>previousClose</code> </changeType> <valuationType>percentage</valuationType> </change> <tickDirection scheme="http://www.mddl.org/mddl/scheme/direction.xml"> <code>Positive</code> </tickDirection> <yield> <mdDecimal>1.8286</mdDecimal> </yield> <dividendYield> <mdDecimal>0.64</mdDecimal> </dividendYield> </trade> <source> <mdString>Pink Sheets</mdString> <code>PINX</code> </source> </instrumentDomain> </snap> </mddl>

MDDL Tag Descriptions

Below are the basic descriptions of the tags presented in the MDDL output. For detailed explanation of tags and additional information about MDDL, please visit http://www.mddl.org. <snap> -- Construct to hold the basic products for single-time or end-of-day quotes. <instrumentDomain> -- Instrument Domain. Generic domain for all instruments and securities.

11/14/07 Version 1.0

15

Pink Sheets Real-Time Level II Quotes and Trade Information API

<instrumentIdentifier> -- Identifies the instrument for the corresponding market data, calculations, or valuations. It may contain many codes from many schemes with multiple names (including multiple languages). The intent is that enough information be given to uniquely identify the instrument. <code> -- The shorthand notation for a known item (e.g. country, exchange, instrument) from the appropriate Controlled Vocabulary or "scheme", e.g, in the included example the code refers to the listing venue for the given security, Pink Sheets. This tag also include a string literal for denote the security symbol. In the example above, symbol CSVI is denoted as <mdString>CSVI</mdString>. <name> -- The textual proper name of an instrument and the role for which that name plays. This may be included in multiple languages. In the included example, <name> is used as part of <instrumentIdentifier> to denote the company name, e.g., <name>Computer Services Inc.</name> <instrumentData> -- Container for basic amplifying information about the instrument. <instrumentType> -- Controlled Vocabulary indicating the classification or type of instrument (e.g. ISO 10962 CFI code for Classification of Financial Instruments) used as part of Instrument Data. In the included example, this tag is used to denote Common stock class as well as Piggyback Eligibility Status, e.g., <instrumentType>Common</instrumentType> and <instrumentType>Piggyback Qualified</instrumentType>. <issueData> -- Container holding information relative to the issue itself (domain agnostic). <placeOfListing> -- The place of listing of an instrument. In our example the place of listing is Pink Sheets. <placeOfTrade> -- The place of trading of an instrument. In our example the place of listing is Pink Sheets. <orderbook> -- Container holding order book (full or best bid/ask), market depth, or market maker (exchange) views of current positions of a particular instrument. <orderbooktype> -- Controlled Vocabulary indicating the form of <orderbook> information provided – order book, market depth, market maker. In the included example, <orderbooktype> is used as part of <orderbook> tag to indicate an Inside Quote, e.g., <orderbookType>Inside Quote</orderbookType> Or to indicate Quote Montage, e.g, <OrderbookType>Montage Quote</OrderbookType> <bid> -- This element is a container to denote data associated with a Bid Quote. <last> -- The last (or most recent) valuation. <size> -- A count of the number of units in a bundle (for example, the number of shares in a trade). <mdDecimal> -- Intended to hold any decimal (numeric) data. <mdNonNegativeDecimal>-- Intended to hold any positive decimal (numeric) data. In the included example, <last> is used as part of <bid> to denote the latest real-time bid for the given market maker in the given security, e.g.,

11/14/07 Version 1.0

16

Pink Sheets Real-Time Level II Quotes and Trade Information API

<bid> <last> <mdDecimal>36.0</mdDecimal> </last> <size> <NonNegativeDecimal>200</NonNegativeDecimal> </size> </bid>

<lastDate> -- Date (and/or time) of last occurrence (e.g. last quote update). <mdDateTime> -- Intended to hold XML Schema types "dateTime", "date", or "time". In the included example, the <lastDate> and <mdDateTime> are used as part of <orderbook> tag to denote the last time and date the inside quote was updated, e.g.,

<lastDate> <mdDateTime>2:18 PM</mdDateTime> </lastDate>

<marketCenter> -- The market center or specialist providing the current quote. In the above example, <marketCenter> is used as part of <orderbook> tag to indicate market maker ID HDSN in the following way:

<marketCenter> <code>HDSN</code> </marketCenter>

<trade> -- Container for all data related to a "trade". In the given example the trade container includes: <last> -- The last (or most recent) valuation. In our example, <last> denotes last trade along with its time:

<last> <mdDecimal>36.5</mdDecimal> <dateTime>10:00 AM</dateTime> </last>

<volume> -- Number of items traded in the period defined. <volumeType> -- or Controlled Vocabulary indicating how "volume" is calculated. <open> -- The value at the beginning of trading or opening of the market. <close> -- The final price as of market close. <high> -- The highest valuation over the period specified. <period> -- Denotes a range of time possibly with a fixed "start" and/or "end" time. <periodType> -- Controlled Vocabulary indicating how "period" relates to parent. <low> -- The lowest valuation over the period specified.

11/14/07 Version 1.0

17

Pink Sheets Real-Time Level II Quotes and Trade Information API

<change> -- Denotes difference between this valuation and a previous valuation (per changeType). <changeType> -- Controlled Vocabulary indicating base value to which "change" is referenced. <tickDirection> -- Controlled Vocabulary showing relative direction of last tick. In the above example the In the given example all the trade related descriptors above are utilized in the following manner:

<volume> <volumeType>total</volumeType> <last> <mdNonNegativeDecimal>300.0</mdNonNegativeDecimal> </last> </volume> <close> <mdDecimal>36.5</mdDecimal> </close> <open> <mdDecimal>36.5</mdDecimal> </open> <high> <mdDecimal>36.5</mdDecimal> <period> <periodType>daily</periodType> </period> </high> <high> <mdDecimal>42.0</mdDecimal> <period> <periodType>annual</periodType> </period> </high> <low> <mdDecimal>36.5</mdDecimal> <period> <periodType>daily</periodType> </period> </low> <low> <mdDecimal>28.05</mdDecimal> <period> <periodType>annual</periodType> </period> </low> <change> <mdDecimal>0.0</mdDecimal> <changeType scheme=“http://www.mddl.org/mddl/scheme/changeType.xml“> <code>previousClose</code> </changeType> </change> <change> <mdDecimal>0.0</mdDecimal>

11/14/07 Version 1.0

18

Pink Sheets Real-Time Level II Quotes and Trade Information API

<changeType scheme=“http://www.mddl.org/mddl/scheme/changeType.xml“> <code>previousClose</code> </changeType> <valuationType>percentage</valuationType> </change> <tickDirection scheme="http://www.mddl.org/mddl/scheme/direction.xml"> <code>Even</code> </tickDirection>

<yield> -- Rate of return, e.g.,

<yield> <mdDecimal>1.7534</mdDecimal> </yield>

<dividendYield> -- Rate of return for an equity instrument. Generally expressed as a percentage or a coefficient of percentage.

<dividendYield> <mdDecimal>0.64</mdDecimal> </dividendYield>

<source> -- The source of the data provided. In the given example the source of the data is Pink Sheets.

Display Guidelines and Important Data Identifying Conventions

Given the inherent flexibility of MDDL format, one can choose to display any part of returned information (whether just Last Trade info or Inside or complete quote and trade information) and format in any way to match the look-and-feel of a website. For an example of how to display the xml output please view the HTML output samples in the HTML Output Examples section of this document.

Please note, the MDDL file contains two <orderbook> tags. The first <orderbook> provides data for an Inside Quote, i.e., the Best Bid and Best Ask along with the cumulative Size (also called market breadth). The second <orderbook> provide all Bids and Asks for the given security with the corresponding sizes and market maker IDs. Market maker IDs (see <marketCenter> tag description) that start with lower case letter ‘c’ (for instance, “cHDSN”) signify that the corresponding quote is a Closed Quote. Bid or Ask values presented as part of <mdString> type of <last> tag that equal ‘U’ denote an Unpriced Quote.

4. Implementation For implementation technical help and support please call Pink Sheets Issuer Services at 212.896.4420.

11/14/07 Version 1.0

19