Retrieve Data Using Bloomberg Hypermedia

This example shows how to connect to the Bloomberg^® Hypermedia service from Datafeed Toolbox™ and then create a universe of securities, a field list, and a trigger to schedule a data request. You then create a data request and retrieve the data. For details about Bloomberg Hypermedia API (HAPI), see Bloomberg HAPI Documentation.

Connect to Bloomberg Hypermedia

Access the Hypermedia service after obtaining a data license from Bloomberg. For details on getting a license, see Bloomberg Data License. After receiving the user credentials information, insert the credentials into a string variable and connect to the data server using the MATLAB^® Command Window.

credentialsString = '{"client_id":"89beaeab724bbdf5e186b733c58af2","client_secret":"77050429aee81eb31793fb10fa4301c54911db545de8b2990252ffe2b56b11","name":"BloombergHAIDevelopment","scopes":["eap","beapData","reportingapi"],"expiration_date":1699198358934,"created_date":1651764758934}'

c = bloombergHypermedia(credentialsString)

c = 

  bloombergHypermedia with properties:

    TimeOut: 200.00

MATLAB returns c as the connection to the service with the Bloomberg Hypermedia session object, bloombergHypermedia, and a request timeout period of 200 seconds (default). You can set the timeOut value, a public property, as well as private properties by using input arguments with the bloombergHypermedia function.

Create Universe of Securities

Creating a universe of securities requires two steps. First, using definitions from Bloomberg Hypermedia API, create a payload structure that defines the universe. For this example, the universe holds historical data for US Equity securities.

universePayload.type = "Universe";
universePayload.identifier = "u" + bloombergHypermedia.generateResourcePostfix;
universePayload.title = "Test Universe " + string(datetime);
universePayload.description = "Test historical data universe - ZYX, WVU";
universePayload.contains{1}.type = "Identifier";
universePayload.contains{1}.identifierType = "TICKER";
universePayload.contains{1}.identifierValue = "ZYX US Equity";
universePayload.contains{2}.type = "Identifier";
universePayload.contains{2}.identifierType = "TICKER";
universePayload.contains{2}.identifierValue = "WVU US Equity"

Then create the universe by using the createUniverse function. Replace the "123" argument in this example for createUniverse with your Bloomberg user ID. The function outputs the universe ID and a response message that confirms the creation of the universe.

userCatalog = "123";
[universeID,response] = createUniverse(c,userCatalog,universePayload)

universeID = 

    "u202303211124440adc42"


response = 

  ResponseMessage with properties:

    StatusLine: 'HTTP/1.1 201 CREATED'
    StatusCode: Created
        Header: [1×15 matlab.net.http.HeaderField]
          Body: [1×1 matlab.net.http.MessageBody]
     Completed: 0

Create Field List

Next, create a payload structure that holds all of the data fields that you want to request.

fieldListPayload.type = "DataFieldListMR";

% add unique identifier for request
fieldListPayload.identifier = "fieldList" + bloombergHypermedia.generateResourcePostfix;
          
% add title
fieldListPayload.title = "Test Data Field List " + string(datetime);
          
% add description of list
fieldListPayload.description = "Test data field list: pxAsk, pxLast, idBbGlobal";

% add the fields to retrieve in subsequent data requests
fieldListPayload.contains{1}.id = "https://api.bloomberg.com/eap/catalogs/bbg/fields/pxAsk";
fieldListPayload.contains{2}.id = "https://api.bloomberg.com/eap/catalogs/bbg/fields/pxLast";
fieldListPayload.contains{3}.id = "https://api.bloomberg.com/eap/catalogs/bbg/fields/idBbGlobal";
fieldListPayload.contains{4}.id = "https://api.bloomberg.com/eap/catalogs/bbg/fields/lastUpdateDt";

Then create the field list by using the createFieldList function. The function outputs the field list ID and a response message that confirms the creation of the field list.

[fieldListID,response] = createFieldList(c,userCatalog,fieldListPayload)

fieldListID = 

    "fieldList20230321112611f7f580"


response = 

  ResponseMessage with properties:

    StatusLine: 'HTTP/1.1 201 CREATED'
    StatusCode: Created
        Header: [1×15 matlab.net.http.HeaderField]
          Body: [1×1 matlab.net.http.MessageBody]
     Completed: 0

Create Trigger to Schedule Request

To schedule your data request, you must create a trigger. First, create a payload structure that holds the trigger parameters. This trigger is for a pricing snapshot that occurs every day at 5 p.m. Eastern Standard Time starting on June 24, 2022.

triggerPayload.type = "PricingSnapshotTrigger";
triggerPayload.identifier = "dailySnap5PM";
triggerPayload.title = "Daily 5 PM snapshot";
triggerPayload.description = "Daily job for 5 PM snapshot";
triggerPayload.snapshotTime = "17:00:00";
triggerPayload.snapshotTimeZoneName = "America/New_York";
triggerPayload.snapshotDate = "2022-06-24";
triggerPayload.frequency = "daily";

Then create the trigger by using the createTrigger function, which outputs a trigger ID and a response message that confirms the creation of the trigger.

[triggerID,response] = createTrigger(c,userCatalog,triggerPayload)

triggerID = 

    "dailySnap5PM"


response = 

  ResponseMessage with properties:

    StatusLine: 'HTTP/1.1 201 CREATED'
    StatusCode: Created
        Header: [1×15 matlab.net.http.HeaderField]
          Body: [1×1 matlab.net.http.MessageBody]
     Completed: 0

Create Data Request

Create a payload structure that holds information about the request. This example uses additional options from the Hypermedia API to define a historical request.

requestID = "r" + bloombergHypermedia.generateResourcePostfix;
requestPayload.identifier = requestID;
requestPayload.title = "My History Request";
requestPayload.description = "My favorite history request";
requestPayload.universe = strcat(testCase.connection.URL,"/eap/catalogs/123/universes/u2022060615481086fc10");
requestPayload.fieldList = strcat(testCase.connection.URL,"/eap/catalogs/123/fieldLists/histFieldList2022060611005354b015");
requestPayload.trigger = strcat(testCase.connection.URL,"/eap/catalogs/bbg/triggers/oneshot/");
requestPayload.formatting.type = "HistoryFormat";
requestPayload.formatting.dateFormat = "yyyymmdd";
requestPayload.formatting.fileType = "unixFileType";
requestPayload.formatting.displayPricingSource = true;

% add options for historical request
requestPayload.runtimeOptions.type = "HistoryRuntimeOptions";
requestPayload.runtimeOptions.historyPriceCurrency = "USD";
requestPayload.runtimeOptions.period = "daily";
requestPayload.runtimeOptions.dateRange.type = "IntervalDateRange";
requestPayload.runtimeOptions.dateRange.startDate = string(datetime('today','Format','yyyy-MM-dd')-10);
requestPayload.runtimeOptions.dateRange.endDate = string(datetime('today','Format','yyyy-MM-dd'));
requestPayload.pricingSourceOptions.type = "HistoryPricingSourceOptions";
requestPayload.pricingSourceOptions.exclusive = true;

Then create the request by using the createRequest function, which outputs the request ID and a response message that confirms the creation of the request.

[requestID,response] = createRequest(c,userCatalog,requestPayload)

requestID = 

    "r202303211130197aaa0d"


response = 

  ResponseMessage with properties:

    StatusLine: 'HTTP/1.1 201 CREATED'
    StatusCode: Created
        Header: [1×15 matlab.net.http.HeaderField]
          Body: [1×1 matlab.net.http.MessageBody]
     Completed: 0

Retrieve Request Information and Data

Now you can retrieve your data. First, extract the data request information using the getRequests function. Then extract the request date.

requestInfo = getRequests(c,userCatalog,requestID)
requestDate = requestInfo.issued{1}(1,[1:4,6:7,9:10])

Retrieve the data by using the getData function, specifying the request ID and the date that you extracted.

requestID = "r202303211130197aaa0d";
[data,response] = getData(c,userCatalog,requestID,requestDate)

data =

  14×7 timetable

       Time           SECURITIES       ERROR CODE    NUM FLDS    MARKET    PX_ASK    PX_LAST    ID_BB_GLOBAL
    ___________    ________________    __________    ________    ______    ______    _______    ____________

    13-Mar-2023    "Growth US Equity"       "0"          "3"        "US"      41.79     41.78        "N.A."   
    14-Mar-2023    "Growth US Equity"       "0"          "3"        "US"      43.79     43.80        "N.A."   
    15-Mar-2023    "Growth US Equity"       "0"          "3"        "US"      43.56     43.54        "N.A."   
    16-Mar-2023    "Growth US Equity"       "0"          "3"        "US"      44.70     44.67        "N.A."   
    17-Mar-2023    "Growth US Equity"       "0"          "3"        "US"      44.68     44.68        "N.A."   
    20-Mar-2023    "Growth US Equity"       "0"          "3"        "US"      43.88     43.88        "N.A."   
    21-Mar-2023    "Growth US Equity"       "0"          "3"        "US"      44.93     44.92        "N.A."   
    13-Mar-2023    "Value US Equity"        "0"          "3"        "US"     125.59    125.58        "N.A."   
    14-Mar-2023    "Value US Equity"        "0"          "3"        "US"     124.62    124.65        "N.A."   
    15-Mar-2023    "Value US Equity"        "0"          "3"        "US"     123.35    123.28        "N.A."   
    16-Mar-2023    "Value US Equity"        "0"          "3"        "US"     124.71    124.70        "N.A."   
    17-Mar-2023    "Value US Equity"        "0"          "3"        "US"     123.74    123.69        "N.A."   
    20-Mar-2023    "Value US Equity"        "0"          "3"        "US"     125.95    125.94        "N.A."   
    21-Mar-2023    "Value US Equity"        "0"          "3"        "US"     126.51    126.50        "N.A."   


response = 

  ResponseMessage with properties:

    StatusLine: 'HTTP/1.1 200 OK'
    StatusCode: OK
        Header: [1×15 matlab.net.http.HeaderField]
          Body: [1×1 matlab.net.http.MessageBody]
     Completed: 0

In the StatusCode field of the response message, OK signifies a successful Hypermedia data retrieval contained in data. The retrieved data is a MATLAB timetable and varies depending on the type of request.

The Bloomberg Hypermedia interface also includes functions to retrieve universe, field list, and trigger:

Additionally, the getFields function returns the entire available Bloomberg field list or information about a given field. Note that retrieving the entire available field list takes a significant amount of time.

External Websites

Bloomberg HAPI Documentation