The Datastream Web Service 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 the service. You can obtain a token by calling GetToken() method. You have to pass as part of this method your Datastream Id (eg. 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:

Copy 
// Create a token request
var tokenRequest = new DSGetTokenRequest()
{
    UserName = "yourDatastreamId",
    Password = "yourpassword",
};

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 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, 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.

the service 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:

Copy 
// 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 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:

Copy 
// 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:

Copy 
// 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:

Copy 
// 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;
                        
            }
        }
    }
}     
NoteNote

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

REQUEST LIMITS

Whilst each DSDataRequest object supports multiple instruments and datatypes, request limits are imposed by the system. Any one DSDataRequest is restricted to the following limits:

  • The maximum number of instruments that can be requested: 50
  • The maximum number of datatypes that can be requested: 50
  • The maximum number of items (instruments x datatypes) that can be requested: 100

The above limits permit the following example permutations in any one DSDataRequest:

  • 50 instruments x 2 datatypes
  • 2 instruments x 50 datatypes
  • 1 constituent list x 50 datatypes (you can never request more than one constituent list)
  • 10 instruments x 10 datatypes

 

When used with GetDataBundle requests, where a collection of DSDataRequest objects can be combined, there are additional limits imposed on the number of items that can be requested across the bundle:

  • The maximum number of DSDataRequests per bundled request: 20
  • The maximum number of items (instruments x datatypes) across all DSDataRequests: 500

The above limits permit the following example permutations in any one GetDataBundle request:

  • Up to 5 DSDataRequests each requesting 100 items
  • 10 DSDataRequests each requesting 50 items
  • 20 DSDataRequests each requesting 25 items

SEE ALSO