Did you know that with API access you can download Empirasign Market Data right into Excel for easier manipulation? If you currently don't have an API license, please contact us and we can set you up with a demo ID and a few hundred free queries to kick the tires: info@empirasign.com

Jump To:

API Documentation

Getting Started

Download the Sample Spreadsheet: Download the Sample Spreadsheet

Is Python your thing? Download example code here: gist.github.com/empirasign/cbd204ae7f45bc4eadae

Handling Excel Download and Macro

If you see the Excel Red Bar Warning that macros have been disabled (screenshot below), this can be dismissed by copying the spreadsheet from the Downloads folder to your My Documents folder and re-opening the spreadsheet. You can also copy the file to any folder where you normally save spreadsheets. In general, Windows can be pretty finicky about Office files opened directly from the browser or from the Downloads folder.

If you see the Excel Yellow Bar Warning with the message "Some active content has been disabled.", or similar, you must click the Enable Content button to allow the macros to function. Screenshot below. It is common to see the Yellow Bar Warning only after you have dispensed with the Red Bar Warning.

Entering your credentials:
In the credentials tab, found below, enter your API ID into cell B4 and your API Password into cell B5. If your machine sits behind a proxy server, this must be entered into cell B8. More on proxy servers below.

To Retrieve Market Data for a Single CUSIP/ticker:

Just enter the cusip or ticker for the security you want to query into Cell B8 on the main tab, and then click the "Get Bond Data" button. Searches can also be constrained by trade date by entering a date range in cells B9 and B10.

Example CUSIP Query

For bulk CUSIP/ticker Market Data queries:

Just enter all the cusips/tickers you want to query into the marked area under column A on the bulk tab and click the "Retrieve Data" button. All our market data will be populated in the bulk_results tab. You can still use the main tab to do single cusip or ticker requests.

Results of Bulk Search:

To Retrieve BWICs for a Specific Date:

Go to the bwics tab. Enter the market sector you want to query (see complete list below) into cell B8. Enter the date range you want to see the BWICs for into cells B9 and B10. If the Date cells are left empty, the search will default to the current date. Click on the "Get BWIC Data" button to run the query.

Retrieve BWICs Specific Date

To Retrieve Offers for Dealer/Sector/Date Combo:

This is a two step process: First see what dealer/sector combos are available for a given date, then download the offerings for a dealer/sector/date combo.

To see what dealer/sector combos are available for a given date, go to the offers tab and enter the date you want to query into cell B8. Then click the Get Available Offers button to view what dealer/sector/num_bonds combos are available for that date. This information will be displayed below the range A12:C12 which is labeled sector/dealer/num_bonds. Once you have decided what combo you are interested in, enter the sector into cell B9 and dealer name into cell B10. Make sure to use the same names as displayed. Now, click the Get Dealer Offers button to retrieve the actual offering data. Once the query has run, this data will be displayed under the range E7:Y7.

API Data Dictionary

The headers for each column in the spreadsheet results table are defined below:

  • kind: the kind of record described in that line item
  • bbg_ticker: the Bloomberg identifier for the bond
  • bsym_sec_type: specific sector of bond ('bsym' = Bloomberg open symbology, now OpenFIGI)
  • cusip: the CUSIP identifier for the bond
  • of_bid: original face on bid
  • cf_bid: current face on bid
  • of: original face
  • cf: current face on trade date
  • price_bid: bid price
  • price32_bid: bid price, with decimals expressed as fraction of 32
  • spread_dec_bid: decimal interpretation of bid spread column
  • spread_bid: bid spread
  • price: trade price
  • price_32: trade price, with decimals expressed as fraction of 32
  • spread_dec: decimal interpretation of spread column
  • spread: trade spread
  • curve: associated reference curve for spread
  • color: trade color. Possible results:
    - cover = second best bid on a bond
    - dnt = did not trade
    - reo = re-offer
    - res = reserve price of bond that did not trade
    - trade = trade price (bond has been traded)
    - trade-p = bond usually traded as part of a package; usually an-all-or-nothing-list
  • trade_dt: trade date
  • settle_dt: settle date
  • dealer: you can find a list of these abbreviations here
  • dealer_notes: any notes specified by dealer

*It is important to note that a blank column usually indicates that it is irrelevant to the kind of record being described, or because the data was not reported by the market.

BWIC Sectors You Can Query:

  • agency: US Agency ARMs and CMOs
  • cmbs: US CMBS (Agency and Non-Agency)
  • nonag: US Non-Agency RMBS (does not include heq/subprime)
  • abs: US ABS (Res, Consumer, Esoteric, CLO, and CDO)
  • naresi: All US Non-Agency Resi
  • conabs: All US Consumer ABS
  • clo: US/EU/UK CLO
  • euro: UK/EU RMBS, ABS, CMBS, CLO
  • eu-resi: UK/EU RMBS
  • eu-abs: UK/EU ABS
  • eu-cmbs: UK/EU CMBS
  • agarm: US Agency ARMs
  • agcmo: US Agency CMOs
  • snr: US CMBS Seniors
  • agcmbs: US Agency CMBS
  • am: US CMBS AM tranches
  • aj: US CMBS AJ tranches
  • io: US CMBS IOs
  • mezz: US CMBS Mezz
  • cre-cdo: CMBS CRE CDO
  • unk: US CMBS (other)
  • alta-15: US 15yr Alt-A fixed
  • alta-30: US 30yr Alt-A fixed
  • prime-15: US 15yr Prime Fixed
  • prime-30: US 30yr Prime Fixed
  • prime-a: US Prime Adjustable
  • auto: US Auto Loans
  • card: US Credit Cards
  • equip: US Equipment Loans
  • heloc: US Heloc
  • heq: US Home Equity
  • mh: US Manufactured Housing
  • other: US ABS (CLO + other)
  • student: US Student Loans
  • subprime: US Subprime
  • utility: US Utility

API Quota Counts:

From a quota perspective, a query is counted for any request that will return market-level data (e.g. cover, price talk, bid, offer, market).

View a real-time audit of your quota usage on the query__log tab on the API excel worksheet.


  • 1 query per call.


  • n number of queries per call, where n is the number of bonds in a query (max 200).
    Ex: if you request data on 300 bonds, only the first 200 results will be returned and 200 queries will be counted against your quota.


  • 0 queries. Call does not count against your quota.


  • n number of queries per call, if n number of bonds are returned for a dealer/sector/date offer sheet request.
  • 0 queries are counted for requests to view offers that are available to query (i.e. 'Get Available Offers' button on spreadsheet). This will return dealer inventory counts for a given sector on a particular date.


  • 0 queries. Call does not count against your quota.


  • 0 queries. Call does not count against your quota.


  • 0 queries. Call does not count against your quota.

Do I need to enter a Proxy Server?

For those of you sitting behind a proxy server, our API now plays nicely with them. Just enter the proxy server address in the appropriate cell on the new credentials tab. See below:

The best way to determine this is to see if your copy of Internet Explorer uses one. This can be found by clicking the "LAN Settings" button on the Connections tab under the menu Tools -> Internet Options. Example Proxy Server: bankproxy:80 If you do not need or use a proxy server, simply leave this cell blank. If your browser uses an automatic configuration script, you'll need to use a parser to extract the Proxy Server address. To do so, either consult us directly or feel free use our web based parser.

More on Proxy Servers: support.microsoft.com/kb/135982
More on Proxy Auto Config scripts: en.wikipedia.org/wiki/Proxy_auto-config

The above examples are all illustrated via our demo Excel spreadsheet. The spreadsheet code that interacts with the API is written in VBA. We also have demonstration scripts written in Python. We can provide these and further documentation upon request. Any language that can form a valid HTTP request should have no issues interacting with our API.

To download the spreadsheet used in the above examples, please follow this link: Excel Download