| Tutorial Source Code |
Examples referenced:
|
| Last Update | March 2022 |
| 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 Refinitiv Data Platform (RDP) defines a number of discrete services providing well-defined endpoints supporting reference, pricing, and analytics data through its Endpoint Request interfaces.
Using the Refinitiv Data Libraries, the following tutorial will outline sample code that provides access to a number of RDP endpoints, supporting different mechanisms to request for data, whether specifying a basic URL, applying query parameters to a URL, or defining a request body via the HTTP POST. The tutorial will cover multiple data services to demonstrate specific features of the library. The latter part of the tutorial will demonstrate a few examples of the interfaces.
Note: In most cases, users of the Refinitiv Data Libraries will utilize interfaces defined within higher layers, such as those defined within the Content layer to retrieve data within the platform. Higher-level interfaces such as the HistoricalPricing, Search, News understand the nature of the specific services and thus define intuitive methods to not only request for data but to extract details within responses. The purpose of this exercise is to bridge the gap where higher-level interfaces do not support specific endpoints, whether they are new, or just not as popular as others.
Defining an Endpoint
At the heart of the Endpoint Request interfaces, is the data endpoint URL. For example, the following data services are represented by their endpoint URLs:
- Historical Pricing: https://api.refinitiv.com/data/historical-pricing/v1/views/events
- News Headlines: https://api.refinitiv.com/data/news/v1/headlines
- Symbology Lookup: https://api.refinitiv.com/discovery/symbology/v1/lookup
When creating a request to retrieve data from an endpoint, the first step is to define the endpoint URL within the interfaces. For example:
// RDP Symbology lookup endpoint URL
var endpoint = https://api.refinitiv.com/discovery/symbology/v1/lookup;
// Endpoint Request definition for the symbology lookup service
const def = Delivery.EndpointRequest.Definition(endpoint);
Once a request definition is in place and depending on the service, you may need to define additional properties to be included within your request. The libraries support a number of interfaces to define the properties of your request as well as the ability to execute the request to retrieve the content.
Defining request properties
Depending on the service and how you choose to prepare your endpoint URL, the interfaces support the ability to specify additional properties to be included within your request. The following request features are available:
- Query Parameters
Endpoint URLs supporting query strings are represented as field=value pairs.
Eg: https://api.refinitiv.com/data/environmental-social-governance/v2/views/basic?universe=IBM.N
- Path Parameters
In some cases, URLs define parameters that are embedded within the URL. When defining the URL as part of your application, you must enclose the path parameter(s) within curly braces.
Eg: https://api.refinitiv.com/data/historical-pricing/v1/views/events/{universe}
- Header Parameters
Endpoints that enforce different content types or formats, typically require the specification within the header portion of the HTTP request. For example, the endpoint to retrieve a news story offers the ability to specify the response format as either "text/html" or "application/json", which is specified within the HTTP header of the request.
- Body Parameters
Many of the RDP endpoints support the HTTP POST defining the ability to specify a body of data in the request. The libraries support the ability to specify JSON details within the support endpoint request.
The following simple code segments demonstrate the above mechanisms:
Query Properties
// Use of query parameters in News Headlines request
const param: Delivery.EndpointRequestDefinitionParams = {
url: 'data/news/v1/headlines',
query: { query: 'Adidas and searchIn:HeadlineOnly and L:EN' },
};
Note: Multiple calls to define a query are additive. That is, endpoints that require multiple parameters in the form of name1=value&name2=value&, can be specified by issuing multiple query requests.
Path Properties
// Use of path parameters in historical data
const params: Delivery.EndpointRequestDefinitionParams = {
url: 'data/historical-pricing/v1/views/events/{universe}',
path: { universe: 'VOD.L' }
};
Header Properties
// an example of how to set headers property
const param: Delivery.EndpointRequestDefinitionParams = {
url: 'data/news/v1/headlines',
query: { query: 'Adidas' },
headers: {accept: 'text/html'}
};
Body Parameters
// set the body parameters for a HTTP POST request
const params: Delivery.EndpointRequestDefinitionParams = {
url: 'discovery/symbology/v1/lookup',
body: {
from: [{'identifierTypes': ['RIC'], 'values': ['MSFT.O']}],
to: [{
'identifierTypes': ["ISIN", "LEI", "ExchangeTicker"]
}],
type: 'auto'
},
method: Delivery.EndpointRequest.Method.POST,
};
Requesting data and processing the response
The following code segment defines the mechanism to request and process data:
// HTTP-GET endpoint request
const params: Delivery.EndpointRequestDefinitionParams = ...
const def = Delivery.EndpointRequest.Definition(params);
// invoke the request
const response = await def.getData(session);
// response.data contains the server JSON response
console.log('Received data:', response.data);
Examples
Each example will demonstrate a number of different features available within the Refinitiv Data Libraries when using the endpoint request interfaces. You can refer to the example package for complete source code and the ability to set up and execute each.
Within the source code package, select the source code example within the Delivery section. To execute each example, refer to the pre-requisites section at the top of this tutorial.
Historical Pricing
In this example, we'll demonstrate some basic syntax to retrieve historical pricing events for a company.
// HTTP-GET endpoint request
const params: Delivery.EndpointRequestDefinitionParams = {
url: 'data/historical-pricing/v1/views/events/{universe}',
path: { universe: 'VOD.L' },
query: { 'count': '5' },
};
const def = Delivery.EndpointRequest.Definition(params);
const response = await def.getData(session);
In the second example, we utilize a Query Parameter (count), to limit the number of data points returned. In both examples, we rely on default parameters, specifically the fields returned in the response. The Historical Endpoint service provides a number of parameters, including the specification of fields to be returned. When no fields are specified, all will be returned.
Here is an example of what the output will look like:
The example displays the raw data from the platform. In this example, we're showing a portion of the data, specifically some metadata and header information related to the fields, plus data arrays (not shown) appearing below.
Note: The specification of the Historical Pricing endpoint hard-codes the company specifier. In reality, users will likely utilize the Path Parameter specification to populate the company identifier, but this was intentionally done to demonstrate flexibility and how basic the syntax is to retrieve content from the platform.
Symbology Lookup
In this example, we'll demonstrate the ability to POST a request by applying a JSON object that outlines parameters required by the Symbology Lookup endpoint defined within RDP. In this first code segment, we'll define the endpoint and POST request definition to be used by multiple calls outlined within the example. With our endpoint definition in place, let's create a JSON object that will be applied to the body of the request. In this specific example, we wish to convert a RIC to multiple identifiers, specifically 'ISIN', 'LEI', and the 'ExchangeTicker'.
// HTTP-POST endpoint request
const params: Delivery.EndpointRequestDefinitionParams = {
url: 'discovery/symbology/v1/lookup',
body: {
from: [{'identifierTypes': ['RIC'], 'values': ['MSFT.O']}],
to: [{
'identifierTypes': ["ISIN", "LEI", "ExchangeTicker"]
}],
type: 'auto'
},
method: Delivery.EndpointRequest.Method.POST,
};
const def = Delivery.EndpointRequest.Definition(params);
const response = await def.getData(session);
The above output represents the raw data from the platform, including the "output" stanza containing the conversion results.
Next Steps
The details outlined provide a good cross-section of the interfaces available to retrieve data defined within RESTful endpoints available within the data platform. As mentioned in the introduction, the endpoint requests presented here will be extremely useful for those services that are not available within higher layers of the libraries. There are many content-specific interfaces, such as Historical Pricing, Symbology, News, ESG, Search available that will further simplify usage to retrieve data. Refer to the Content tutorials within this API for more details.