REST API Tutorial 14: Historical Criteria Search

Last update Dec 2023
Environment Any
Language Any HTTP is supported
Compilers None
Prerequisites DSS login, internet access
Source code Below

Tutorial purpose

There are several available historical search calls to retrieve instrument identifiers:

  • Historical Search
  • Historical Criteria Search
  • Historical Chain Resolution

This tutorial covers the second type, explaining how to make historical criteria search requests.

2 use cases are covered:

  • Find all instruments that traded on the New York Stock Exchange on 7 November 2010
  • Find all fixed income instruments that traded during the 12 months preceding November 2016, matured in September 2016, and with a coupon rate greater than or equal to 30%.

 

Table of contents


Historical criteria search for NYSE RICs - HTTP request

Note: for all requests we need to include a user token in the header of our request. This was retrieved in Tutorial 1.

URL: 

    	
            https://selectapi.datascope.refinitiv.com/RestApi/v1/Search/HistoricalCriteriaSearch

Method:          POST

Headers:

    	
            
Prefer: respond-async


Content-Type: application/json


Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061

Body:

The body of the request contains several parts:

  • The search criteria. Here we set only one, the RIC pattern, using a regular expression. The syntax "\\.N$" specifies that the instrument’s RIC must have a suffix of .N, indicating the New York Stock Exchange (the double \\ escapes the "." so that it is interpreted literaly, as by default a "." represents any character).
  • The date range. Here we chose a single date.
    	
            
{


  "Request": {


    "RicPattern": "\\.N$",


    "BondTypeCodes": null,


    "ContributorIds": null,


    "CountryCodes": null,


    "CurrencyCodes": null,


    "ExchangeCodes": null,


    "FutureMonthCodes": null,


    "InstrumentTypeCodes": null,


    "OptionMonthCodes": null,


    "OptionTypeCodes": null,


    "CouponRate": null,


    "StrikePrice": null,


    "ExpiryDate": null,


    "MaturityDate": null,


    "Range": {


      "Start": "2010-11-07T00:00:00.000Z",


      "End": "2010-11-08T00:00:00.000Z"


    }


  }


}

Note: early 2018 the Tick History REST API expanded support for regular expressions (regex) in the RicPattern and DescriptionPattern properties in the Search/HistoricalCriteriaSearch endpoint. These properties now support all POSIX Extended Regular Expression (ERE) syntax, with the following exceptions:

  • The ^ and $ operators can be used only once in an expression
  • Expressions are case insensitive

Here are a few examples of simple regular expressions you could use:

  • string         Contains            Example: "RicPattern": "CARR",
  • ^string       Begins with       Example: "RicPattern": "^CARR",
  • string$       Ends with          Example: "RicPattern": "\\.PA$",

 

 

Historical criteria search for NYSE RICs - HTTP response

Status:                        200 OK

Relevant headers:

    	
            Content-Type: application/json; charset=utf-8

Body:

    	
            
{


  "@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#Collection(DataScope.Select.Api.Search.HistoricalSearchResult)",


  "value": [


    {


      "Identifier": ".AD.N",


      "IdentifierType": "Ric",


      "Source": "",


      "Key": "VjF8MHgzMDAwMDAwMDAwMDAwMDAwfDB4MzAwMDAwMDAwMDAwMDAwMHx8fHx8fHwuQUQuTnw",


      "Description": "Historical Instrument",


      "InstrumentType": "Unknown",


      "Status": "Valid",


      "DomainCode": "6",


      "FirstDate": "1996-01-02T00:00:00.000Z",


      "LastDate": "2019-11-18T00:00:00.000Z",


      "History": []


    },


    {


      "Identifier": ".AP.N",


      "IdentifierType": "Ric",


      "Source": "",


      "Key": "VjF8MHgzMDAwMDAwMDAwMDAwMDAwfDB4MzAwMDAwMDAwMDAwMDAwMHx8fHx8fHwuQVAuTnw",


      "Description": "Historical Instrument",


      "InstrumentType": "Unknown",


      "Status": "Valid",


      "DomainCode": "6",


      "FirstDate": "1996-01-01T00:00:00.000Z",


      "LastDate": "2017-10-06T00:00:00.000Z",


      "History": []


    },


    {


      "Identifier": ".AV.N",


      "IdentifierType": "ChainRIC",


      "Source": "",


      "Key": "VjF8MHgzMDAwMDAwMDAwMDAwMDAwfDB4MzAwMDAwMDAwMDAwMDAwMHx8fHx8fHwuQVYuTnw",


      "Description": "Historical Chain",


      "InstrumentType": "Unknown",


      "Status": "Valid",


      "DomainCode": "6",


      "FirstDate": "1996-01-01T00:00:00.000Z",


      "LastDate": "2020-02-24T00:00:00.000Z",


      "History": []


    },

There are many more results, the above is just the first part.

Note: domain code 6 is for Market Price.

 

 

Historical criteria search for FI - HTTP request

URL: 

    	
            https://selectapi.datascope.refinitiv.com/RestApi/v1/Search/HistoricalCriteriaSearch

Method:          POST

Headers:

    	
            
Prefer: respond-async


Content-Type: application/json


Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061

Body:

The body of the request contains several parts:

  • The search criteria. Here we combine several: the coupon rate defined using a minimum value, and a range for the maturity date.
  • The date range, in this case the 12 months preceding November 2016.
    	
            
{


  "Request": {


    "BondTypeCodes": null,


    "ContributorIds": null,


    "CountryCodes": null,


    "CurrencyCodes": null,


    "ExchangeCodes": null,


    "FutureMonthCodes": null,


    "InstrumentTypeCodes": null,


    "OptionMonthCodes": null,


    "OptionTypeCodes": null,


    "CouponRate": {


      "Min": 30


    },


    "StrikePrice": null,


    "ExpiryDate": null,


    "MaturityDate": {


      "Start": "2016-09-01T00:00:00.000Z",


      "End": "2016-09-30T23:59:59.999Z"


    },


    "Range": {


      "Start": "2015-09-30T00:00:00.000Z",


      "End": "2016-09-30T23:59:59.999Z"


    }


  }


}

 

Historical criteria search for FI - HTTP response

Status:                        200 OK

Relevant headers:

    	
            Content-Type: application/json; charset=utf-8

Body:

    	
            
{


  "@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#Collection(DataScope.Select.Api.Search.HistoricalSearchResult)",


  "value": [


    {


      "Identifier": "984308CM6=RRPS",


      "IdentifierType": "Ric",


      "Source": "",


      "Key": "VjF8MHgzMDAwMDAwMDAwMDAwMDAwfDB4MzAwMDAwMDAwMDAwMDAwMHx8fHx8fHw5ODQzMDhDTTY9UlJQU3w",


      "Description": "Historical Instrument",


      "InstrumentType": "Unknown",


      "Status": "Valid",


      "DomainCode": "6",


      "FirstDate": "2015-11-26T00:00:00.000Z",


      "LastDate": "2016-09-28T00:00:00.000Z",


      "History": []


    },


    {


      "Identifier": "AAHA2YEUAM=MP",


      "IdentifierType": "Ric",


      "Source": "",


      "Key": "VjF8MHgzMDAwMDAwMDAwMDAwMDAwfDB4MzAwMDAwMDAwMDAwMDAwMHx8fHx8fHxBQUhBMllFVUFNPU1QfA",


      "Description": "Historical Instrument",


      "InstrumentType": "Unknown",


      "Status": "Valid",


      "DomainCode": "6",


      "FirstDate": "2007-08-25T00:00:00.000Z",


      "LastDate": "2018-07-12T00:00:00.000Z",


      "History": []


    },


    {


      "Identifier": "AAHR1YGBAL=MP",


      "IdentifierType": "Ric",


      "Source": "",


      "Key": "VjF8MHgzMDAwMDAwMDAwMDAwMDAwfDB4MzAwMDAwMDAwMDAwMDAwMHx8fHx8fHxBQUhSMVlHQkFMPU1QfA",


      "Description": "Historical Instrument",


      "InstrumentType": "Unknown",


      "Status": "Valid",


      "DomainCode": "6",


      "FirstDate": "2014-09-20T00:00:00.000Z",


      "LastDate": "2018-07-12T00:00:00.000Z",


      "History": []


    },

There are many more results, the above is just the first part.

Note: domain code 6 is for Market Price.