Datastream Web Service provides a client API to access Datastream content. The APIs are distributed as .NET libraries targetting various framework versions such as .NET 3.5, 4.0 and 4.5. The APIs offer elegant interfaces making use of language features. Further, Visual Studio's intellisense features would make the integration much easier when the .NET APIs are used. Functionalities such as token management, asynchronous access etc. are available out of the box. If your application is built using .NET, then the .NET API based solution is our recommended approach.

GETTING STARTED

First download the .NET API library from here based on the .NET framework version your application uses. Add Reference to the downloaded assembly in your application. You can then access methods in the entry point class DSClient to retrieve data from the service. The following are the steps you will typically use during integration:

  • Configure API options (including credentials) through code or your config file.
  • Create a data request by specifying an instrument, the data types, date information etc.
  • Call GetData method
  • Access various properties of the response.

The API allows bundling many data requests, invoking the methods asynchronously and offers various endpoint types to connect to. The below code snippet is an example of a typical usage:

Copy 
using Datastream.DswsApi;
void OnMyAppStart()
{
     // Configure options when the application starts
     // You can do this in code as illustrated here using your Datastream Id
     // Alternatively you can use the appSettings element of your config file (Ex: Web.config/App.config)
     
     DSClient.Options.UserName = "yourDatastreamId";
     DSClient.Options.Password = "yourpassword";
     DSClient.Init();
}

void OnMyGetDswsData()
{
     // Create a data request 
     var request = new DSDataRequest()
     {
         Instrument = new DSInstrument("VOD"),
         DataTypes = new DSDataTypes("PL", "PH"),
         Date = new DSTimeSeriesDate(DSDateType.Relative(-30), DSDateType.Relative(-10), DSDateFrequency.Daily)
     };

     // Execute the request 
     var response = DSClient.DataService.GetData(request);

     // Get the response value 
     double[] dt1Values = response["PL"]["VOD"].GetValue<double[]>();
     double[] dt2Values = response["PH"]["VOD"].GetValue<double[]>();
 }

 void OnMyAppShutDown()
 {
     // Shutdown when the application is closed
     DSClient.ShutDown();
 }

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 use one or more instruments as part of a request.

The data types contain the field codes for which you want to retrieve the data. You can browse the available data types from here or use DSDataTypeCodes to select the data types during development.

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. You can use absolute dates, relative dates or certain literals as dates.

You can also specify additional request properties to customize your responses. Following code snippets provide details for constructing instruments, data types and dates:

Copy 
// Instrument 
// Create a single instrument 
var singleInstr = new DSInstrument("VOD");

// Create multiple instruments 
var multiInstr = new DSInstrument("VOD", "BARC", "MSFT");

// Create an expression 
var expr = new DSInstrument("VOD(PL) + VOD(PH)", DSInstrumentProperties.IsExpression);

// DataTypes 
// Create a single datatype 
var datatypes1 = new DSDataTypes("PH");

// Create multiple datatypes 
var datatypes2 = new DSDataTypes("PH", "PL", "MV", "P");

// Create datatype using literals 
var datatypes3 = new DSDataTypes(DSDataTypeCodes.Equity.Pricing.PH);

// Date (Snapshot) 
// An absolute date 
var date1 = new DSSnapshotDate(DSDateType.Absolute(DateTime.Now));

// A relative date 
var date2 = new DSSnapshotDate(DSDateType.Relative(-20));

// A relative date with frequency 
var date3 = new DSSnapshotDate(DSDateType.Relative(-20, DSDateFrequency.Monthly));

// A literal date 
var date4 = new DSSnapshotDate(DSDateType.Literal(DSDateLiterals.StartDateOfQuarter));

// Dont specify date 
var date5 = new DSSnapshotDate(null);

// Date (TimeSeries) 
// Start/End specified as absolute dates 
var date1 = new DSTimeSeriesDate(DSDateType.Absolute(DateTime.Now.AddDays(-20)), 
    DSDateType.Absolute(DateTime.Now), DSDateFrequency.Daily);

// Start/End specified as relative dates 
var date2 = new DSTimeSeriesDate(DSDateType.Relative(-20), 
    DSDateType.Relative(0), DSDateFrequency.Daily);

// Start/End specified as literals 
var date3 = new DSTimeSeriesDate(DSDateType.Literal(DSDateLiterals.StartDateOfQuarter), 
    DSDateType.Absolute(DateTime.Now), DSDateFrequency.Weekly);

// Dont specify date 
var date4 = new DSTimeSeriesDate(null, null, DSDateFrequency.None);

//  
// Request 
var request = new DSDataRequest()
{
    Instrument = new DSInstrument("VOD"),
    DataTypes = new DSDataTypes("PL", "PH"),
    Date = new DSTimeSeriesDate(DSDateType.Relative(-30), DSDateType.Relative(-10), DSDateFrequency.Daily),
    Properties = new DSDataRequestProperties(DSDataRequestPropertyTypes.ReturnCurrency | 
      DSDataRequestPropertyTypes.ReturnInstrumentExpandedName),
};

UNDERSTANDING RESPONSES

A data response contains all the requested data types, and, for each data type, the values corresponding to instruments. You can either use the indexers to directly ask the response value for your request's datatype/instrument or you can enumerate the responses. 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 an exception being thrown. 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.

Copy 
// Access the response through indexers 
double[] dt1Values = response["PL"]["VOD"].GetValue<double[]>();
double[] dt2Values = response["PH"]["VOD"].GetValue<double[]>();

// Access the response through enumeration 
foreach (var datatypeValue in response.DataTypeValues)
{
    Trace.WriteLine(string.Format("----DataType: {0}", datatypeValue.DataType));

    foreach (var symbol in datatypeValue.SymbolValues)
    {
        Trace.WriteLine(string.Format("Symbol: {0}", symbol.Symbol));
        Trace.WriteLine(string.Format("Value Type: {0}", symbol.Type));
        Trace.WriteLine(string.Format("Values Length: {0}", symbol.Value is Array 
                                    ? ((Array)symbol.Value).GetLength(0) : 0));
    }
}

DATA RETRIEVAL

After constructing a data request, the GetData method can be used to actually retrieve the data. If you want to retrieve data for multiple requests at the same time, it might be a good idea to use the GetDataBundle method which packs multiple requests into a single server call. Note that calling these methods result in a synchronous call to the server. Also these methods would perform an on-demand login to the server to validate your credentials and obtain a token. Token retrieval is not performed every time you call these methods. It is performed only if a valid token is not already available. Following code example shows how to retrieve data synchronously:

Copy 
void OnGetData()
{
     // Create a data request 
     var request = new DSDataRequest()
     {
         Instrument = new DSInstrument("VOD"),
         DataTypes = new DSDataTypes("PL", "PH"),
         Date = new DSTimeSeriesDate(DSDateType.Relative(-30), DSDateType.Relative(-10), DSDateFrequency.Daily)
     };

     // Execute the request 
     var response = DSClient.DataService.GetData(request);

     // Get the response value 
     double[] dt1Values = response["PL"]["VOD"].GetValue<double[]>();
     double[] dt2Values = response["PH"]["VOD"].GetValue<double[]>();
 }

 void OnGetMultipleData()
 {
    // Create data requests
    var req1 = new DSDataRequest()
    {
        Instrument = new DSInstrument("VOD"),
        DataTypes = new DSDataTypes("PL", "PH"),
        Date = new DSTimeSeriesDate(DSDateType.Relative(-30), DSDateType.Relative(-10), DSDateFrequency.Daily)
    };

    var req2 = new DSDataRequest()
    {
        Instrument = new DSInstrument("BARC"),
        DataTypes = new DSDataTypes("MV", "P"),
        Date = new DSSnapshotDate(DSDateType.Absolute(DateTime.Now.AddYears(-1))),
    };

    // Get the data for multiple requests
    var resps = DSClient.DataService.GetDataBundle(new[] { req1, req2 });

    // Process each request's response
    foreach (var resp in resps)
    {
        foreach (var datatypeValue in resp.DataTypeValues)
        {
            string datatype = datatypeValue.DataType;
            foreach (var symbolValue in datatypeValue.SymbolValues)
            {
                string symbol = symbolValue.Symbol;
                var value = symbolValue.GetValue<double[]>();
            }
        }
    }
        
 }

ASYNCHRONOUS PATTERN

The .NET API library supports asynchronous requests and responses. You can either use the event based asynchronous pattern or the IAsyncResult based pattern. If you are using .NET 4.0 or above, then you can also use the task based asynchronous pattern.

You can refer here for the relevant methods needed for asynchronous programming. The below code snippet shows an example of asynchronous access using the task based (.NET 4.0) and event based (.NET 3.5) pattern.

Copy 
// Create a data request
var request = new DSDataRequest()
{
    Instrument = new DSInstrument("VOD"),
    DataTypes = new DSDataTypes("PL", "PH"),
    Date = new DSTimeSeriesDate(DSDateType.Relative(-30), DSDateType.Relative(-10), DSDateFrequency.Daily)
};

//            
// Execute asynchronously using Task based Async pattern (.NET 4.0 and above)
var task = DSClient.DataServiceAsync.GetDataAsync(request);

// Make sure when the task completes, we process the result 
// If you want to show results in UI, make sure you pass a valid sync context to TPL
task.ContinueWith(t =>
{
    // After the task is completed, access the results  
    double[] dt1Values = t.Result["PL"]["VOD"].GetValue<double[]>();
    double[] dt2Values = t.Result["PH"]["VOD"].GetValue<double[]>();

    ShowResultsInUI();

}, TaskScheduler.FromCurrentSynchronizationContext());


//  
// Execute asynchronously using Event based Async pattern (.NET 3.5)
// Make sure you have wired to Completed events ONCE when your application starts
DSClient.DataServiceAsync.GetDataCompleted += (s, args) =>
{
        // Access the results 
        double[] dt1Values = args.Result["PL"]["VOD"].GetValue<double[]>();
        double[] dt2Values = args.Result["PH"]["VOD"].GetValue<double[]>();

        // Show the output in UI 
        // Note that you can use args.UserState if you passed some state during the GetDataAsync call 
        // You might potentially use the state to differentiate your requests
        ShowResultsInUI();

};

// Make the async request
DSClient.DataServiceAsync.GetDataAsync(request, "MyState-Request1");

SEE ALSO