platts ewindow market data api user guide. platts ewindow market data api ewindow market data gives...

Version 1.4 20 June 2017

Platts eWindow Market Data API User Guide

S&P Global Platts holds all the rights on this document. This document should not be replicated, copied, or tampered with in part or in its entirety without the express written permission of Platts

Table Of Contents

1. Introduction ...............................................................................................1

2. Request Headers ......................................................................................1

3. eWindow Market Data API .......................................................................1

3.1 MetaData .................................................................................................1

3.2 AutoComplete .........................................................................................4

3.3 eWindow Market Data ............................................................................6

4. Error Codes ...............................................................................................9

5. Appendix ...................................................................................................10

5.1 The API Test Portal .................................................................................10

5.2 Offices ....................................................................................................11

1. Introduction

The Platts eWindow Market Data API functionality gives our clients the ability to easily retrieve and manage eWindow Market Data by making simple API calls to interact with our system. The Platts eWindow Market Data API User Guide is intended for software developers. To use the Platts eWindow Market Data API User Guide you should be familiar with web programming and be comfortable creating applications that consume web services through HTTP requests.

2. Request Headers

Below are the Request Headers which are common to all Platts eWindow Market Data APIs.

Header Description Required

appKey

A request header that contains a string, and is used to authenticate requests. This is a unique key assigned to the API consumer.

Example : appKey: XXXXXXXXXXXXXXX

Yes

Content-Type

The Content-Type header field is used to specify the nature (MIME Type) of the data in the body of the request or response.

Default : application/xml

Example : Content-Type: application/json

No

Accept-Encoding

The Accept-Encoding header specifies the compression algorithm for an object. The API responses are returned in the gzip format which results in more than 50% size reduction of response, which allows the transfer of more content in a single response and reduces the response time.

Accept-Encoding: gzip

No

1

3. Platts eWindow Market Data API

eWindow Market Data gives you all the numbers you need to observe your surroundings, think on your feet and remain nimble: the market data helps to be in sync with other market participants.

List of APIs - MetaData

- AutoComplete

- Platts eWindow Market Data

3.1 MetaDataThe eWindow Market Data MetaData service is a web service that returns the fields that are available as part of eWindow Market Data in response to an HTTP request.

URLhttps://api.platts.com/v1/tradedata/ewindowdata/metadata

HTTP MethodGET

Request ParametersThis service does not have any input parameters. Without any request parameters, this service returns the list of all available fields, along with their description and an example.

Request HeadersThis service only uses request headers that are common to all eWindow Market Data APIs. For details, refer to the Request Headers section.

Request Elements

2

Element Description

IDENTIFIER_NAME

Trade data column name.

Type: String

DESCRIPTIONBusiness synonym for the Trade data column.

Type: String

EXAMPLESample values of the Trade data column.

Type: String

Sample Requesthttps://api.platts.com/v1/tradedata/ewindowdata/metadata

Sample Response – XML

Sample Response – JSON

<?xml version="1.0" encoding="UTF-8"?><Platts xmlns="https://api.platts.com/Content/v2/TradeData"> <Content DocType="TradeData.MetaData"> <TradeData> <MetaData> <Rows> <Row> <IDENTIFIER_NAME>BUYER</IDENTIFIER_NAME> <DESCRIPTION>Entity buying the item/activity</DESCRIPTION> <EXAMPLE>Shell Singapore</EXAMPLE> </Row> <Row> <IDENTIFIER_NAME>PRICE_UNIT</IDENTIFIER_NAME> <DESCRIPTION>Unit of price</DESCRIPTION> <EXAMPLE>USD</EXAMPLE> </Row> <Row> <IDENTIFIER_NAME>PRODUCT</IDENTIFIER_NAME> <DESCRIPTION>The product being bid/offered</DESCRIPTION> <EXAMPLE>Platts Dubai</EXAMPLE> </Row> </Rows> </MetaData> </TradeData> </Content></Platts>

{ "@xmlns": "https://api.platts.com/Content/v2/TradeData", "Content": { "@DocType": "TradeData.MetaData", "TradeData": { "MetaData": { "Rows": { "Row": [ { "IDENTIFIER_NAME": "BUYER", "DESCRIPTION": "Entity buying the item/activity", "EXAMPLE": "Shell Singapore" }, { "IDENTIFIER_NAME": "PRICE_UNIT", "DESCRIPTION": "Unit of price", "EXAMPLE": "USD" }, { "IDENTIFIER_NAME": "PRODUCT", "DESCRIPTION": "The product being bid/offered", "EXAMPLE": "Platts Dubai" } ] } } } }}

3

Sample Use Case

3.2 AutoCompleteThe eWindow Market Data Autocomplete service is a web service that returns matching trade data fields or values within any trade data field in response to an HTTP request.

The request specifies a textual search string. This service is also capable of restricting the scope of search to a specific trade data field.

URLhttps://api.platts.com/v1/tradedata/ewindowdata/autocomplete

HTTP MethodGET

Request Parameters

This service does not have any mandatory input parameters. Without any request parameters, this service returns the list of all available fields along with the distinct values for each field.


Response Elements

S No Use case scenario with API call

1When the user would like to retrieve the information about the trade data fields.

API URL - https://api.platts.com/v1/tradedata/ewindowdata/metadata

Parameter Description Required

DataColumn

The Trade data field name on which the user wants to restrict the search. Using this parameter, the user can restrict text search specific to the provided trade data field.

Default: None

Example: DataColumn=PRODUCT

No

Query

The text string to be searched with. The service will return matches based on this string.

Default: None

Query=Azeri

No

Element Description

ColumnTrade data column name.

Type: String

ValueTrade data field value.

Type: String

4

Sample Requesthttps://api.platts.com/v1/tradedata/ewindowdata/autocomplete?DataColumn=PRODUCT&Query=Azeri



Sample Use Case

<?xml version="1.0" encoding="UTF-8"?><TradeData xmlns="https://api.platts.com/content/v2/TradeData"> <AutoComplete> <Rows> <Row> <ColumnNames> <Column Name="PRODUCT"> <Values> <Value>PLATTS AZERI LIGHT CFR CRG</Value> <Value>PLATTS AZERI LIGHT CIF CRG</Value> <Value>PLATTS AZERI LIGHT DES CRG</Value> </Values> </Column> </ColumnNames> </Row> </Rows> </AutoComplete></TradeData>

{ "@xmlns": "https://api.platts.com/content/v2/TradeData", "AutoComplete": { "Rows": { "Row": { "ColumnNames": { "Column": { "@Name": "PRODUCT", "Values": { "Value": [ " PLATTS AZERI LIGHT CFR CRG", " PLATTS AZERI LIGHT CIF CRG", " PLATTS AZERI LIGHT DES CRG" ] } } } } } }}


1When the user would like to retrieve all possible trade data fields along with their distinct values.

API URL - https://api.platts.com/v1/tradedata/ewindowdata/autocomplete

2

When the user would like to retrieve all distinct values for specific trade data fields. i.e. list of all available values for trade data field “product”.

API URL - https://api.platts.com/v1/tradedata/ewindowdata/autocomplete?DataColumn=product

3

When user would like to retrieve search text specific to any trade data field. i.e. user is looking for all matching text with keyword “Azeri” for trade data field “product”.

API URL - https://api.platts.com/v1/tradedata/ewindowdata/autocomplete?DataColumn=product&Query=azeri

4When user would like to search text across all fields and values within all fields.

API URL - https://api.platts.com/v1/tradedata/ewindowdata/autocomplete?Query=azeri

5

3.3 eWindow Market DataThe eWindow Market Data service is a web service that returns eWindow Market Data in response to an HTTP request. This service provides the below features:

- Provides the ability to choose the list of Trade Data fields to be part of the response

- Ability to apply filter conditions and refine the response

- Ability to return only distinct records

- Ability to sort the data based on any Trade Data field(s)

In addition, this service also has the ability to support Pagination, and defaults to return 200 records, with the maximum number of records being 15000. The response is always bound to the eWindow Market Data for which the user is entitled.

URLhttps://api.platts.com/v1/tradedata/ewindowdata?Filter={}&Fields={}&Distinct={}&OrderBy={}&PageNumber={}&PageSize={}

HTTP MethodGET

Request Parameters

This service does not have any mandatory input parameter. If passed without any parameters, it returns the most recent 24 hours of data entitled to the user, which includes all the trade data fields in the response.

Parameter Description Required

Fields

List of Trade data field(s) that will be part of the response. Using this parameter, the user can restrict the number of fields that will be part of the service response. If the parameter is not passed, the response will contain all of the trade data fields.

Default: None Example : Fields=PRODUCT,HUB

No

Filter

The filter criteria the user would like to apply over the eWindow Market Data in order to filter the response. The filter criteria are the combinations of a Trade Data field, the operand and the value. Please refer to the Filter Expression section for more details on constructing the filter criteria.

Default: None Example : Filter= PRODUCT==Platts Dubai

No

Distinct

Using this Boolean parameter, the user can choose to fetch only the distinct records as part of the response.

Default: False Example: Distinct=True

No

OrderBy

List of Trade data field(s) and the respective sort order (Ascending/ Descending). Using this parameter, the user can re-order the response. By default, the response is set to descending order of the trade data field “Update Time”.

Default: as part of this service Example: OrderBy=PRODUCT desc

No

PageSize

Using this parameter, the user can request the number of records that have to be fetched as part of the response. If the value is not specified, it will be default to 200 records per response. The maximum value that can be specified for this parameter is 15000.

Default: 200 Example: PageSize=10000

No

PageNumber

The user can request for a specific page based on the page size and the total number of records. If the value is not specified it will default to the first page. If the page number requested is outside the range of paginated records for the specified page size, it will return an error.

Default: 1 Example: PageNumber=10

No

MaxId

The timestamp of the first request executed. This will be a part of the response of the first request (with PageNumber=1), and has to be passed as a request parameter for subsequent API calls. For an application using Pagination, this becomes a mandatory Request parameter for all subsequent pages requested.

Default: 1 Example: MaxId=20120301162315014

No

6


Response Elements

Sample Requesthttps://api.platts.com/v1/tradedata/ewindowdata?Filter=Product==Platts Brent Diff&Fields=Market,hub,price


Element Description

Paging

It is a collection of fields related to pagination, composing of Total Record Count, Page Size, Page Number, Total number of pages and the time stamp when the first request executed.

Type: Collection of values

TotalRecordCountTotal number of records available in the system for the given criteria.

Type: Integer

PageSizeThe page size that is referred by the user as part of the request.

Type: Integer

PageNumberThe page number that is requested by the user as part of the request.

Type: Integer

TotalPagesThe total number pages available based on the page size and the filter criteria referred by the user as part of request.

Type: Integer

MaxIdThe time stamp when the first request is executed. This has to be referred in the request parameter in case of pagination.

Type: Integer

RowThe collection of key & value pairs representing the trade data field and the respective values for each row.

Type: Collection of Trade Data fields and values

<?xml version="1.0" encoding="UTF-8"?><Platts xmlns="https://api.platts.com/content/v2/TradeData"> <Content DocType="TradeData.EWindowData"> <TradeData> <EWindowData> <Paging> <TotalRecordCount>122490</TotalRecordCount> <PageSize>200</PageSize> <PageNumber>1</PageNumber> <TotalPages>613</TotalPages> <MaxId>20170608153001000</MaxId> </Paging> <Rows> <Row> <MARKET>EU Brent CFD</MARKET> <HUB>Brent CFD vs 1st Month</HUB> <PRICE>-.95</PRICE> </Row> <Row> <MARKET>EU Brent CFD</MARKET> <HUB>Brent CFD vs 1st Month</HUB> <PRICE>-1.08</PRICE> </Row> . . . </Rows> </EWindowData> <TradeData> </Content></Platts>

7


Sample Use Case

{ "@xmlns": "https://api.platts.com/content/v2/TradeData", "Content": { "@DocType": "TradeData.EWindowData", "TradeData": { "EWindowData": { "Paging": { "TotalRecordCount": "122490", "PageSize": "200", "PageNumber": "1", "TotalPages": "613", "MaxId": "20170608153001000" }, "Rows": { "Row": [ { "MARKET": "EU Brent CFD", "HUB": "Brent CFD vs 1st Month", "PRICE": "-.95" }, { "MARKET": "EU Brent CFD", "HUB": "Brent CFD vs 1st Month", "PRICE": "-1.08" } ] } } } }


1

When the user would like to get all the fields without any restrictions. If the user does not apply any conditions, the default response will contain the recent 24 hours data of the subscribed dataset.

API URL - https://api.platts.com/v1/tradedata/ewindowdata

2When the user would like to retrieve the list of Markets they are entitled to.

API URL - https://api.platts.com/v1/tradedata/ewindowdata? Fields=MARKET&Distinct=True

3When user would like to have some specific Trade data fields as part of the response like HUB and PRODUCT.

API URL - https://api.platts.com/v1/tradedata/ewindowdata?Fields=HUB,PRODUCT&Distinct=True

4

When the user wants to retrieve the records that match with a specific criteria, like all records with the Product as “Platts Dubai”

API URL - https://api.platts.com/v1/tradedata/ewindowdata?Filter=PRODUCT==Platts Brent Diff&Fields=MARKET,PRODUCT,HUB,MARKET_MAKER,PRICE,ORDER_STATE,ORDER_DATE

5

When the user wants to retrieve distinct records that match the criteria - Product as “Platts Dubai” and selected fields HUB & PRODUCT

API URL - https://api.platts.com/v1/tradedata/ewindowdata?Filter= PRODUCT==Platts Brent Diff &Fields=HUB,PRODUCT&Distinct=True

6When the user would like retrieve the records that match a criteria - Product as “Platts Dubai” and sort by hub in descending order.

API URL - https://api.platts.com/v1/tradedata/ewindowdata?Filter=PRODUCT==Platts Brent Diff &OrderBy=HUB desc

7

When the user wants to implement pagination, MaxID from the first request’s response has to be passed as a request parameter for all subsequent requests.

First Page URL – https://api.platts.com/v1/tradedata/ewindowdata?Filter=PRODUCT==Platts Brent Diff &&PageNumber=1&PageSize=15000

Second Page URL – https://api.platts.com/v1/tradedata/ewindowdata?Filter=PRODUCT==Platts Brent Diff &&PageNumber=2&PageSize=15000 &MaxId= 20160725082945942

8

When the user would like to retrieve the records by applying a complex filter criteria

API URL - https://api.platts.com/v1/tradedata/ewindowdata?Filter=Product[]=Platts Brent Diff,Platts Brent Diff Spread^Market==EU Brent CFD^Price<1^Price>=-2^Order_date>2017-04-04&Fields=price,product&Distinct=true&OrderBy=product desc

8

Filter ExpressionBelow is the list of operand notation referred to as part this service along with the implementation of the operation.

4. Error Codes

The error codes listed below contain both generic and specific identifiers to particular APIs / scenarios.

Operators Description Example

== Equal to PRODUCT== Platts Dubai

!= Not Equal to PRODUCT!= Platts Dubai

> Greater than PRICE>100

< Lesser than PRICE<100

>= Greater than and Equal to PRICE>=100

<= Lesser than and Equal to PRICE<=100

^ And Window_Region == Asia^Market==Global

| OR Window_Region == Asia|Market==Asia

[]= List, List item separated using (,)Order_State[]=Consummated,Active,Withdrawn (Retrieve records with Order_State from list)

[]!= Not in List Item separated using (,)Order_State[]!=Consummated,Active,Withdrawn (Retrieve records with Order_State not in this list)

~= Starts with Product ~= Platts (Product Starts with Platts)

=~ Ends with Product =~ Platts (Product Ends with Platts)

~=~ Contains Product ~=~ Platts (Product Contains Platts)

~!= Does not Starts with Product ~!= Platts (Product does not Starts with Platts)

!=~ Does not Ends with Product !=~ Platts (Product does not Ends with Platts)

~!=~ Does not contain Product ~!=~ Platts (Product does not contain Platts)

Error No Error Text HTTP Error Code When Does this Error Code Appear to the User?

TRD-4026Authentication error.Please provide a valid Application Key

401User calls an API Function and when the provided appKey is invalid.

TRD-40023You do not have access to the Data Set requested. Please contact your Platts

403When a user requests for data which they do not have entitlements for.

TRD-50041Invalid request.Please enter valid columns.

400When the Tradeadata API is requested for with Invalid Columns.

TRD-50042Invalid request.Please check your filter criteria

400When the Filter expression used in the Tradedata API is incorrect.

9

5. Appendix

5.1 The API Test PortalThe Platts eWindow Market Data API can be consumed using any common programming language like C-Sharp and Java that support REST service consumption.

The API can also be accessed and tested through the on-line test portal https://developer.platts.com

Direct URL: https://developer.platts.com/io-docs

- Select “Platts eWindow Trade Data API”

- Enter your client API Key

- Select the API you would like to test, and click Try It.

Error No Error Text HTTP Error Code When Does this Error Code Appear to the User?

TRD-50043Invalid request.Please check your filter criteria and format.

400

When the Filter expression used in the Tradedata API is incorrect.


400


400

TRD-50045Invalid Query Parameters.Please check your query.

400 When the API is provided with Invalid Query parameters

TRD-50046Requested page number does not exist.Please choose a page number within the valid range.

404When the requested Page number for Tradedata function does not exist

TRD-50047No records found.Please refine your query.

200This error occurs when no records are found for the Filter passed for in the Tradedata API

TRD-50048Field is not eligible for Autocomplete.There is no Autocomplete data available.

200This error occurs when there is no intellisense (Autocomplete) data found for the TradeData field.

TRD-60061Service is currently unavailable.If issue persists, please contact Platts Support.

500When the user tries to call a API using an Invalid HTTP Method.

TRD-70020Recall method not Supported. Refer to the Platts API documentation for more information.

405When the user tries to call an API using an Invalid HTTP Method.

10

NORTH AMERICA

New York2 Penn Plaza, 25th Floor New York, NY 10121-2298, USA P: +1-800-PLATTS8 (toll-free) P: +1-212-904-3070 (direct)

Boston225 Franklin Street, 14th Floor Boston, MA 02110 USA P: +1 800-752-8878 P: +1 617-530-8300

Denver1800 Larimer Street, Suite 2000 Denver, CO 80202, USA P: +1-720-264-6600

Hightstown148 Princeton-Hightstown Road Hightstown, NJ 80021, USA P: +1-800-PLATTS8 (toll-free)

HoustonHeritage Plaza 1111 Bagby Street, Suite 2200 Houston, TX 77002, USA P: +1-800-PLATTS8 (toll-free)

Pittsburgh424 South 27th Street, Suite 306 Pittsburgh, PA 15203, USA P: +1-412-431-4370

Washington, D.C.1200 G Street NW, Suite 1000 Washington, DC 20005, USA P: +1-212-904-3070

LATIN AMERICA

Buenos AiresTte. Gral. Juan D. Perón 346, 6th Floor (C1038AAH) Buenos Aires, Argentina P: +54-11-4121-4810

São PauloAv Brigadeiro Faria Lima 201 21st floor São Paulo – SP Brasil – 05626-100 – Brazil P: +55-11-3818-4100

Mexico City

Av. Javier Barros Sierra 540 Torre 2 PH2 Col. Santa Fe, C.P. 01219 Ciudad de México Mexico Tel +52 55 5081 4400

EUROPE, MIDDLE EAST AND AFRICA

London 20 Canada Square 12th Floor, Canary Wharf London E14 5LH, UK P: +44-20-7176-6111

Dubai Dubai International Financial Centre The Gate Precinct - Building 1 Level 05 P.O. Box 506650 Dubai, UAE P: +971-4-372-7100

Moscow Business Center Mokhovaya 4/7 Vozdvizhenka Street Building 2, 7th Floor, 125009 Moscow, Russia P: +7-495-783-4141

Stavanger Øvre Holmegate 1 4006 Stavanger Norway P: +47-51-89-06-66

ASIA-PACIFIC

Singapore 12 Marina Boulevard #23-01 Marina Bay Financial Centre Tower 3 Singapore 018982 P: +65-6532-2800

Beijing Suite 1601, 16/F Tower D Beijing CITC A6 Jianguo Menwai Avenue Chaoyang District Beijing 100022, China P: +86-10-6569-2929

Hong Kong Unit 6901, Level 69, International Commerce Centre, 1 Austin Road West, Kowloon, Hong Kong P: +852-2841-1035

Shanghai 33/F Shanghai Plaza 138 Huaihai Road (M) Shanghai 200021, China P: +86-21-5110-5488

Tokyo Marunouchi Kitaguchi Building, 28th Floor 1-6-5 Marunouchi Tokyo 100-0005, Japan P: +81-3-4550-8300

Melbourne Level 45, 120 Collins Street Melbourne VIC 3000, Australia P: +61-3-9631-2000

© 2017 S&P Global Platts, a division of S&P Global. All rights reserved.

platts.com 11

5.2 Offices

platts ewindow market data api user guide. platts ewindow market data api ewindow market data gives...

Documents