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 SOAP based web service, built using WCF framework, to access Datastream content. The metadata is published through WSDL. You can use any platform that can access SOAP based web services for integration. You can refer this test page to see the SOAP request and response messages for various operations along with the different parameters you can use.

GETTING STARTED

First import the metadata into the client side from here. If you are using Microsoft Visual Studio, then you will typically add a service reference to the service and this will generate the relevant types and service client automatically for you. If you are using Java, you might choose a technique similar to this to generate your web service client code. You can then instantiate the service client and invoke the various methods. You can refer here for a description of the operations. Following are the steps you will typically use during integration:

  • Obtain a secure token by calling GetToken() method passing your credentials
  • Create DSDataRequest with the appropriate instrument, data types and date information.
  • Invoke GetData() method passing the secure token and the data request.
  • Extract data from the returned DSDataResponse.

You can also use GetDataBundle() method to retrieve data for multiple requests in a single call.

TOKEN RETRIEVAL

A secure token is needed in order to retrieve data from DSWS. You can obtain a token by calling GetToken() method. You have to pass as part of this method 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:

// Create a token request
var tokenRequest = new DSGetTokenRequest()
{
    UserName = "myusername@mycompany.com",
    Password = "mypassword",
};

string tokenValue = null;
DateTime tokenExpiry = default(DateTime);
using (var dsclient = new DSServiceClient())
{
    // Issue a call to get the token
    var tokenResponse = dsclient.GetToken(tokenRequest);

    // Read the token from the response
    tokenValue = tokenResponse.TokenValue;
    tokenExpiry = tokenResponse.TokenExpiry;
}
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:

// A data request
var request = new DSDataRequest()
{
    Instrument = new DSInstrument() { Value = "VOD" },
    DataTypes = new[] { new DSDataType() { Value = "PL" } },
    Date = new DSDate() { Kind = DSDateKind.Snapshot, Start = "2011-01-01" },
};

//
// Different types of requests...

// Single instrument
var singleInstr = new DSInstrument() 
{ 
    Value = "VOD" 
};

// Multiple instruments 
var multiInstr = new DSInstrument() 
{ 
    Value = "VOD,BARC,MSFT", 
    Properties = new[] 
    { 
        new DSStringObjectKVPair() { Key = DSInstrumentPropertyNames.IsSymbolSet.ToString(), Value = true } 
    } 
};

// Expressions
var expr = new DSInstrument()
{
    Value = "VOD(PL) + VOD(PH)", 
    Properties = new[] 
    {
        new DSStringObjectKVPair() { Key = DSInstrumentPropertyNames.IsExpression.ToString(), Value = true } 
    }
};

// Single datatype
var singleDataType = new[] { new DSDataType() { Value = "PL" } };

// Multiple datatypes
var multiDataTypes = new[] { new DSDataType() { Value = "PL" }, new DSDataType() { Value = "PH" } };

// Snapshot date
var snpDate = new DSDate() { Kind = DSDateKind.Snapshot, Start = "2011-01-01" };

// Snapshot date with date literals
var snpDate2 = new DSDate() { Kind = DSDateKind.Snapshot, Start = DSDateNames.WKE.ToString() };

// Timeseries date
var tsDate = new DSDate() { Kind = DSDateKind.TimeSeries, Start = "-30D", End = "-10D", 
    Frequency = DSDateFrequencyNames.D.ToString() };
 

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 SOAP error with appropriate fault details. 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:

// Access the response
DSDataResponse response = ResponseGotFromGetData();
foreach (var datatypeValue in response.DataTypeValues)
{
    // This is the datatype requested
    string requestedDataType = datatypeValue.DataType;

    // Access the symbols for the datatype
    // If the requested instrument was a list, there will be multiple symbols
    foreach (var symbolVal in datatypeValue.SymbolValues)
    {
        string symbol = symbolVal.Symbol;
        if (symbolVal.Type == DSSymbolResponseValueType.Error)
        {
            // The symbol value is an error - perhaps there is no data
            string errorMessage = symbolVal.Value.ToString();
        }
        else if (symbolVal.Type == DSSymbolResponseValueType.DoubleArray)
        {
            // The symbol value is a double array
            double[] values = (double[]) symbolVal.Value;
                        
        }
    }
}
 

DATA RETRIEVAL

You can retrieve the data for a single request by calling GetData() method. Following code snippet provides an example GetData request and response:

// Create the request
var request = new DSGetDataRequest()
{
    TokenValue = TokenGotThroGetToken(),
    DataRequest = new DSDataRequest()
    {
        Instrument = new DSInstrument() { Value = "VOD" },
        DataTypes = new[] { new DSDataType() { Value = "PL" }, new DSDataType() { Value = "PH" } },
        Date = new DSDate() { Kind = DSDateKind.TimeSeries, Start = "-30D", End = "-10D"
                    Frequency = DSDateFrequencyNames.D.ToString() }
    }
};

// Get the data
DSDataResponse response = null;
using (var dsclient = new DSServiceClient())
    response = dsclient.GetData(request).DataResponse;

// Process the response
foreach (var datatypeValue in response.DataTypeValues)
{
    // This is the datatype requested
    string requestedDataType = datatypeValue.DataType;

    // Access the symbols for the datatype
    // If the requested instrument was a list, there will be multiple symbols
    foreach (var symbolVal in datatypeValue.SymbolValues)
    {
        string symbol = symbolVal.Symbol;
        if (symbolVal.Type == DSSymbolResponseValueType.Error)
        {
            // The symbol value is an error - perhaps there is no data
            string errorMessage = symbolVal.Value.ToString();
        }
        else if (symbolVal.Type == DSSymbolResponseValueType.DoubleArray)
        {
            // The symbol value is a double array
            double[] values = (double[]) symbolVal.Value;
                        
        }
    }
}

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

// Create data requests
var req1 = new DSDataRequest()
{
    Instrument = new DSInstrument() { Value = "VOD" },
    DataTypes = new new[] { new DSDataType() { Value = "PL" } },
    Date = new DSDate() { Kind = DSDateKind.Snapshot, Start = "-10D" },
};

var req2 = new DSDataRequest()
{
    Instrument = new DSInstrument() { Value = "BARC" },
    DataTypes = new new[] { new DSDataType() { Value = "PH" } },
    Date = new DSDate() { Kind = DSDateKind.Snapshot, Start = "-30D" },
};

// Bundle the requests
var bundleReq = new DSGetDataBundleRequest()
{
    TokenValue = TokenGotThroGetToken(),
    DataRequests = new[] { req1, req2 },
};

// Get the data for multiple requests
DSDataResponse[] responses = null;
using (var dsclient = new DSServiceClient())
    responses = dsclient.GetDataBundle(bundleReq).DataResponses;

// Process each request's response
foreach (var response in responses)
{
    foreach (var datatypeValue in response.DataTypeValues)
    {
        string datatype = datatypeValue.DataType;
        foreach (var symbolValue in datatypeValue.SymbolValues)
        {
            string symbol = symbolValue.Symbol;
            if (symbolVal.Type == DSSymbolResponseValueType.Error)
            {
                // The symbol value is an error - perhaps there is no data
                string errorMessage = symbolVal.Value.ToString();
            }
            else if (symbolVal.Type == DSSymbolResponseValueType.DoubleArray)
            {
                // The symbol value is a double array
                double[] values = (double[]) symbolVal.Value;
                        
            }
        }
    }
}        

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