DataScope Select - REST API

Close Menu
Expand All Collapse All
Introductory Tutorials Tutorials Introduction Programming without SDK Tutorial REST API Tutorials REST API Tutorials Introduction REST API Tutorial 1: Connecting to the DSS server REST API Tutorial 2: On Demand End of Day Extraction REST API Tutorial 3: On Demand intraday extraction, embargo REST API Tutorial 4: On Demand price history extraction REST API Tutorial 5: On Demand corporate actions extraction REST API Tutorial 6: On Demand ownership data extraction REST API Tutorial 7: On Demand T&C extraction REST API Tutorial 8: On Demand composite extraction REST API Tutorial 9: On Demand extraction: instrument list REST API Tutorial 10: GUI control calls: immediate extract REST API Tutorial 11: Search by Instrument REST API Tutorial 12: Search for an Equity REST API Tutorial 13: Search for a Future or Option REST API Tutorial 14: On Demand price history extraction raw .Net SDK Tutorials .Net SDK Tutorial 1: Connecting to the DSS server .Net SDK Tutorial 2: GUI control calls: List, report, sched .Net SDK Tutorial 3: GUI control calls: Validate, extraction .Net SDK Tutorial 4: GUI control calls: Embargo, note files .Net SDK Tutorial 5: On Demand: EoD extraction .Net SDK Tutorial 6: On Demand: EoD extraction, file I/O .Net SDK Tutorial 7: On Demand: large instrument lists .Net SDK Tutorial 8: On Demand: Terms & Conditions .Net SDK Tutorial 9: On Demand: Composite extraction .Net SDK Tutorial 10: Search by Instrument .Net SDK Tutorial 11: Search for Equity .Net SDK Tutorial 12: Search for Future or Option

.Net SDK Tutorial 10: Search by Instrument

Last update July 2019
Environment Windows
Language C#
Compilers Microsoft Visual Studio 2012/2013
Prerequisites DSS login, internet access, having done the previous tutorials
Source code Download .Net SDK Tutorials Code

Tutorial purpose

This is the tenth tutorial in a series of .Net SDK tutorials. It is assumed that the reader has acquired the knowledge delivered in the previous tutorials before following this one.

This tutorial is the first covering searches. It explains how to make a search request, using as criteria the instrument code. This is illustrated with two examples, which can be extended to other instrument codes:

  • Search using the Reuters Instrument Code (RIC).
  • Search using the Organisation Id (OrgId).

Such a search can also be used to validate a list of instruments (as illustrated by the first example).

You can choose to have results in a different instrument code type (as illustrated by the second example).

 

Table of contents

 

Getting ready

Opening the solution

The code installation was done in Tutorial 1.

Opening the solution is similar to what was done in the previous tutorials:

  • Navigate to the \DSS REST API\Tutorial 10\Learning folder.
  • Double click on the solution file rest_api_ric_search.sln to open it in Microsoft Visual Studio.

 

Referencing the DSS SDK

Before anything else, you must reference the DSS REST API .Net SDK in the Microsoft Visual Studio project.

Important: this must be done for every single tutorial, for both the learning and refactored versions.

This was explained in the tutorial 2; please refer to it for instructions.

 

Viewing the C# code

In Microsoft Visual Studio, in the Solution Explorer, double click on Program.cs and on DssClient.cs to display both file contents. Each file will be displayed in a separate tab.

 

Setting the user account

Before running the code, you must replace  YourUserId  with your DSS user name, and  YourPassword  with your DSS password, in these 2 lines of Program.cs:

        private static string dssUserName = "YourUserId";
        private static string dssUserPassword = "YourPassword";

Important reminder: this must be done for every single tutorial, for both the learning and refactored versions.

Failure to do so will result in an error at run time (see Tutorial 1 for more details).

 

Understanding the code

We shall only describe what is new versus the previous tutorials.

DssClient.cs

This is the same as the version of Tutorial 9, except for the leading comment, and the addition of a search context.

Up to now we were doing extractions which required an extraction context, now we must add a search context.

It is declared and initialized in the same way as an extraction context:

//searchContext temporarily set to public, to expose it to our learning program.
public SearchContext searchContext;

public void ConnectToServer(string dssUserName, string dssUserPassword)
{
    extractionsContext = new ExtractionsContext(dssUri, dssUserName, dssUserPassword);
    searchContext = new SearchContext(dssUri, dssUserName, dssUserPassword);
}

 

Program.cs

The search context is exposed here:

SearchContext searchContext = dssClient.searchContext;

 

Creating the instrument identifiers string

The instruments identifiers we search for must all be of the same type; we cannot mix several types (Ric, Cusip, Isin, etc.) in a single query. We must specify the type we use.

The sample code defines an array of RICs (these might have been read from a CSV file or a database).

An invalid one is included to demonstrate that nothing will be returned for it; this is a way to validate instrument identifiers.

It is possible to use * as a wild card, like:   "IBM*",

The code also contains a commented part that can be used to test with OrgIds instead of Rics:

//Rics:
IdentifierType inputInstrumentsIdentifierType = IdentifierType.Ric;
string[] inputInstruments = { "US10YT=RRPS", "JPY=", "IBM.N", "INVALID.RIC" };
IdentifierType preferredResultIdentifierType = IdentifierType.Ric;
//OrgIds:
//IdentifierType inputInstrumentsIdentifierType = IdentifierType.OrgId;
//string[] inputInstruments = { "18174", "18175" };
//IdentifierType preferredResultIdentifierType = IdentifierType.OrgId;

In the code above we also set the preferred output identifier type. Set it to the same value as the input type if you want to validate the input list.

The API expects a comma separated string as input, which we create from the array:

string inputInstrumentsString = string.Join(",", inputInstruments);

 

Performing the search

We can set a limit to the number of records in the result:

searchContext.Preferences.MaxPageSize = 100;

When creating the search request, we specify:

  • The instrument type groups we are interested in, to filter results (the sample code contains all possibilities),
  • The input instruments identifier type,
  • The preferred output instruments identifier type (note: returned results might contain different types).

The input instrument string we defined in the previous step is also used as a parameter:

IDssEnumerable<ValidatedInstrument> resultingInstruments =
    searchContext.InstrumentSearch(
        AllInstrumentSearchRequest.Create(
            new[] { 
                InstrumentTypeGroup.CollatetizedMortgageObligations,
                InstrumentTypeGroup.Commodities, InstrumentTypeGroup.Equities,
                InstrumentTypeGroup.Funds, InstrumentTypeGroup.FuturesAndOptions,
                InstrumentTypeGroup.GovCorp, InstrumentTypeGroup.MortgageBackedSecurities,
                InstrumentTypeGroup.Money, InstrumentTypeGroup.Municipals
            },
            inputInstrumentsIdentifierType,
            inputInstrumentsString,
            preferredResultIdentifierType));

 

Displaying the results

The result contains details on each returned instrument. The code displays some details, and the number of results:

foreach (ValidatedInstrument instrument in resultingInstruments)
{
    Console.WriteLine("{0}\n - IdentifierType: {1}\n - InstrumentType: {2}\n - Status: {3}\n - Description: {4}",
        instrument.Identifier,
        instrument.IdentifierType, instrument.InstrumentType,
        instrument.Status, instrument.Description);
}
int numberOfResults = resultingInstruments.Count();
Console.WriteLine("\nNumber of results: {0}", numberOfResults);

 

Validation code

The sample includes some code to calculate and display validation counts, and list all non validated instrument identifiers. This is only for the case where the input and output instrument identifier types are the same.

This fairly simple code is included just as an illustration; it is not specific to the API, explanations are out of scope here.

 

Full code

The full code can be displayed by opening the appropriate solution file in Microsoft Visual Studio.

 

Summary

List of the main steps in the code:

  1. Authenticate by creating a search context.
  2. Create a string of financial instrument identifiers.
  3. Run the search, wait for it to complete.
  4. Treat the returned data.

 

Refactored version

There is none for this tutorial.

 

Code run results

Build and run

Don’t forget to reference the DSS SDK, and to set your user account in Program.cs !

 

Successful run

After running the program, and pressing the Enter key when prompted, the final result should look like this:

 

Potential errors and solutions

If the user name and password were not set properly, an error will be returned. See Tutorial 1 for details.

 

Conclusions

This tutorial introduced a simple instrument search, based on the instrument identifier.

Now move on to the next tutorial, which covers another search type.

Tutorial Group: 
.Net SDK Tutorials