| Tutorial Source Code |
Examples referenced:
|
| Last Update | July 2021 |
| Compiler/Runtime | See Getting Started with TypeScript. |
| Pre-requisites | Enable the session environment as outlined within the Getting Started guide. |
Overview
Whether accessing from the desktop or directly to the cloud, the Refinitiv Data Libraries provide ease-of-use interfaces to retrieve content defined within standard web-based APIs. Built on top of the request-response paradigm, the library includes a SymbolConversion interface that performs a best-match resolution of multiple symbols returning the single highest-ranking match, if any.
The following tutorial demonstrates a few use cases showing different ways to convert symbols. The interface supports a finite list of symbol types such as a Ticker, RIC, SEDOL, CUSIP, LipperID, ISIN, and PermID.
Note: The Symbol Conversion interface is presently built on top of the Search Lookup endpoint. While the Symbology endpoint provides a comprehensive conversion capability allowing a wide range of symbol types resulting in 1 to many relationships, it does not presently provide a simple way to perform a best-match resolution.
Basic conversions
The conversion interface supports the ability to detect the type of symbol based on its value. That is, if a list of mixed symbol types is ingested into the interface, the service will detect the symbol type and automatically convert. For example, the following code segment will take a list of mixed-typed instruments and automatically detect and convert each one.
// Convert 4 symbol types (ticker, ISIN, CUSIP, SEDOL)
await doSymbolConversion(`\nDetect and convert symbols of mixed type`, {
symbols: ["IBM", "US5949181045", "037833100", "BH4HKS3"]
});
In the above example, a list of different symbol types was provided as part of the definition. By default, the conversion service automatically detected the type for each and converted, where possible, to each of the symbol types available. it's is worth noting that the conversion service may not detect all types of symbols, for example, a Lipper ID. In these cases, you will need to bundle these undetected types and instruct the interface to expect a specific type. The next section describes this capability.
Specifying the symbol type
While the default behavior is very convenient, there may use cases where we feed into the interface a collection of know types and force the interface to verify and convert to a specific type. For example:
// // ISIN to RIC conversion
await doSymbolConversion(`\nISIN to RIC conversion for 2 items:`, {
symbols: ["US5949181045", "US02079K1079"],
fromSymbolType: SymbolConversion.SymbolType.ISIN,
toSymbolType: SymbolConversion.SymbolType.RIC,
});
Instead of relying on the conversion service to detect the type of symbols provided, we explicitly instruct the service to verify the provided symbols as a specific type. This way, we can rely on the engines to ignore any values that are not valid types. Additionally, we may choose to convert the symbols to a specific type, for example, a RIC.by explicitly instructing the service to convert to one or more types.
Data structure returned
All request-reply responses will carry standard response details such as the success of the response, HTTP status details, which include reasons why the request may fail, and a data section containing details specific to the service. The structure and format of the data returned from a conversion contain a table representing the list of symbols and values converted.
The following code segment determines if the request was successful, using a simple boolean property available within the response. Upon success, we begin to extract and display details populated within the data. Upon failure, the details of why the underlying HTTP request failed are displayed. In this specific example, we are only processing the data table containing the rows of symbols provided and the conversion types.
const doSymbolConversion = async function (title: string, params: SymbolConversion.Params) {
const definition = SymbolConversion.Definition(params);
const convRes = await definition.getData(session);
console.log(title);
if (convRes.data.table)
console.table(convRes.data.table);
else
console.log('No symbol conversion result received');
};
The table of data representing the document hit is organized as a 2-dimensional grid of rows and columns. The rows represent each symbol and the columns contain the converted symbol types.
Executing the Application
In our examples, we've prepared a number of code segments demonstrating different features of Symbology conversion. To execute the examples within the source code package, refer to the pre-requisites section at the top of this tutorial.
Refer to the above screenshots to compare the output expected from the execution for some of the code segments.
This tutorial was meant as a simple guide to get you familiar with Symbol conversion and what it can provide. As outlined at the beginning of the tutorial, the library utilizes the Search Lookup endpoint because of its simple, best-fit conversion that is presently unavailable within the Symbology endpoint. However, the Symbology service does provide a very rich interface the allows data mapping and navigation across the Refinitiv information model. Specifically, the API enables customers to map from external identifiers to a Refinitiv PermID and to navigate between a wide range of identifiers. If there is a requirement to explore more complex relationships and navigation between other identifiers, we would encourage the use of the Endpoint Request interface offered within the Delivery Layer outlined in this section. The Endpoint Request provides the user the ability to reference the endpoint directly, apply request parameters and receive raw JSON data from the platform.