| Tutorial Source Code |
Examples referenced: |
| Last Update | July 2021 |
| Interpreter | Python 3.7.x or greater |
| Pre-requisites | Familiarity with Python and a basic understanding of Jupyter Notebook. If accessing content from:
The majority of the examples are built to work within Jupyter Notebook. Ensure this package is installed. |
| Additional Reading | Symbology documentation: |
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)
response = symbol_conversion.Definition(symbols=["MSFT.O", "US5949181045", "GOOG.O", "BH4HKS3"]).get_data()
response.data.df
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
response = symbol_conversion.Definition(
symbols=["US5949181045", "US02079K1079"],
from_symbol_type=symbol_conversion.SymbolTypes.ISIN,
to_symbol_types=[
symbol_conversion.SymbolTypes.RIC
],
).get_data()
response.data.df
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
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 checks if the response contains the raw data and/or a dataframe.
# Check if the response contains the raw data?
if response.data.raw:
display(response.data.raw)
else:
print("Response does not contain raw data")
# Check if the response contains a Dataframe too?
if (not response.data.df.empty):
display(response.data.df)
else:
print("\nResponse does not contain DataFrame")
Executing the Tutorial
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 with the ability to reference the endpoint directly, apply request parameters and receive raw JSON data from the platform.