DataScope Select - REST API

Close Menu
Expand All Collapse All
Introductory Tutorials Tutorials Introduction Programming without SDK Tutorial REST API Tutorials REST API Tutorials Introduction REST API Tutorial 1: Connecting to the DSS server REST API Tutorial 2: On Demand End of Day Extraction REST API Tutorial 3: On Demand intraday extraction, embargo REST API Tutorial 4: On Demand price history extraction REST API Tutorial 5: On Demand corporate actions extraction REST API Tutorial 6: On Demand ownership data extraction REST API Tutorial 7: On Demand T&C extraction REST API Tutorial 8: On Demand composite extraction REST API Tutorial 9: On Demand extraction: instrument list REST API Tutorial 10: GUI control calls: immediate extract REST API Tutorial 11: Search by Instrument REST API Tutorial 12: Search for an Equity REST API Tutorial 13: Search for a Future or Option REST API Tutorial 14: On Demand price history extraction raw .Net SDK Tutorials .Net SDK Tutorial 1: Connecting to the DSS server .Net SDK Tutorial 2: GUI control calls: List, report, sched .Net SDK Tutorial 3: GUI control calls: Validate, extraction .Net SDK Tutorial 4: GUI control calls: Embargo, note files .Net SDK Tutorial 5: On Demand: EoD extraction .Net SDK Tutorial 6: On Demand: EoD extraction, file I/O .Net SDK Tutorial 7: On Demand: large instrument lists .Net SDK Tutorial 8: On Demand: Terms & Conditions .Net SDK Tutorial 9: On Demand: Composite extraction .Net SDK Tutorial 10: Search by Instrument .Net SDK Tutorial 11: Search for Equity .Net SDK Tutorial 12: Search for Future or Option

REST API Tutorial 6: On Demand ownership data extraction

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

Tutorial purpose

This tutorial explains how to:

  • Retrieve the available field list from the DSS server.
  • Retrieve ownership data from the DSS server, using an on demand request. Ownership data is reference data on securities issued by the company.

 

Table of contents

 

Get available field list for ownership data - HTTP request

If you do not know what field lists are available, you can request a list of those available.

The report template type must be specified in the path. As we want ownership data we set a value of Owners. The preceding tutorials show other possibilities.

See here for more information on report templates and corresponding field lists.

Note: for all requests we need a user token. This was retrieved in Tutorial 1.

URL:               

https://hosted.datascopeapi.reuters.com/RestApi/v1/Extractions/GetValidContentFieldTypes(ReportTemplateType=ThomsonReuters.Dss.Api.Extractions.ReportTemplates.ReportTemplateTypes'Owners')

Method:          GET

Headers:

Prefer: respond-async
Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061

 

Get available field list for ownership data - HTTP response

If the token is valid, this is the response we get:

Status:                        200 OK

Relevant headers:

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

Body:

There are more than 60 values in the response. Here is the beginning of the response:

{
  "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#ContentFieldTypes",
  "value": [
    {
      "Code": "OWN.Asset ID",
      "Name": "Asset ID",
      "Description": "Unique system-assigned identifier for the instrument",
      "FormatType": "Text",
      "FieldGroup": " "
    },
    {
      "Code": "OWN.Asset Status",
      "Name": "Asset Status",
      "Description": "Code representing the status of the instrument",
      "FormatType": "Text",
      "FieldGroup": " "
    },
    {
      "Code": "OWN.Asset Status Description",
      "Name": "Asset Status Description",
      "Description": "Description of Asset Status code",
      "FormatType": "Text",
      "FieldGroup": " "
    },
    {
      "Code": "OWN.Asset SubType",
      "Name": "Asset SubType",
      "Description": "Code representing the asset sub classification within the security type code",
      "FormatType": "Text",
      "FieldGroup": " "
    },
    {
      "Code": "OWN.Asset Subtype Country Code",
      "Name": "Asset Subtype Country Code",
      "Description": "Countries to which the Asset Subtype apply",
      "FormatType": "Text",
      "FieldGroup": " "
    },

This goes on with all the other available fields. Here is the last part:

    {
      "Code": "OWN.Value Changed",
      "Name": "Value Changed",
      "Description": "Dollar value of shares changed",
      "FormatType": "Number",
      "FieldGroup": " "
    },
    {
      "Code": "OWN.Value Held",
      "Name": "Value Held",
      "Description": "Dollar value of shares held",
      "FormatType": "Number",
      "FieldGroup": " "
    },
    {
      "Code": "OWN.Wertpapier",
      "Name": "Wertpapier",
      "Description": "Issue-level code used for identifying instruments in Germany",
      "FormatType": "Text",
      "FieldGroup": " "
    }
  ]
}

The result contains the field code, name, a description, field type (number, text, date) and group.  Use this to choose the field names you want. In the next step we will make a request for data, using some data fields we chose.

 

Get ownership data - HTTP request

This is similar to the previous tutorials, as it is also an On Demand extraction request.

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

  • The type of extraction: as we want ownership data we set a value of OwnershipExtractionRequest. The preceding tutorials show other possibilities.
  • The list of field names: these were determined in the first step of this tutorial.
  • The list of instrument identifiers, each one with its type. Similar to the previous tutorials, below we define one instrument using a CUSIP code and one using a RIC.
  • For this request we do not set any conditions.

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://hosted.datascopeapi.reuters.com/RestApi/v1/Extractions/ExtractWithNotes

Method:          POST

Headers:

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

Body:

{
  "ExtractionRequest": {
    "@odata.type": "#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.OwnershipExtractionRequest",
    "ContentFieldNames": [
      "Asset ID",
      "Asset Status",
      "Asset Status Description",
      "Change Sign",
      "Common Code",
      "Currency Code",
      "Currency Code Description",
      "CUSIP",
      "File Code",
      "Issuer ID",
      "Issuer Name",
      "Issuer OrgID",
      "RCP ID",
      "Issuer Short Name",
      "Legal Entity OrgID",
      "Holdings Previous Report Date",
      "Holdings Report Date",
      "Owner Country",
      "Owner ID",
      "Owner Name",
      "Owner Type",
      "Owner Type Description",
      "Percent of Shares Outstanding",
      "Primary Issue Flag",
      "Security Description",
      "Shares Held",
      "Value Held",
      "Shares Changed",
      "Value Changed"
    ],
    "IdentifierList": {
      "@odata.type": "#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.InstrumentIdentifierList",
      "InstrumentIdentifiers": [
      	{ "Identifier": "438516AC0", "IdentifierType": "Cusip" },
      	{ "Identifier": "IBM.N", "IdentifierType": "Ric" }
      ]
    }
  }
}

 

Get ownership data - HTTP response

Request accepted, no timeout

If the token is valid, and there is no timeout (these requests can take time as they generate very large data sets), the data will be delivered.

This is the response we get:

Status:                        200 OK

Relevant headers:

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

Body:

There are more than 5000 values in the response. Here is the beginning of the response:

{
    "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.ExtractionResult",
    "Contents": [
        {
            "IdentifierType": "Cusip",
            "Identifier": "438516AC0",
            "Asset ID": "0x0000190000004b52",
            "Asset Status": "MAT",
            "Asset Status Description": "Expired/Matured",
            "Change Sign": null,
            "Common Code": "038610325",
            "Currency Code": "USD",
            "Currency Code Description": "U.S. Dollar",
            "CUSIP": "438516AC0",
            "File Code": null,
            "Issuer ID": "0x00001900004f782e",
            "Issuer Name": "HONEYWELL INTERNATIONAL INC",
            "Issuer OrgID": "18181",
            "RCP ID": null,
            "Issuer Short Name": "Honeywell Intl",
            "Legal Entity OrgID": "18181",
            "Holdings Previous Report Date": null,
            "Holdings Report Date": null,
            "Owner Country": null,
            "Owner ID": null,
            "Owner Name": null,
            "Owner Type": null,
            "Owner Type Description": null,
            "Percent of Shares Outstanding": null,
            "Primary Issue Flag": null,
            "Security Description": "HON    9.500 06/01/16 MATd",
            "Shares Held": null,
            "Value Held": null,
            "Shares Changed": null,
            "Value Changed": null
        },
        {
            "IdentifierType": "Ric",
            "Identifier": "IBM.N",
            "Asset ID": "0x0003dd001379d460",
            "Asset Status": "ISS",
            "Asset Status Description": "Issued",
            "Change Sign": "P",
            "Common Code": null,
            "Currency Code": "USD",
            "Currency Code Description": "U.S. Dollar",
            "CUSIP": "459200101",
            "File Code": "77",
            "Issuer ID": "0x000019000050e3aa",
            "Issuer Name": "International Business Machines Corp",
            "Issuer OrgID": "18228",
            "RCP ID": "300018228",
            "Issuer Short Name": null,
            "Legal Entity OrgID": "18228",
            "Holdings Previous Report Date": null,
            "Holdings Report Date": "2019-06-30",
            "Owner Country": "Taiwan, R.O.C.",
            "Owner ID": "23935014",
            "Owner Name": "KGI High Sharpe Global Balanced Fund",
            "Owner Type": "MF",
            "Owner Type Description": "Mutual Fund",
            "Percent of Shares Outstanding": 0,
            "Primary Issue Flag": "Y",
            "Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "Shares Held": 330,
            "Value Held": 45507,
            "Shares Changed": 330,
            "Value Changed": 45507
        },
        {
            "IdentifierType": "Ric",
            "Identifier": "IBM.N",
            "Asset ID": "0x0003dd001379d460",
            "Asset Status": "ISS",
            "Asset Status Description": "Issued",
            "Change Sign": "S",
            "Common Code": null,
            "Currency Code": "USD",
            "Currency Code Description": "U.S. Dollar",
            "CUSIP": "459200101",
            "File Code": "77",
            "Issuer ID": "0x000019000050e3aa",
            "Issuer Name": "International Business Machines Corp",
            "Issuer OrgID": "18228",
            "RCP ID": "300018228",
            "Issuer Short Name": null,
            "Legal Entity OrgID": "18228",
            "Holdings Previous Report Date": "2019-06-30",
            "Holdings Report Date": "2019-08-31",
            "Owner Country": "England",
            "Owner ID": "24055403",
            "Owner Name": "ReAssure HL Pensions Balanced 1 Pen",
            "Owner Type": "PP",
            "Owner Type Description": "Pension Fund Portfolio",
            "Percent of Shares Outstanding": 0,
            "Primary Issue Flag": "Y",
            "Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "Shares Held": 4864,
            "Value Held": 659218,
            "Shares Changed": -182,
            "Value Changed": -24666
        },
        {
            "IdentifierType": "Ric",
            "Identifier": "IBM.N",
            "Asset ID": "0x0003dd001379d460",
            "Asset Status": "ISS",
            "Asset Status Description": "Issued",
            "Change Sign": "S",
            "Common Code": null,
            "Currency Code": "USD",
            "Currency Code Description": "U.S. Dollar",
            "CUSIP": "459200101",
            "File Code": "77",
            "Issuer ID": "0x000019000050e3aa",
            "Issuer Name": "International Business Machines Corp",
            "Issuer OrgID": "18228",
            "RCP ID": "300018228",
            "Issuer Short Name": null,
            "Legal Entity OrgID": "18228",
            "Holdings Previous Report Date": "2018-12-31",
            "Holdings Report Date": "2019-03-31",
            "Owner Country": "United States",
            "Owner ID": "1176400",
            "Owner Name": "Morgan Dempsey Capital Management, LLC",
            "Owner Type": "IA",
            "Owner Type Description": "Investment Advisor",
            "Percent of Shares Outstanding": 0,
            "Primary Issue Flag": "Y",
            "Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "Shares Held": 0,
            "Value Held": 0,
            "Shares Changed": -26619,
            "Value Changed": -3755941
        },
        {
            "IdentifierType": "Ric",
            "Identifier": "IBM.N",
            "Asset ID": "0x0003dd001379d460",
            "Asset Status": "ISS",
            "Asset Status Description": "Issued",
            "Change Sign": "S",
            "Common Code": null,
            "Currency Code": "USD",
            "Currency Code Description": "U.S. Dollar",
            "CUSIP": "459200101",
            "File Code": "77",
            "Issuer ID": "0x000019000050e3aa",
            "Issuer Name": "International Business Machines Corp",
            "Issuer OrgID": "18228",
            "RCP ID": "300018228",
            "Issuer Short Name": null,
            "Legal Entity OrgID": "18228",
            "Holdings Previous Report Date": "2019-06-30",
            "Holdings Report Date": "2019-09-30",
            "Owner Country": "Norway",
            "Owner ID": "2022570",
            "Owner Name": "SPP Generation 60 tal",
            "Owner Type": "MF",
            "Owner Type Description": "Mutual Fund",
            "Percent of Shares Outstanding": 0,
            "Primary Issue Flag": "Y",
            "Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "Shares Held": 40650,
            "Value Held": 5911323,
            "Shares Changed": -2812,
            "Value Changed": -408921
        },

This goes on with all the other available fields. Here is the last part:

        {
            "IdentifierType": "Ric",
            "Identifier": "IBM.N",
            "Asset ID": "0x0003dd001379d460",
            "Asset Status": "ISS",
            "Asset Status Description": "Issued",
            "Change Sign": "S",
            "Common Code": null,
            "Currency Code": "USD",
            "Currency Code Description": "U.S. Dollar",
            "CUSIP": "459200101",
            "File Code": "77",
            "Issuer ID": "0x000019000050e3aa",
            "Issuer Name": "International Business Machines Corp",
            "Issuer OrgID": "18228",
            "RCP ID": "300018228",
            "Issuer Short Name": null,
            "Legal Entity OrgID": "18228",
            "Holdings Previous Report Date": "2019-03-31",
            "Holdings Report Date": "2019-06-30",
            "Owner Country": "Canada",
            "Owner ID": "23808103",
            "Owner Name": "IA Clarington U.S. Dividend Growth Registered Fund",
            "Owner Type": "MF",
            "Owner Type Description": "Mutual Fund",
            "Percent of Shares Outstanding": 0,
            "Primary Issue Flag": "Y",
            "Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "Shares Held": 0,
            "Value Held": 0,
            "Shares Changed": -400,
            "Value Changed": -55160
        },
        {
            "IdentifierType": "Ric",
            "Identifier": "IBM.N",
            "Asset ID": "0x0003dd001379d460",
            "Asset Status": "ISS",
            "Asset Status Description": "Issued",
            "Change Sign": "S",
            "Common Code": null,
            "Currency Code": "USD",
            "Currency Code Description": "U.S. Dollar",
            "CUSIP": "459200101",
            "File Code": "77",
            "Issuer ID": "0x000019000050e3aa",
            "Issuer Name": "International Business Machines Corp",
            "Issuer OrgID": "18228",
            "RCP ID": "300018228",
            "Issuer Short Name": null,
            "Legal Entity OrgID": "18228",
            "Holdings Previous Report Date": "2018-03-31",
            "Holdings Report Date": "2018-06-30",
            "Owner Country": "United States",
            "Owner ID": "23082423",
            "Owner Name": "VNB Wealth Management",
            "Owner Type": "BK",
            "Owner Type Description": "Bank and Trust",
            "Percent of Shares Outstanding": 0,
            "Primary Issue Flag": "Y",
            "Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "Shares Held": 15795,
            "Value Held": 2206562,
            "Shares Changed": -225,
            "Value Changed": -31433
        },
        {
            "IdentifierType": "Ric",
            "Identifier": "IBM.N",
            "Asset ID": "0x0003dd001379d460",
            "Asset Status": "ISS",
            "Asset Status Description": "Issued",
            "Change Sign": "P",
            "Common Code": null,
            "Currency Code": "USD",
            "Currency Code Description": "U.S. Dollar",
            "CUSIP": "459200101",
            "File Code": "77",
            "Issuer ID": "0x000019000050e3aa",
            "Issuer Name": "International Business Machines Corp",
            "Issuer OrgID": "18228",
            "RCP ID": "300018228",
            "Issuer Short Name": null,
            "Legal Entity OrgID": "18228",
            "Holdings Previous Report Date": "2019-06-30",
            "Holdings Report Date": "2019-09-30",
            "Owner Country": "Switzerland",
            "Owner ID": "22046591",
            "Owner Name": "Zürcher Kantonalbank (Asset Management)",
            "Owner Type": "BK",
            "Owner Type Description": "Bank and Trust",
            "Percent of Shares Outstanding": 0.04,
            "Primary Issue Flag": "Y",
            "Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
            "Shares Held": 371719,
            "Value Held": 54055377,
            "Shares Changed": 66996,
            "Value Changed": 9742558
        }
    ],
    "Notes": [
        "Extraction Services Version 13.2.41189 (85522a4c8b22), Built Nov 11 2019 22:27:03\r\nUser has overridden estimates broker entitlements.\r\nProcessing started at 19112019 16:05:28.\r\nUser ID: 33314\r\nExtraction ID: 2000000113034286\r\nSchedule: 0x06df5ecf6d412ba5 (ID = 0x0000000000000000)\r\nInput List (2 items):  (ID = 0x06df5ecf6d412ba5) Created: 19112019 16:05:28 Last Modified: 19112019 16:05:28\r\nReport Template (35 fields): _OnD_0x06df5ecf6d412ba5 (ID = 0x06df5ecf6d812ba5) Created: 19112019 16:05:26 Last Modified: 19112019 16:05:26\r\nSchedule dispatched via message queue (0x06df5ecf6d412ba5)\r\nSchedule Time: 19112019 16:05:26\r\nProcessing completed successfully at 19112019 16:05:33, taking 4.933 Secs.\r\nExtraction finished at 19112019 15:05:33 UTC, with servers: x01q10, QSHC16 (0.6 secs), QSSHA1 (0.0 secs)\r\nUsage Summary for User 33314, Client 11122, Template Type Ownership Owners\r\nBase Usage\r\n        Instrument                          Instrument                   Terms          Price\r\n  Count Type                                Subtype                      Source         Source\r\n------- ----------------------------------- ---------------------------- -------------- ----------------------------------------\r\n      1 Corporate                                                        N/A            N/A\r\n      1 Equities                                                         N/A            N/A\r\n-------\r\n      2 Total instruments charged.\r\n      0 Instruments with no reported data.\r\n=======\r\n      2 Instruments in the input list.\r\nWriting RIC maintenance report.\r\n",
        "Identifier,IdentType,Source,RIC,RecordDate,MaintType,OldValue,NewValue,Factor,FactorType\r\n"
    ]
}

 

Request accepted, but with a timeout

If the token is valid, but there was a timeout, this is the response we get:

Status:                        202 Accepted

Relevant headers:

Location: https://hosted.datascopeapi.reuters.com/RestApi/v1/Extractions/ExtractResult(ExtractionId='0x053c0831a44b5841')

Body:

Response does not contain any data.

You will have to send another HTTP GET request to retrieve the result, using the location URL that was delivered in the HTTP 202 Response header.

 

Get ownership data, subsequent request after a timeout - HTTP request

This is how we resend our request. Note the path, taken from the 202 response header:

URL:               

https://hosted.datascopeapi.reuters.com/RestApi/v1/Extractions/ExtractResult(ExtractionId='0x053c0831a44b5841')

Method:          GET

Headers:

Prefer: respond-async
Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061

If the data is available, you will get the results. Otherwise you will have to try again later. The more data is requested, the longer it can take for it to be available.

Tutorial Group: 
REST API Tutorials