Refinitiv

As of Oct 1, 2018 the former Financial and Risk business division of Thomson Reuters is now known as Refinitiv. All names and marks owned by Thomson Reuters, including Thomson, Reuters and the Kinesis logo are used under license from Thomson Reuters and its affiliated companies.

Refinitiv products will be undergoing brand changes at a future date to reflect Refinitiv branding.

For any further information please contact us at legal@refinitiv.com.

DSWS provides a REST based web service, built using WCF framework, to access Datastream content. You can either use JSON or XML (pox) based request/response. You can use any platform that issue HTTP requests for integration. The HTTP GET based operations are simpler to use but the HTTP POST based operations offer richer functionality. You can refer this test page to see the JSON/XML request and response messages for various operations along with the different parameters you can use.

GETTING STARTED

First understand the operations and data format to use from here. For the GET based operations, you will pass the request parameters in the URL as query string. Following are the steps you will typically use during integration when using the GET based methods:

  • Obtain a secure token by invoking the Token operation, passing your username and password as query string.
  • Retrieve the data by calling the Data operation, passing the appropriate instrument, data types and date information as query string.

You have to parse the returned repsonse to extract the results. You can control whether the responses need to be in JSON or XML by setting the Accept header or use the format query string. Note that all the query string values should be properly URL encoded.

You will not be able to retrieve data for multiple requests in a single call with the GET based operation. The POST based GetDataBundle operation can be used for this purpose. If you want to use POST based operations for all your requests, then you can use the GetToken and GetData counterparts.

TOKEN RETRIEVAL

A secure token is needed in order to retrieve data from DSWS. You can obtain a token using Token (or GetToken). You have to pass as part of this operation your username (eg. myusername@mycompany.com or ZABC123) and password. You will get back a secure token as part of the response and you will use this token for subsequent data access. Following code snippet shows an example token request and response:

HTTP Method: GET
Url: http://product.datastream.com/DSWSClient/V1/DSService.svc/rest/Token 
Query String: ?username=myusername%40mycompany.com&password=mypassword

Response
{
    "Properties":null,
    "TokenExpiry":"\/Date(1358511071286)\/",
    "TokenValue":"n9IcXCXIq+Ap01D2F84B72EF6414D3F08105B5"
}
NoteNote

The tokens have an expiry time and the response contains the timestamp (in UTC) when the token will expire. You can cache the token until this expiry time and use it for data requests. You need to obtain the token again if it has expired.

UNDERSTANDING REQUESTS

A data request in DSWS consists of an instrument (eg. VOD.L), data types (eg. PH), date information (eg. Start/End dates of a time series) and optional request properties. An instrument is generally a symbol (such as RIC, Thomson Ticker, Datastream Mnemonic, ISIN etc.) but it can also be a complex expression. You can specify properties for the instrument (eg. are they set of instruments rather than a single instrument). The data types contain the field codes for which you want to retrieve the data. You can lookup the instruments from here and browse the available data types from here. The expression syntax can be found here.

DSWS supports point-in-time data (snapshot) as well as time series data retrieval. For a snapshot date you will specify a single date, while for a time series date the start date, end date and frequency information will be specified. Note that the DateKind must be populated appropriately. You can use absolute dates (eg. 2012-11-24), relative dates (eg. -30D) or certain literals (eg. BDATE) as dates.

You can also specify additional request properties to customize your responses (eg. return expanded instrument name). If you need to specify the type of the instrument, you can use the special SYM# function. For example SYM#(VOD.L,RIC) specifies that the instrument type is a RIC. Following code snippet provides an example data request:

HTTP Method: GET
Query String:?token=n9IcXCXIq%2bA7F9D4603&instrument=VOD&datatypes=PL%2cPH&datekind=TimeSeries&start=-30D&end=-20D&freq=D


HTTP Method: POST { "DataTypes":[ { "Properties":null, "Value":"PL" }, { "Properties":null, "Value":"PH" }], "Date": { "End":"-20D", "Frequency":"D", "Kind":1, "Start":"-30D" }, "Instrument": { "Properties":null, "Value":"VOD" }, "Tag":null }
NoteNote

If you know that your request contains a symbol that is a RIC, it is better to pass the symbol decorated with <symbol>. For example, VOD.L can be passed as <VOD.L>. Alternatively, you can use the verbose syntax SYM#(VOD.L,RIC). This usually speeds up the operation in the backend.

UNDERSTANDING RESPONSES

A data response in DSWS contains all the requested data types and for each data type, the values corresponding to instruments. Note that even though you ask for a single instrument, if the instrument is a list symbol (eg. LFTSE100), you will get back multiple instruments in the response.

The response value is contained inside symbol response value. You can access the Value property to get the appropriate data. For example if you asked for a time series closing price, this property will contain an array of doubles.

A request failure (eg. invalid arguments) would result in a HTTP error. Further you have to check the Type property of a symbol response to see if a specific data type has errors (eg. time series information not available for requested data type).

You can also check additional response properties such as expanded symbol names etc. provided you had asked them during your request. Following code snippet provides an example data response:

{
    "AdditionalResponses":null,
    "DataTypeNames":null,
    "DataTypeValues":[
    {
        "DataType":"PL",
        "SymbolValues":[
        {
            "Currency":"£",
            "Symbol":"VOD",
            "Type":10,
            "Value":[158.48,159.25,161.2,160.65,161.05,160.65,161,NaN,155.97,155.9]
        }]
    },
    {
        "DataType":"PH",
        "SymbolValues":[
        {
            "Currency":"£",
            "Symbol":"VOD",
            "Type":10,
            "Value":[160.07,162.2,162.92,162.4,162,161.99,163.4,NaN,159.57,159.35]
         }]
     }],
     "Dates":["\/Date(1354665600000+0000)\/","\/Date(1354752000000+0000)\/","\/Date(1354838400000+0000)\/"],
     "SymbolNames":null,
     "Tag":null
}

DATA RETRIEVAL

You can retrieve the data for a single request using Data operation. Following code snippet provides an example request and response:

HTTP Method: GET
Url: http://product.datastream.com/DSWSClient/V1/DSService.svc/rest/Data
Query String: ?token=n9IcXCXIq%2bA7F9D4603&instrument=VOD&datatypes=PL%2cPH&datekind=TimeSeries&start=-30D&end=-20D&freq=D

Response
{
    "AdditionalResponses":null,
    "DataTypeNames":null,
    "DataTypeValues":[
    {
        "DataType":"PL",
        "SymbolValues":[
        {
            "Currency":"£",
            "Symbol":"VOD",
            "Type":10,
            "Value":[158.48,159.25,161.2,160.65,161.05,160.65,161,NaN,155.97,155.9]
        }]
    },
    {
        "DataType":"PH",
        "SymbolValues":[
        {
            "Currency":"£",
            "Symbol":"VOD",
            "Type":10,
            "Value":[160.07,162.2,162.92,162.4,162,161.99,163.4,NaN,159.57,159.35]
         }]
    }],
    "Dates":["\/Date(1354665600000+0000)\/","\/Date(1354752000000+0000)\/","\/Date(1354838400000+0000)\/"],
    "SymbolNames":null,
    "Tag":null

}

You can also use the POST based GetData operation in order to retrieve data for a single request. Following code snippet provides an example request and response:

HTTP Method: POST
Url: http://product.datastream.com/DSWSClient/V1/DSService.svc/rest/GetData 

Request
{
    "DataRequest":{
        "DataTypes":[
        {
            "Properties":null,
            "Value":"PL"
        },
        {
            "Properties":null,
            "Value":"PH"
        }],
        "Date":
        {
            "End":"-20D",
            "Frequency":"D",
            "Kind":1,
            "Start":"-30D"
       },
       "Instrument":
        {
            "Properties":null,
            "Value":"VOD"
        },
       "Tag":null
    },
    "Properties":null,
    "TokenValue":"n9IcXCXIq+ApBEe0z1B72EF6414D3F08105B5"
}

Response
{
    "DataResponse":{
        "AdditionalResponses":null,
        "DataTypeNames":null,
        "DataTypeValues":[
        {
            "DataType":"PL",
            "SymbolValues":[
            {
                "Currency":"£",
                "Symbol":"VOD",
                "Type":10,
                "Value":[158.48,159.25,161.2,160.65,161.05,160.65,161,NaN,155.97,155.9]
            }]
        },
        {
            "DataType":"PH",
            "SymbolValues":[
            {
                "Currency":"£",
                "Symbol":"VOD",
                "Type":10,
                "Value":[160.07,162.2,162.92,162.4,162,161.99,163.4,NaN,159.57,159.35]
             }]
         }],
         "Dates":["\/Date(1354665600000+0000)\/","\/Date(1354752000000+0000)\/","\/Date(1354838400000+0000)\/"],
         "SymbolNames":null,
         "Tag":null
    },
    "Properties":null
}

If you want to combine muliple requests into a single call then you can use GetDataBundle to get the data for all the requests in one-go. Following code snippet provides an example request and response:

HTTP Method: POST
Url: http://product.datastream.com/DSWSClient/V1/DSService.svc/rest/GetDataBundle 

Request
{
     "DataRequests":[
        {
            "DataTypes":[
            {
                "Properties":null,
                "Value":"PL"
            }],
            "Date":
            {
                "End":"",
                "Frequency":"",
                "Kind":0,
                "Start":"-10D"
            },
            "Instrument":
            {
                "Properties":null,
                "Value":"VOD"
            },
            "Tag":null
        },
        {
            "DataTypes":[
            {
                "Properties":null,
                "Value":"PH"
            }],
            "Date":
            {
                "End":"-0D",
                "Frequency":"D",
                "Kind":1,
                "Start":"-5D"
            },
            "Instrument":
            {
                "Properties":null,
                "Value":"BARC"
            },
            "Tag":null
        }],
    "Properties":null,
    "TokenValue":"FhzsU9Yozo3Ofml6H6D7092"
}

Response
{
    "DataResponses":[
        {
            "AdditionalResponses":null,
            "DataTypeNames":null,
            "DataTypeValues":[
            {
                "DataType":"PL",
                "SymbolValues":[
                {
                    "Currency":"£ ",
                    "Symbol":"VOD",
                    "Type":5,
                    "Value":191.24
                }]
            }],
            "Dates":["\/Date(1407715200000+0000)\/"],
            "SymbolNames":null,
            "Tag":null
      },
      {
            "AdditionalResponses":null,
            "DataTypeNames":null,
            "DataTypeValues":[
            {
                "DataType":"PH",
                "SymbolValues":[
                {
                    "Currency":"£",
                    "Symbol":"BARC",
                    "Type":12,
                    "Value":[222.05,221.95,221.45,223.6,null]
                }]
            }],
            "Dates":["\/Date(1408320000000+0000)\/","\/Date(1408406400000+0000)\/","\/Date(1408492800000+0000)\/","\/Date(1408579200000+0000)\/","\/Date(1408665600000+0000)\/","\/Date(1408924800000+0000)\/"],
            "SymbolNames":null,
            "Tag":null
       }],
       "Properties":null
}

There is a limit on the number of requests you can bundle together. Currently this limit is set to 2000 data points in a bundle where a data point is an instrument-datatype combination. For example, assume we have a bundle that contains 2 requests, with the first request containing instruments IBM.N and data types MNEM,NAME and the second request containing instrumentsVOD,BARC and data types PH,PL,P. The total number of data points for this bundle is then (1 instrument * 2 datatypes) + (2 instruments * 3 datatypes) = 8. If you exceed the limits, then you will receive an error.

NoteNote

Your application will perform better if you bundle the data requests together rather than making multiple individual data requests.

SEE ALSO