REST API Tutorial 8: On Demand raw data extraction

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

Tutorial purpose

Please follow the REST API tutorial 3, which explains the workflow, before going through this one.

This tutorial explains how to:

Request raw data from the server, using an on demand request.
Check the request status.
Retrieve the data.

Request raw data - HTTP request
FID filtering
Request raw data - HTTP response
Check request status - HTTP request
Check request status - HTTP response
Retrieve data - HTTP request
Retrieve data - HTTP response

Request raw data - HTTP request

This is an On Demand extraction request.

URL:

    	
            https://selectapi.datascope.refinitiv.com/RestApi/v1/Extractions/ExtractRaw

Method: POST

Headers:

Note: for all requests we need a user token, set in the header. The token was retrieved in Tutorial 1.

    	
            Prefer: respond-async
Content-Type: application/json
Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061

Body:

The body of the request must mention it is an extraction request. It contains several parts:

The type of extraction: as we want tick data we set a value of TickHistoryRawExtractionRequest. The preceding and following tutorials show other possibilities.
Contrary to the other requests covered in the previous tutorials, there is no list of field names, because this is the raw transaction data from the exchange.
The list of instrument identifiers, each one with its type. Below we define one instrument using a RIC.
The conditions: they include the date range for the request.

    	
            {
  "ExtractionRequest": {
    "@odata.type": "#DataScope.Select.Api.Extractions.ExtractionRequests.TickHistoryRawExtractionRequest",
    "IdentifierList": {
      "@odata.type": "#DataScope.Select.Api.Extractions.ExtractionRequests.InstrumentIdentifierList",
      "InstrumentIdentifiers": [
        { "Identifier": "CARR.PA", "IdentifierType": "Ric" }
      ]
    },
    "Condition": {
      "MessageTimeStampIn": "GmtUtc",
      "ReportDateRangeType": "Range",
      "QueryStartDate": "2016-09-29T12:00:00.000Z",
      "QueryEndDate": "2016-09-29T12:10:00.000Z",
      "ExtractBy": "Ric",
      "SortBy": "SingleByRic",
      "DomainCode": "MarketPrice",
      "DisplaySourceRIC": true
    }
  }
}

FID filtering

You can modify the request above to filter the output to contain only data for a set of particular FID, by adding condition Fids:

    	
                "Condition": {
      "MessageTimeStampIn": "GmtUtc",
      "ReportDateRangeType": "Range",
      "QueryStartDate": "2017-09-29T12:00:00.000Z",
      "QueryEndDate": "2017-09-29T12:30:00.000Z",
      "ExtractBy": "Ric",
      "SortBy": "SingleByRic",
      "DomainCode": "MarketPrice",
      "Fids": "25,31,22,30,5",
      "DisplaySourceRIC": true
    }

The entire list of FIDs with numbers and description can be found in the GUI, in the lower part of the Tick History Raw template creation screen:

Request raw data - HTTP response

The possible responses are described in detail the REST API tutorial 3.

In a nutshell, the most likely outcome is a response with an HTTP status of 202 Accepted, and the header will contain a location URL. The next step is to check the request status by polling the location URL regularly until it returns a 200 OK.

If the request is for a small amount of data, the response could have an HTTP status of 200 OK, and the body will contain a jobId and Notes. If the Notes contain the message: Processing completed successfully, we can proceed further. We skip the step where we check the request status, and go directly to the last step, which is to retrieve the data using the jobId.

Other HTTP status codes can be encountered, follow this link for a full list with detailed explanations. It is strongly recommended that your code handle all possible status codes.

Check request status - HTTP request

Skip this step if the previous step returned an HTTP status of 200 OK.

If the previous step returned an HTTP status of 202 Accepted, this step must be executed, and repeated in a polling loop until it returns an HTTP status of 200 OK.

URL:

This is the location URL, taken from the 202 response header received in the previous step.

    	
            https://selectapi.datascope.refinitiv.com/RestApi/v1/Extractions/ExtractRawResult(ExtractionId='0x05a2779b84db3036')

Method: GET

Headers:

    	
            Prefer: respond-async
Content-Type: application/json
Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061

Check request status - HTTP response

If you receive an HTTP status 202 Accepted response (the same as in the previous step), it means the request has not yet completed. You must wait a bit and check the request status again.

If you receive an HTTP status 200 OK response, the body will contain a jobId and Notes. If the Notes contain the message: Processing completed successfully, we can proceed further. We go to the last step, which is to retrieve the data using the jobId.

Retrieve data - HTTP request

It is mandatory to have received a 200 OK response with a JobID from a previous step before proceeding with this last step.

URL:

Note the jobId, used as parameter in the URL.

    	
            https://selectapi.datascope.refinitiv.com/RestApi/v1/Extractions/RawExtractionResults('0x05a2779b84db3036')/$value

Method: GET

Headers:

    	
            Prefer: respond-async
Content-Type: Accept-Encoding: gzip, deflate
Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061

Retrieve data - HTTP response

We should get a response of this type:

Status: 200 OK

Relevant headers:

    	
            Content-Encoding: gzip
Content-Type: text/plain

Body:

RAW reports are delivered message-per-message as reported by the exchange venues. Here is the beginning of the response content (this one does not use a FID filter, all FIDs are returned):

    	
            #RIC,Domain,Date-Time,GMT Offset,Type,MsgClass/FID number,UpdateType/Action,FID Name,FID Value,FID Enum String,PE Code,Template Number,Key/Msg Sequence Number,Alias Underlying RIC,Number of FIDs
CARR.PA,Market Price,2016-09-29T10:00:00.258628004Z,+2,Raw,UPDATE,QUOTE,,,,8132,,45808,,14
,,,,FID,25,,ASK,23.31,
,,,,FID,6580,,ASK_COND_N,0,
,,,,FID,31,,ASKSIZE,1828,
,,,,FID,4147,,ASK_TIM_MS,36000210,
,,,,FID,346,,ASK_TONE," ",
,,,,FID,3867,,AUC_ASK,,
,,,,FID,3864,,AUC_ASKSIZ,,
,,,,FID,6516,,BOOK_STATE,1,N
,,,,FID,134,,MID_PRICE,23.3075,
,,,,FID,292,,NO_ASKMMKR,6,
,,,,FID,6554,,NO_ASKORD1,6,
,,,,FID,1025,,QUOTIM,10:00:00.000000000,
,,,,FID,3855,,QUOTIM_MS,36000210,
,,,,FID,5,,TIMACT,10:00:00.000000000,
CARR.PA,Market Price,2016-09-29T10:00:00.258628004Z,+2,Raw,UPDATE,QUOTE,,,,8132,,45824,,14
,,,,FID,3866,,AUC_BID,,
,,,,FID,3862,,AUC_BIDSIZ,,
,,,,FID,22,,BID,23.305,
,,,,FID,6579,,BID_COND_N,0,
,,,,FID,30,,BIDSIZE,487,
,,,,FID,4150,,BID_TIM_MS,36000211,
,,,,FID,345,,BID_TONE," ",
,,,,FID,6516,,BOOK_STATE,1,N
,,,,FID,134,,MID_PRICE,23.3075,
,,,,FID,291,,NO_BIDMMKR,2,
,,,,FID,6544,,NO_BIDORD1,2,
,,,,FID,1025,,QUOTIM,10:00:00.000000000,
,,,,FID,3855,,QUOTIM_MS,36000211,
,,,,FID,5,,TIMACT,10:00:00.000000000,
CARR.PA,Market Price,2016-09-29T10:00:00.258628004Z,+2,Raw,UPDATE,QUOTE,,,,8132,,45840,,14