Converting ISINs to RICs using the TRTH REST API

Introduction

This article investigates several use cases that involve translating ISINs into RICs, or retrieving data using ISINs directly, with the TRTH (Thomson Reuters Tick History) REST API. To keep it short we will concentrate on the TRTH REST API.

You will need some basic TRTH v2 GUI and TRTH REST API knowledge to understand this article. If you want to test the code a valid TRTH v2 user account is also required.

A separate article covers the same topic for DSS REST API users.

Instrument identifier codes

Instrument identifiers can be referred to using several coding systems.

Thomson Reuters products use RICs (Reuters Instrument Codes), which uniquely identify financial instruments, including where they are traded. As an example, IBM.N identifies the IBM stock traded on NYSE, and IBM.L identifies the IBM stock traded on LSE. The RIC syntax here is <ticker>.<exchange>, which is the most common syntax in use, but there are cases where the syntax is different (options, futures, FX, etc.).

Several other codes are in use in the financial world (ISIN, Sedol, Cusip, etc.). One of the popular ones is ISINs (International Securities Identification Number) which uniquely identify securities, but do not identify the venue (or exchange) where they are traded. For example, US4592001014 identifies the IBM stock (whatever venue it is traded on).

Mapping ISINs to RICs

As an ISIN does not identify the venue, a single ISIN maps to several RICs. For example, the IBM ISIN US4592001014 maps to more than 50 RICs, one for each data source (i.e. venue or exchange): IBM.LM, IBM.MX, IBM.BE, IBM.HA, IBM.H, IBMI.L, etc.

To request data on TRTH you might use the ISIN, but in most cases this returns data for all corresponding RICs, which is rarely required. For other Thomson Reuters products (like Elektron) you must use the RIC. It is therefore often required to map ISINs (or other codes) to RICs.

Primary RIC

One of the RICs is the primary RIC. It identifies the exchange with the primary listing for the instrument (i.e. the venue where it was originally listed, which is usually in the country of origin of the company). In the case of IBM the primary exchange is NYSE, and the Primary RIC is IBM.N.

Other identifier types: Cusip, Sedol

This article uses ISINs as an example, because their use is widespread, but everything in this article can also be applied when working with Cusips and Sedols.

Instruments and code extracts used in this article

We use 4 ISINs in our examples:

ISIN Asset class Comment Primary RIC Primary Exchange
US4592001014 Equity   IBM.N  NYS
GB00B29MWZ99 Equity Delisted Sept. 2009 TRIL.L LSE
DE000C0JK7R7 Future derivative Expires Sept. 2017 STXXU7 EUX
DE0001135317 Bond Expired 4 Apr. 2017 N/A CPL

The code extracts are based on pure HTTP requests. To try them out you can cut and paste them into a REST client, like Postman. This is explained in the REST API Tutorials Introduction. You can also download the associated Postman environment and collection to avoid copy/pasting. All request headers must contain an authentication token; refer to the REST API Tutorial 1 for details.

The full workflow for some requests is omitted for clarity, but when required you will find pointers to the tutorials where the details are explained.

Delisted RICs

Some queries might return delisted RICs among the results. A delisted RIC is no longer listed on the exchange, there are no quotes, and it is no longer tradable. One is included in our list, TRIL.L, the old RIC for Thomson Reuters, delisted in September 2009.

You can recognize delisted RICs in results through a special syntax: TRIL.L^I09

Here is the syntax: the original RIC (TRIL.L) followed by “^”, followed by a month code and a year code that indicate when the RIC was delisted. For equities the month code starts at “A” for January, so “I” is for September. The year code 09 means 2009.

Use cases

When converting an ISIN to RIC(s) there are 3 main use cases:

  1. We want the primary RIC
  2. We want the RIC(s) for a particular exchange (or currency), or a set of exchanges
  3. We want all the RICs

Another use case could be that we want to find the primary exchange.

There are different ways to go about these use cases.

Manually performing a bulk historical search

Before moving to the API calls, I’d like to mention a nice TRTH v2 GUI capability. You can do a bulk Historical Search using a CSV file as input, restricting results for an ISIN to a specific exchange and/or currency, using this CSV format:

If you want several exchanges you must create one entry per exchange in the input CSV.

The resulting RICs can be added to an instrument list on the server.

There is no direct equivalent to the bulk instrument and exchange/currency search in the REST API, but it does deliver equivalent functionality to directly retrieve the set of current RICs from an ISIN combined with an exchange and/or currency, using the EquitySearch or FuturesAndOptionsSearch calls.

API use cases and calls summary

In a nutshell, below is the list of appropriate API calls for each use case.

Use case API call Comment
Find primary exchange for an ISIN InstrumentListValidateWithOptions Delivers for each input ISIN the primary exchange.
Find current primary RIC for an ISIN TermsAndConditionsExtractionRequest Delivers for each input ISIN the primary RIC. You can also retrieve the currency and exchange code.
Find current RIC(s) for 1 or more exchanges for an ISIN

TermsAndConditionsExtractionRequest

Search

Delivers for each input ISIN and exchange the corresponding RIC; you can also retrieve the currency.

The family of non historical Search requests delivers for an input ISIN all RICs and corresponding exchanges; select from results the RICs for the exchanges of interest.

Find historical RIC(s) for 1 or more exchanges for an ISIN

HistoricalReference, ReferenceHistory

 

HistoricalSearch

 

Delivers for each input ISIN all RICs and corresponding exchanges; from the results you can select those for exchanges of interest. In some cases you must add a ReferenceHistory call to identify the historical exchange values for the returned RICs.

HistoricalSearch can also be used, as described in the 2nd use case of the Tick History REST API use cases reference document, available in the documentation tab under the examples category, but HistoricalReference is more straightforward.

Find historical primary RIC for an ISIN   Combine above use cases, i.e. find historical RICs for an ISIN, then select the one on the primary exchange.
Directly run a data extraction request using an ISIN  

2 outcomes are possible for a TRTH data extraction using ISINs, depending on data type:

  1. Time and Sales, Market Depth and Intraday Summary return data for all RICs. This is rarely useful, you might prefer mapping your ISINs to RICs before requesting data.
  2. Elektron Timeseries, Terms and Conditions and Corporate Actions deliver data for the RIC corresponding to the input ISIN and exchange. If no exchange is specified, the result defaults to the primary RIC.

The details are covered in the next section.

Use cases and calls details

Let us look at the relevant API calls in detail, to get a better understanding of their capabilities.

Finding the primary exchange for an ISIN

A call to InstrumentListValidateWithOptions delivers for each input ISIN the primary exchange.

A single call suffices for multiple ISINs.

Here are the details of the API call:

Method: POST

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Extractions/InstrumentListValidateWithOptions

Body:

{
  "InputsForValidation": [
    { "Identifier": "US4592001014", "IdentifierType": "Isin" },
    { "Identifier": "GB00B29MWZ99", "IdentifierType": "Isin" },
    { "Identifier": "DE000C0JK7R7", "IdentifierType": "Isin" },
    { "Identifier": "DE0001135317", "IdentifierType": "Isin" }
  ],
  "Options": {
    "AllowDuplicateInstruments": false,
    "AllowHistoricalInstruments": true,
    "AllowInactiveInstruments": true,
    "AllowOpenAccessInstruments": false,
    "AllowUnsupportedInstruments": false,
    "ExcludeFinrAsPricingSourceForBonds": false,
    "UseConsolidatedQuoteSourceForCanada": false,
    "UseConsolidatedQuoteSourceForUsa": false,
    "UseDebtOverEquity": false,
    "UseExchangeCodeInsteadOfLipper": false,
    "UseUsQuoteInsteadOfCanadian": false
  }
}

Response data:

{
    "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#ThomsonReuters.Dss.Api.Extractions.SubjectLists.InstrumentsValidateIdentifiersResult",
    "ValidatedInstruments": [
        {
            "Identifier": "US4592001014",
            "IdentifierType": "Isin",
            "Source": "NYS",
            "Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAwM2RjMDA0YTAyNGZkOHxOWVN8RVFRVXxFUVRZfE9EU0h8RXx8SUJNLk58MDA3Nw",
            "Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "InstrumentType": "EquityQuote",
            "Status": "Valid"
        },
        {
            "Identifier": "GB00B29MWZ99",
            "IdentifierType": "Isin",
            "Source": "LSE",
            "Key": "VjF8MHgwMDAzZGQwMDE0NzUyYzkzfDB4MDAwM2RjMDA0NzkxZGRkNHxMU0V8RVFRVXxFUVRZfE9EU0h8RXx8VFJJTC5MXkkwOXwwNjkx",
            "Description": "THOMSON REUTERS PLC ORD",
            "InstrumentType": "EquityQuote",
            "Status": "Valid"
        },
        {
            "Identifier": "DE000C0JK7R7",
            "IdentifierType": "Isin",
            "Source": "",
            "Key": "VjF8MHgzMDAwMDAwMDAwMDAwMDAwfDB4MzAwMDAwMDAwMDAwMDAwMHx8fHx8fHx8",
            "Description": "Historical Instrument",
            "InstrumentType": "MortAggregate",
            "Status": "Valid"
        },
        {
            "Identifier": "DE0001135317",
            "IdentifierType": "Isin",
            "Source": "CPL",
            "Key": "VjF8MHgwMDAzZTcwMDAzZTEzYTNjfDB4MDAwNDA1MDAzMDJmOTE4ZnxDUEx8R0NCRHxHT1ZUfEdCVU5EfEd8RXx8",
            "Description": "DEGV   3.750 01/04/17 MATd",
            "InstrumentType": "GovCorpBond",
            "Status": "Valid"
        }
    ],
    "ValidationResult": {
        "ValidInstrumentCount": 4,

[…]

The response contains an object ValidatedInstruments, array that contains several objects (one for each input ISIN) containing the fields we are interested in: Identifier and Source.

Results: parsing the response allows us to build a list of ISINs and corresponding primary exchange codes:

  • US4592001014 – NYS
  • GB00B29MWZ99 – LSE
  • DE000C0JK7R7 – EUX
  • DE0001135317 – CPL

Notes:

  • The request body contains a number of options. As we set "AllowInactiveInstruments": true and "AllowHistoricalInstruments": true the recently matured bond and the delisted instruments were delivered. If we had set these parameters to false no results would have been returned for the matured bond and the 2 expired instruments.
  • In most common TRTH use cases you will be setting both these values to true.

Finding the current primary RIC for an ISIN

If you only need the current value of the primary RIC, or if your instrument is a Fixed Income instrument, you can use a TermsAndConditionsExtractionRequest, which delivers for each input ISIN the primary RIC (except if you specified the source, see next section). It is also possible to retrieve the currency and exchange code.

A single call suffices for multiple ISINs.

Method: POST

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Extractions/Extract

Body:

{
  "ExtractionRequest": {
    "@odata.type": "#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.TermsAndConditionsExtractionRequest",
    "ContentFieldNames": [ 
      "RIC", "ISIN", "Currency Code", "Exchange Code", "Exchange Code List"
    ],
    "IdentifierList": {
      "@odata.type": "#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.InstrumentIdentifierList",
      "InstrumentIdentifiers": [
        { "Identifier": "US4592001014", "IdentifierType": "Isin" },
        { "Identifier": "GB00B29MWZ99", "IdentifierType": "Isin" },
        { "Identifier": "DE000C0JK7R7", "IdentifierType": "Isin" },
        { "Identifier": "DE0001135317", "IdentifierType": "Isin" }
      ],
      "ValidationOptions": { "AllowHistoricalInstruments": true },
      "UseUserPreferencesForValidationOptions": false
    }
  }
}

Response:

Depending on the request size the response will either contain the data, or (if it takes more than 30 seconds) the response will be empty, and the header will contain a location URL. A subsequent GET request to the location URL will deliver the data when it is ready.

Response data:

{
    "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#Collection(ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.ExtractionRow)",
    "value": [
        {
            "IdentifierType": "Isin",
            "Identifier": "US4592001014",
            "RIC": "IBM.N",
            "ISIN": "US4592001014",
            "Currency Code": "USD",
            "Exchange Code": "NYS",
            "Exchange Code List": "ADC,AEX,BAT,BCO,BDS,BEC,BER,BOS,BRN,BTE,BTY,CHI,CIN,DEA,DEU,DEX,DUS,ETX,FRA,GER,HAM,HAN,IEX,LMA,LSE,MEX,MID,MIL,MUN,NBN,NYQ,NYS,PAR,PPB,PSE,SGO,STO,STU,SWX,TDG,THM,TRQ,VIE,XBO,XDS,XPH"
        },
        {
            "IdentifierType": "Isin",
            "Identifier": "GB00B29MWZ99",
            "RIC": "TRIL.L^I09",
            "ISIN": "GB00B29MWZ99",
            "Currency Code": "GBp",
            "Exchange Code": "LSE",
            "Exchange Code List": null
        },
        {
            "IdentifierType": "Isin",
            "Identifier": "DE000C0JK7R7",
            "RIC": null,
            "ISIN": null,
            "Currency Code": null,
            "Exchange Code": null,
            "Exchange Code List": null
        },
        {
            "IdentifierType": "Isin",
            "Identifier": "DE0001135317",
            "RIC": null,
            "ISIN": "DE0001135317",
            "Currency Code": "EUR",
            "Exchange Code": "CPL",
            "Exchange Code List": null
        }
    ]
}

The response contains an object value, array that contains several objects (one for each input ISIN) containing the field we are interested in: RIC. In this example we also included the Currency Code and Exchange Code as control elements.

Results: parsing the response allows us to build a list of ISINs and corresponding primary RIC, primary exchange and currency:

  • US4592001014 – IBM.N – NYS – USD
  • GB00B29MWZ99 – TRIL.L^I09 – LSE – GBp
  • DE000C0JK7R7 – null – null – null
  • DE0001135317 – null – CPL – EUR

Notes on the expired instruments:

  • The syntax of TRIL.L^I09 shows it is a delisted instrument.
  • No primary RIC is delivered for the matured bond, because it is no longer quoted.
  • No data is delivered for the future derivative, because it is no longer quoted.

For more information on the Terms and Conditions extraction, see the DSS REST API Tutorial 7: On Demand T&C extraction (note that even though that tutorial is under the DSS REST API, it also applies for the TRTH REST API).

Finding the current RIC(s) for one or more exchanges for an ISIN

The TermsAndConditionsExtractionRequest we saw in the previous section defaults to the primary RIC. But you can add to each input ISIN a specific exchange; the result will then contain the corresponding RIC.

To get results for several exchanges, you need one entry per source.

For instance, if you want to convert the ISIN US4592001014 to get the RICs on the PSE and SWX exchanges, as well as the primary RIC, you would set the following in the InstrumentIdentifiers:

        { "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "PSE" },
        { "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "SWX" },
        { "Identifier": "US4592001014", "IdentifierType": "Isin" },

Results: this returns the following RICs: IBM.P, IBM.S and IBM.N.

The above scenario assumes you know exactly what exchanges you want. If you do not, you might want to use a Search.

The family of Search requests delivers for an input ISIN all RICs and corresponding exchanges, from the results you can select those for exchanges of interest.

These requests deliver current instruments. No RICs are delivered if the instrument is no longer quoted.

One needs to run one call per ISIN.

The various search requests have different filtering capabilities, for example:

  • InstrumentSearch is the generic search; it allows filtering by instrument type.
  • EquitySearch allows filtering by 1 currency and/or several exchanges.
  • FuturesAndOptionsSearch allows filtering by a combination of 1 currency, several exchanges, expiration date and/or strike price.
  • GovCorpSearch allows filtering by a combination of asset statuses (where matured is MAT), several currencies, dates and more.
  • Etc.

The set of fields that are returned in the response is not configurable. For each result it is recommended to check the value of field IdentifierType, because in cases where a RIC is not available a different identifier type might be returned, as illustrated by our last search example below (the GovCorpSearch).

Let us see these calls in more detail.

Basic instrument search

InstrumentSearch allows filtering by InstrumentTypeGroup.

Method: POST

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Search/InstrumentSearch

Body:

{
  "SearchRequest": {
    "InstrumentTypeGroups": [
      "CollatetizedMortgageObligations", "Commodities", "Equities", "Funds",
      "FuturesAndOptions", "GovCorp", "Money", "MortgageBackedSecurities",
      "Municipals"
    ],
    "IdentifierType": "Isin",
    "Identifier": "US4592001014",
    "PreferredIdentifierType": "Ric"
  }
}

Response data:

{
    "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#Collection(ThomsonReuters.Dss.Api.Content.ValidatedInstrument)",
    "value": [
        {
            "Identifier": "IBM.LM",
            "IdentifierType": "Ric",
            "Source": "LMA",
            "Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAwM2RjMDAzZGNiNDE2OHxMTUF8RVFRVXxFUVRZfE9EU0h8RXx8SUJNLkxNfDAzOTM",
            "Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "InstrumentType": "EquityQuote",
            "Status": "Valid"
        },

[…]

        {
            "Identifier": "IBM.N",
            "IdentifierType": "Ric",
            "Source": "NYS",
            "Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAwM2RjMDA0YTAyNGZkOHxOWVN8RVFRVXxFUVRZfE9EU0h8RXx8SUJNLk58MDA3Nw",
            "Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "InstrumentType": "EquityQuote",
            "Status": "Valid"
        },

[…]

        {
            "Identifier": "IBM.BT1",
            "IdentifierType": "Ric",
            "Source": "BT1",
            "Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAxMDBiMDAxNWNhNDAzMXxCVDF8RVFRVXxFUVRZfE9EU0h8RXx8SUJNLkJUMXwzNzkz",
            "Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "InstrumentType": "EquityQuote",
            "Status": "Valid"
        }
    ]
}

The response contains an object value, array that contains one or more objects (one for each RIC that maps to the input ISIN) containing the fields we are interested in: Identifier and Source (i.e. the venue / exchange).

Results: parsing the response allows us to build a list of all the RICs and corresponding source (exchange), but only for instruments that are still quoted.:

  • US4592001014 – more than 50 results.

    Note: the primary RIC cannot be distinguished from the others.
  • GB00B29MWZ99 – no results
  • DE000C0JK7R7 – no results
  • DE0001135317 – no results

There are no results for the delisted instruments and the matured bond, because they are no longer quoted.

For more information on instrument search refer to REST API Tutorial 16: Search by Instrument.

Equity search

EquitySearch allows filtering by 1 currency and/or several exchanges.

Method: POST

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Search/EquitySearch

Body:

{
  "SearchRequest": {
    "AssetStatus": "Active",
    "AssetCategoryCodes": null,
    "SubTypeCodes": null,
    "CurrencyCodes": [ "USD" ],
    "CompanyName": null,
    "Description": null,
    "DomicileCodes": null,
    "ExchangeCodes": [ "NAS", "NYS", "GSM", "NSM", "SWX" ],
    "FairValueIndicator": null,
    "FileCodes": null,
    "GicsCodes": null,
    "OrgId": null,
    "Ticker": null,
    "Identifier": "US4592001014",
    "IdentifierType": "Isin",
    "PreferredIdentifierType": "Ric"
  }
}

Note: this example illustrates how additional filtering can be done on one single currency code (multiple codes are not supported) and one or more exchange codes.

Response data:

{
    "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#Collection(ThomsonReuters.Dss.Api.Content.ValidatedInstrument)",
    "value": [
        {
            "Identifier": "IBM.N",
            "IdentifierType": "Ric",
            "Source": "NYS",
            "Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAwM2RjMDA0YTAyNGZkOHxOWVN8RVFRVXxFUVRZfHxFfHxJQk0uTnwwMDc3",
            "Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "InstrumentType": "EquityQuote",
            "Status": "Valid"
        },
        {
            "Identifier": "IBMUSD.S",
            "IdentifierType": "Ric",
            "Source": "SWX",
            "Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAxMDBiMDAxMjkwM2NiNXxTV1h8RVFRVXxFUVRZfHxFfHxJQk1VU0QuU3wwNDc3",
            "Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "InstrumentType": "EquityQuote",
            "Status": "Valid"
        }
    ]
}

The response contains an object value, array that contains one or more objects (one for each RIC that maps to the input ISIN) containing the fields we are interested in: Identifier and Source (i.e. the venue / exchange).

Results: parsing the response allows us to build a list of all the equity RICs (with corresponding exchange) for the selected exchanges and currency, but only for instruments that are still quoted:

  • US4592001014 – IBM.N (NYS) and IBMUSD.S (SWX)
  • GB00B29MWZ99 – no results (for a search on LSE), no longer quoted.

There is no point using EquitySearch for DE000C0JK7R7 and DE0001135317 as they are not equities, no results will be returned.

For more information on equity search refer to REST API Tutorial 17: Search for an Equity.

Futures and Options search

FuturesAndOptionsSearch allows filtering by a combination of 1 currency, several exchanges, expiration date and/or strike price.

Method: POST

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Search/FuturesAndOptionsSearch

Body:

{
  "SearchRequest": {
    "FileCodes": null,
    "CurrencyCodes": [ "EUR" ],
    "ExchangeCodes": [ "EUX", "DTB" ],
    "StrikePrice": null,
    "ExpirationDate": {
      "@odata.type": "#ThomsonReuters.Dss.Api.Search.DateValueComparison",
      "ComparisonOperator": "GreaterThanEquals",
      "Value": "2016-12-31T00:00:00.000Z"
    },
    "IdentifierType": "Isin",
    "Identifier": "DE000C0JK7R7",
    "PreferredIdentifierType": "Ric",
    "UnderlyingRic": null
  }
}

Note: this example illustrates how additional filtering can be done on one single currency code (multiple codes are not supported), on one or more exchange codes, and on the expiration date. We did not add a filter on strike price, it would not apply to this ISIN.

Response data:

{
    "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#Collection(ThomsonReuters.Dss.Api.Content.ValidatedInstrument)",
    "value": []
}

The response is empty because the instrument is no longer quoted. If it was quoted then the response would contain an object value, array that would contain one or more objects (one for each RIC that maps to the input ISIN) containing the fields we are interested in: Identifier and Source (i.e. the venue / exchange).

Results: parsing the response allows us to build a list of all the future and option RICs (with corresponding exchange) for the selected exchanges, currency and expiration date, but only for instruments that are still quoted.

There is no point using FutureAndOptionSearch for US4592001014, GB00B29MWZ99 and DE0001135317 as they are not futures or options, no results will be returned.

For more information on future and option search refer to REST API Tutorial 18: Search for a Future or Option.

Government Corporates search

GovCorpSearch allows filtering by a combination of asset statuses (where MAT stands for matured), several currencies, dates and more.

Method: POST

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Search/GovCorpSearch

Body:

{
  "SearchRequest": {
    "AssetStatuses": ["CLD", "CAN", "DFS", "RDM", "EXC", "MAT", "FNG", "DEF", "ISS", "LIQ", "NAC", "PRE", "PUT", "RPN", "REF", "RMK", "RBM", "FDD", "REP", "RES", "TEN", "TBC", "TBE", "TBI", "TBP", "TBR", "TBB", "WHN"],
    "Coupon": null,
    "CurrencyCodes": [ "EUR", "USD" ],
    "Group": { "Agency": true, "Government": true, "Corporate": true, "Supra": true },
    "MoodyRatingsCodes": null,
    "StandardPoorsRatingsCodes": null,
    "Callable": false,
    "Convertable": false,
    "Extendable": false,
    "Putable": false,
    "Sinkable": false,
    "IssueDate": null,
    "MaturityDate": null,
    "NextPayDate": null,
    "Identifier": "DE0001135317",
    "IdentifierType": "Isin",
    "PreferredIdentifierType": "Ric"
  }
}

Note: this example illustrates some of the filtering capabilities.

Response data:

There are 120 results:

{
    "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#Collection(ThomsonReuters.Dss.Api.Content.ValidatedInstrument)",
    "value": [
        {
            "Identifier": "DE0001135317",
            "IdentifierType": "Isin",
            "Source": "EJV",
            "Key": "VjF8MHgwMDAzZTcwMDAzZTEzYTNjfDB4MDAwNDA1MDAzMDJmNzE2ZnxFSlZ8R0NCRHx8fEd8RXx8R09SUA",
            "Description": "DEGV   3.750 01/04/17 MATd",
            "InstrumentType": "GovCorpBond",
            "Status": "Valid"
        },
        {
            "Identifier": "DE0001135317",
            "IdentifierType": "Isin",
            "Source": "AAF",
            "Key": "VjF8MHgwMDAzZTcwMDAzZTEzYTNjfDB4MDAwNDA1MDAzMDJmNzI2Y3xBQUZ8R0NCRHx8fEd8RXx8",
            "Description": "DEGV   3.750 01/04/17 MATd",
            "InstrumentType": "GovCorpBond",
            "Status": "Valid"
        },

[…]

        {
            "Identifier": "DE0001135317=VTMR",
            "IdentifierType": "Ric",
            "Source": "ZNR",
            "Key": "VjF8MHgwMDAzZTcwMDAzZTEzYTNjfDB4MDAxMDJjZDhkZWI1MGI4NHxaTlJ8R0NCRHx8fEd8RXxERTAwMDExMzUzMTc9VlRNUnw",
            "Description": "DEGV   3.750 01/04/17 MATd",
            "InstrumentType": "GovCorpBond",
            "Status": "Valid"
        }
    ]
}

The response contains an object value, array that contains one or more objects (one for each RIC that maps to the input ISIN) containing the fields we are interested in: Identifier and Source (i.e. the venue / exchange).

Results: RICs are not always available for this particular instrument, so the response contains a set of ISINs (always the same, with one record per source) and a set of RICs (in this case a mix of contributor and exchange RICs). This is why we recommend checking the value of field IdentifierType, to verify if the returned identifier is a RIC, or if a different identifier type was returned because no RIC was available.

There is no point using GovCorpSearch for US4592001014, GB00B29MWZ99 and DE000C0JK7R7 as they are not bonds, no results will be returned.

Finding the historical RIC(s) for one or more exchanges for an ISIN

The HistoricalReference extraction request delivers for each input ISIN all RICs and corresponding exchanges, from the results you can select those for exchanges of interest.

As this is a historical extraction you must specify a date/time range. The longer the range, the more results will be returned. Note that the HistoricalReference extraction returns a record for every single reference data change in the date range; for a wide date range you might receive several results containing the same ISIN and RIC identifiers, because other reference data changed during that period. If you chose only a few output data fields it will look like there are duplicates, even though it is not the case.

We therefore recommend you select a single date for the request, the date at which you want the RICs corresponding to the input ISIN. This limits the results. Bear in mind that results can change depending on the date range; a typical case would be a request for a RIC before or after it is delisted. This is illustrated in the following examples.

A single call can handle multiple ISINs, but in the examples below we handle ISINs separately because we use different date ranges.

Note: Fixed Income instruments are not supported by this call; for those you can search for the current RIC(s) using a TermsAndConditionsExtractionRequest, as described earlier in this article.

Here are the details of the API call:

Method: POST

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Extractions/Extract

Body:

{
    "ExtractionRequest": {
        "@odata.type": "#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.HistoricalReferenceExtractionRequest",
        "ContentFieldNames": [
           "RIC", "ISIN", "Exchange Code", "Currency Code", "Change Date"
        ],
        "IdentifierList": {
            "@odata.type": "#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.InstrumentIdentifierList",
            "InstrumentIdentifiers": [
                { "Identifier": "US4592001014", "IdentifierType": "Isin" }
            ],
            "ValidationOptions": {"AllowHistoricalInstruments": true},
            "UseUserPreferencesForValidationOptions": false
        },
        "Condition": {
        	"StartDate": "2017-05-31T00:00:00.000Z",
            "EndDate": "2017-05-31T00:00:00.000Z"
        }
    }
}

Note we set the same value for StartDate and EndDate, to request data for a point in time.

Response:

Depending on the request size the response will either contain the data, or (if it takes more than 30 seconds) the response will be empty, and the header will contain a location URL. A subsequent GET request to the location URL will deliver the data. For details see REST API Tutorial 3: On Demand data extraction workflow.

Response data:

{
    "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#Collection(ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.ExtractionRow)",
    "value": [
        {
            "IdentifierType": "Isin",
            "Identifier": "US4592001014",
            "RIC": "1AIBM.PIPB",
            "ISIN": "US4592001014",
            "Exchange Code": "PPB",
            "Currency Code": "MXN",
            "Change Date": "2017-05-31"
        },

[…]

        {
            "IdentifierType": "Isin",
            "Identifier": "US4592001014",
            "RIC": "IBM.N",
            "ISIN": "US4592001014",
            "Exchange Code": "NYS",
            "Currency Code": "USD",
            "Change Date": "2017-05-31"
        },

[…]

        {
            "IdentifierType": "Isin",
            "Identifier": "US4592001014",
            "RIC": "IBMz.CHI",
            "ISIN": "US4592001014",
            "Exchange Code": "CHI",
            "Currency Code": "CHF",
            "Change Date": "2017-05-31"
        }
    ]
}

Results: with the data we also receive the corresponding primary RIC, primary exchange and currency:

  • US4592001014 – 2017-05-31 – we receive more than 50 results, including a few delisted RICs.
  • GB00B29MWZ99 – 2009-09-01 (before delisting) – we receive more than 20 results, including TRIL.L (on LSE, in GBp).
  • GB00B29MWZ99 – 2009-09-11 (just after delisting) we receive only 1 result: TRIL.L^I09 (on LSE, in GBp). The syntax indicates that the RIC was delisted.
  • DE000C0JK7R7 – 2017-05-31 – delivers 4 results (all on EUX, in EUR): STXXcv1, STXXcvoi1, STXXU7, and STXXU7^0. To interpret these requires some knowledge of RIC rules for futures. The first two are continuation RICs (as indicated by the lower case c; if you have Eikon, see page RULES6 for more information). STXXU7is the main RIC. The last one is the delisted RIC for the previous decade (2007; if you have Eikon, see page RULES9 for more information).
  • DE0001135317 – 2017-03-31 (before expiry) – delivers 7 results, but the exchange and currency codes have null values (this is because Fixed Income is not yet supported): DE0001135317=EX, DE113531=BE, DE113531=D, DE113531=H, DE113531=HA, DE113531=MU, DE113531=LUSG. The RIC syntax shows that the first 6 are quoted on exchanges, identified by the letters after the “=” sign (EUX and 6 German exchanges: BER, DUS, HAM, HAN, MUN), and the last one is from a contributor (Lang & Schwarz).

Finding the historical exchange and currency for a RIC

The last instrument (DE0001135317) shows there are particular cases where the HistoricalReference extraction request delivers the RICs, but not the related exchanges and currency codes. We guessed them through our knowledge of RIC syntaxes, but how can we automate the process ?

This is where a ReferenceHistory search can help. Here are the details of the API call, which can handle a whole set of RICs in one go:

Method: POST

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Search/ReferenceHistory

Body:

{
  "Request": {
    "Rics": [
      "DE0001135317=EX","DE113531=BE","DE113531=D","DE113531=H",
      "DE113531=HA","DE113531=MU","DE0001135317=LUSG"
    ],
    "Range": {
      "Start": "2017-03-31T00:00:00.000Z",
      "End": "2017-03-31T00:00:00.000Z"
    }
  }
}

Response data:

{
    "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#Collection(ThomsonReuters.Dss.Api.Search.ReferenceHistoryResult)",
    "value": [
        {
            "Ric": "DE0001135317=EX",
            "HistoryEvents": [

[…]

                {
                    "Field": "Currency",
                    "Value": "978",
                    "Timestamp": "2017-03-31T00:00:00.000Z"
                },

[…]

                {
                    "Field": "Exchange",
                    "Value": "418",
                    "Timestamp": "2017-03-31T00:00:00.000Z"
                }

[…]

For each input RIC we receive a set of records defining fields, among which the Currency and Exchange. In this case all RICs have value 978 for the currency, but different values for the exchange. To decode the exchange numerical values we use another API call:

Method: GET

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Search/GetHistoricalExchanges

Response data:

{
    "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#Collection(ThomsonReuters.Dss.Api.Search.HistoricalLookupEntry)",
    "value": [
        {
            "Code": "0",
            "Name": "[   ] undefined"
        },

[…]

        {
            "Code": "418",
            "Name": "[EUX] EUREX"
        },

[…]

This allows us to convert the numbers to exchanges; we see 418 corresponds to EUX.

To decode the currency numerical values there is a similar API call:

Method: GET

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Search/GetHistoricalCurrencies

Results: using the results of this set of calls we can build our list of RICs for ISIN DE0001135317, with the corresponding exchanges and currency:

  • DE0001135317=EX – EUX – EUR
  • DE113531=BE – BER – EUR
  • DE113531=D – DUS – EUR
  • DE113531=H – HAM – EUR
  • DE113531=HA – HAN – EUR
  • DE113531=MU – MUN – EUR
  • DE113531=LUSG – RCT (Thomson Reuters Contributor) – EUR

Finding the historical primary RIC for an ISIN

In detail, this requires 3 steps:

  1. Finding the primary exchange for the ISIN.
  2. Finding all the RICs for all exchanges for the ISIN.
  3. Using the result of step 1 to select the corresponding result from step 2.

Steps 1 and 2 were explained in the previous use cases in this article, step 3 is obvious.

Let us go back to our 4 example ISINs. Step 1 delivers the following:

  • US4592001014 – NYS
  • GB00B29MWZ99 – LSE
  • DE000C0JK7R7 – EUX
  • DE0001135317 – CPL

Programmatically going through the results of step 2 to find the exchange code delivered by step 1 filters down the results to the following:

  • US4592001014 –IBM.N
  • GB00B29MWZ99 –TRIL.L
  • DE000C0JK7R7 –STXXU7 (and continuation RICs STXXcv1, STXXcvoi1)
  • DE0001135317 – no results

Note: as we saw, historical reference data does not yet cover Fixed Income instruments. For those you can find the current primary RIC for an ISIN, as described in the next section.

Directly running a data extraction request using an ISIN

It is technically possible to run a TRTH data extraction using ISINs directly. If you do so, there are 2 different outcomes, depending on the type of data you request:

  1. Time and Sales, Market Depth and Intraday Summary return data for all RICs. This amount of data is rarely required. If you do not want data for all RICs, you are better off mapping your ISINs to RICs before requesting data, using the methods described above.

To receive the RIC as first output field, set condition "DisplaySourceRIC": true.

Time and Sales field "Trade - Trade Price Currency" can deliver the currency.

  1. Elektron Timeseries, Terms and Conditions and Corporate Actions deliver data for the RIC corresponding to the input ISIN and exchange. If no exchange is specified, the result defaults to the primary RIC. If you want results for several exchanges, you need one entry per exchange.

    To see the details of the ISIN to RIC mapping you can include the following fields in the request: RIC, Currency Code and Exchange Code.

We do not recommend adding static data (like exchange and currency) to the output field list, because this data will be delivered for every single output record, resulting in slower processing due to useless duplication and information treatment.

As an example, let us look at an Elektron Timeseries (i.e. End of Day pricing) request.

Elektron Timeseries request

An ElektronTimeseriesExtractionRequest delivers data for the RIC that corresponds to the input ISIN and source (exchange). If you do not mention the exchange, the result will contain data for the primary RIC.

If you want results for several exchanges, you need one entry per source.

For instance, if you want to retrieve data for ISIN US4592001014 on the PSE and SWX exchanges, as well as the primary exchange, you could set the following in the InstrumentIdentifiers:

        { "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "PSE" },
        { "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "SWX" },
        { "Identifier": "US4592001014", "IdentifierType": "Isin" },

Results: this will return data for the following RICs: IBM.P, IBM.S and IBM.N.

You can also retrieve the RIC, currency and exchange code, asset and trading status, expiration date, etc.

The following query specifies the exchange for the first ISIN, and defaults to the primary for the others:

Method: POST

Endpoint: https://hosted.datascopeapi.reuters.com/RestApi/v1/Extractions/ExtractRaw

Body:

{
  "ExtractionRequest": {
    "@odata.type": "#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.ElektronTimeseriesExtractionRequest",
    "ContentFieldNames": [
      "Instrument ID", "RIC", "Currency Code", "Exchange Code",
      "Asset Status", "Trading Status", "Expiration Date",
      "Open", "High", "Low", "Last", "Volume", "Trade Date"
    ],
    "IdentifierList": {
      "@odata.type": "#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.InstrumentIdentifierList",
      "InstrumentIdentifiers": [
        { "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "PSE" },
        { "Identifier": "US4592001014", "IdentifierType": "Isin" },
        { "Identifier": "GB00B29MWZ99", "IdentifierType": "Isin" },
        { "Identifier": "DE000C0JK7R7", "IdentifierType": "Isin" },
        { "Identifier": "DE0001135317", "IdentifierType": "Isin" }
      ]
    },
    "Condition": {
      "StartDate": "1996-01-01T00:00:00.000-00:00",
      "EndDate": "2017-07-01T00:00:00.000-00:00"
    }
  }
}

Response:

Depending on the request size the data will either be returned directly, or (if it takes more than 30 seconds) you will have to wait for the extraction to complete before retrieving the data. For more details see REST API Tutorial 3: On Demand data extraction workflow and REST API Tutorial 7: On Demand End of Day extraction.

Response data:

Instrument ID,RIC,Currency Code,Exchange Code,Asset Status,Trading Status,Expiration Date,Open,High,Low,Last,Volume,Trade Date
US4592001014,IBM.P,USD,PSE,ISS,1,,91.25,92,90.625,90.875,19600,1996/01/02

[…]

US4592001014,IBM.P,USD,PSE,ISS,1,,154.82,154.82,153.14,153.89,198773,2017/06/30
US4592001014,IBM.N,USD,NYS,ISS,1,,91.375,92,90.625,90.875,2216800,1996/01/02

[…]

US4592001014,IBM.N,USD,NYS,ISS,1,,154.28,154.5,153.15,153.83,1412034,2017/06/30
GB00B29MWZ99,TRIL.L^I09,GBp,LSE,NAC,0,,,,,587,1402242,1996/01/02

[…]

GB00B29MWZ99,TRIL.L^I09,GBp,LSE,NAC,0,,1858,1892,1815,1892,22871910,2009/09/09
DE0001135317,,EUR,CPL,MAT,0,,,,,,,2006/12/06

[…]

DE0001135317,,EUR,CPL,MAT,0,,99.995,99.995,99.995,,,2017/01/02
DE0001135317,,EUR,CPL,MAT,0,,,,,,,2017/01/03

Results: the response contains the data for IBM on the PSE exchange. For the other ISINs it contains the data for the primary exchange, and, where available, the corresponding primary RIC, primary exchange and currency:

  • US4592001014 / PSE – IBM.P – PSE – USD
  • US4592001014 – IBM.N – NYS – USD
  • GB00B29MWZ99 – TRIL.L^I09 – LSE – GBp
  • DE000C0JK7R7 – no data
  • DE0001135317 – null – CPL - EUR

Notes:

  • Asset Status “ISS” means “Issued”, “NAC” means “Not Active”. “MAT” means “Expired/Matured”.
  • Trading Status is 1 if the instrument is currently traded, 0 otherwise.

Notes on the expired instruments:

  • The syntax of TRIL.L^I09 shows it is a delisted instrument.
  • No data is delivered for the expired future derivative.
  • No primary RIC is delivered for the matured bond, because Fixed Income is not yet supported. The asset status tells us the instrument has matured.

Conclusions

In this article we saw several TRTH REST API calls that allow us to find the primary exchange for an ISIN, the primary RIC for an ISIN, a RIC for a specific ISIN and exchange, and all the RICs for an ISIN. The last capability allows us to select a subset of RICs for specific exchanges (and / or currencies) of interest. We also saw how to request current or historical values, and that in some cases we can even directly retrieve data using ISINs (and exchanges).