This API Version is out of date. For information on the most recent version, visit /v1/market-api-docs/.
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.
/api/cusip/
- 1 query per call.
/api/bonds/
- n number of queries per call, where n is the number of bonds in a query (max 500).
For example, if you request data on 600 bonds, only the first 500 results will be returned and 500 queries will be counted against your quota.
/api/bwics/
- 0 queries. Call does not count against your quota.
/api/offers/
- 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.
/api/mbsfeed/
- 0 queries. Call does not count against your quota.
/api/mystatus/
- 0 queries. Call does not count against your quota.
/api/query_log/
- 0 queries. Call does not count against your quota.
MBS API Dictionary
POST /api/bonds/
Retrieve BWIC and runs data for a list of Bloomberg Tickers, CUSIPs, and ISINs.
Request parameters
bonds (comma separated), app_id, req_sig, nport (true or false)
Response fields
data
- bbg_ticker, bbgid, cf, curve, cusip, dealer, kind='pxtalk', list_id, of, price, price32, settle_dt, spread, spread_dec, trade_dt
- bbg_ticker, bbgid, cf, color, curve, cusip, kind='bwic', list_id, of, price, price32, settle_dt, spread, trade_dt
- bbg_ticker, bbgid, cf_bid, curve, cusip, dealer, dealer_notes, kind='bid', of_bid, price32_bid, price_bid, settle_dt, spread_bid, trade_dt
- bbg_ticker, bbgid, cf, curve, cusip, dealer, dealer_notes, kind='offer', of, price, price32, settle_dt, spread, trade_dt
- bbg_ticker, bbgid, cf, cf_bid, curve, cusip, dealer, dealer_notes, kind='market', of, of_bid, price, price32, price32_bid, price_bid, settle_dt, spread, spread_bid, trade_dt
- if nport=true same as above plus: kind, cusip, isin, regName, seriesName, repPdDate, balance, balanceCurCd, balanceExchangeRt, valUSD, fairValLevel, units, accessionNumber, regCik, annualizedRt
meta
errors, requests_left, results
Example Reponse
{
"meta": {
"errors": [],
"requests_left": 4896,
"results": "OK"
},
"data": [
{
"curve": null,
"cusip": "XS0264193797",
"bbg_ticker": "AIREM 2006-1X 2C2",
"cf": null,
"of": 83.0,
"trade_dt": "2013-02-08",
"spread": null,
"settle_dt": "2013-02-13",
"kind": "offer",
"dealer_notes": null,
"bbgid": null,
"price32": null,
"price": 82.25,
"dealer": "jefferies"
}
]
}
GET /api/bwics/
Retrieve summary level data for a day's Agency CMO BWICs.
Request parameters
sector, dt, app_id, req_sig
Response fields
data
bonds: [bbg_ticker, bbgid, cusip, isin, of]
cf
cusips
description
isins
list_id
num_bonds
num_color
num_distinct_talk
num_talk
num_trace
seller
settle_dt
trade_dt
trade_datetime_utc
uids
meta
errors, notes, requests_left, results
Example Reponse (some results removed for space):
{
"data": [
{
"bonds": [
{
"bbg_ticker": "FHR 3777 DA",
"bbgid": "BBG001CNH1M8",
"cusip": "3137A42F3",
"isin": null,
"of": 8.0
}
],
"cf": 0.2,
"cusips": [
"3137A42F3"
],
"description": "FHR 3777 DA",
"isins": [
"US3137A42F37"
],
"list_id": "181105J",
"num_bonds": 1,
"num_color": 0,
"num_distinct_talk": 0,
"num_talk": 0,
"num_trace": 0,
"seller": null,
"settle_dt": "2018-11-08",
"trade_dt": "2018-11-05 10:00",
"trade_dt_utc": "2018-11-05T15:00:00",
"uids": [
"3137A42F3"
]
},
],
"meta": {
"errors": [],
"requests_left": 4936,
"results": "OK"
}
}
POST /api/nport/
Retrieve NPORT data for a list of Bloomberg Tickers, CUSIPs, and ISINs.
Request parameters
bonds (comma separated), app_id, req_sig
Response fields
data
kind, cusip, isin, regName, seriesName, seriesLei, repPdDate, balance, balanceCurCd, balanceExchangeRt, valUSD, fairValLevel, units, accessionNumber, regCik, annualizedRt
meta
errors, requests_left, results
Example Reponse:
{
"data": [
{
"accessionNumber": "0001752724-19-177502",
"annualizedRt": 2.32,
"balance": 500000,
"balanceCurCd": "USD",
"balanceExchangeRt": 1.0,
"cusip": "40438DAD1",
"fairValLevel": 2,
"isin": "US40438DAD12",
"kind": "nport",
"regCik": "0000908695",
"regName": "USAA Mutual Funds Trust",
"repPdDate": "2019-09-30",
"seriesLei": "5493002WB6DHNEK4HM51",
"seriesName": "Ultra Short-Term Bond Fund",
"units": "PA",
"valUSD": 500369.4
},
{
"accessionNumber": "0001752724-19-181680",
"annualizedRt": 2.32,
"balance": 6292000,
"balanceCurCd": "USD",
"balanceExchangeRt": 1.0,
"cusip": "40438DAD1",
"fairValLevel": 2,
"isin": "US40438DAD12",
"kind": "nport",
"regCik": "0000099203",
"regName": "FPA NEW INCOME INC",
"repPdDate": "2019-09-30",
"seriesLei": "549300EH2YCK6M0NO786",
"seriesName": "FPA New Income, Inc.",
"units": "PA",
"valUSD": 6296648.53
}
],
"meta": {
"errors": [],
"requests_left": 2152,
"results": "OK"
}
}
GET /api/offers/
Retrieve all available bids, offers, and markets for a specific date.
Request parameters:
dt, app_id, req_sig, min_cf
Response fields:
offers_available
dealer, num_bonds, sector
meta
errors, requests_left, results
Example Reponse
{
"offers_available": [
{
"sector": "nonag",
"num_bonds": 9,
"dealer": "amherst"
},
{
"sector": "nonag",
"num_bonds": 10,
"dealer": "ballantyne"
},
{
"sector": "nonag",
"num_bonds": 51,
"dealer": "bnp"
},
{
"sector": "nonag",
"num_bonds": 25,
"dealer": "nomura"
},
{
"sector": "nonag",
"num_bonds": 3,
"dealer": "rbc"
}
],
"meta": {
"errors": [],
"requests_left": 4896,
"results": "OK"
}
}
Retrieve bids, offers, and markets for a dealer/sector/date combination.
Request parameters:
sector, dt, dealer, app_id, req_sig
Response fields:
offers
bbg_ticker, bbgid, cf, curve, cusip, dealer, dealer_notes, kind, of, price, price32, settle_dt, spread, trade_dt
markets
bbg_ticker, bbgid, cf, cf_bid, curve, cusip, dealer, dealer_notes, kind, of, of_bid, price, price32, price32_bid, price_bid, settle_dt, spread, spread_bid, trade_dt
bids
bbg_ticker, bbgid, cf_bid, curve, cusip, dealer, dealer_notes, kind, of_bid, price32_bid, price_bid, settle_dt, spread_bid, trade_dt
meta
errors, requests_left, results
Example Reponse:
{
"markets": [],
"offers": [
{
"curve": null,
"cusip": "3136AB2Q5",
"offer_dt": "2015-05-05",
"bbg_ticker": "FNR 2013-11 SB",
"cf": 30.9457,
"of": 35.4222,
"trade_dt": "2015-05-05",
"spread": null,
"settle_dt": "2015-05-08",
"kind": "offer",
"dealer_notes": null,
"bbgid": null,
"price32": "25-00",
"price": null,
"dealer": "citi"
}
],
"bids": [],
"meta": {
"errors": [],
"requests_left": 4803,
"results": "OK"
}
}
POST /api/collab/
Retrieve individual bond suggestions for a list of Bloomberg Tickers, CUSIPs, and ISINs. Suggestions are based on our collaborative filter recommendation engine.
Request parameters:
bonds (comma separated), app_id, req_sig
Response fields:
rec_list
input
suggestions: [(bbg_ticker, isin, cusip)]
meta
errors, requests_left, results
Example Reponse:
{
"meta": {
"errors": [],
"requests_left": 2489,
"results": "OK"
},
"rec_list": [
{
"input": "US30711XSX39",
"suggestions": [
[
"CAS 2018-C03 1M2",
"US30711XJ702",
"30711XJ70"
],
[
"CAS 2017-C07 2M2",
"US30711XWX82",
"30711XWX8"
],
[
"CAS 2016-C05 2M1",
"US30711XDG60",
"30711XDG6"
],
[
"CAS 2018-C02 2M2",
"US30711XC368",
"30711XC36"
],
[
"CAS 2017-C04 2M2",
"US30711XLT99",
"30711XLT9"
],
[
"CAS 2018-C06 1M1",
"US30711X3G73",
"30711X3G7"
]
]
},
{
"input": "SYNCT 2017-1 A",
"suggestions": [
[
"GMALT 2017-2 A3",
"US38013MAD83",
"38013MAD8"
],
[
"CHAIT 2018-A1 A1",
"US161571HN70",
"161571HN7"
],
[
"COMET 2017-A6 A6",
"US14041NFQ97",
"14041NFQ9"
],
[
"KCOT 2018-1A A2",
"US50117PAB58",
"50117PAB5"
],
[
"BMWLT 2017-2 A3",
"US05584PAD96",
"05584PAD9"
],
[
"SRT 2017-A A3",
"US80285AAG04",
"80285AAG0"
]
]
},
{
"input": "64828AAK9",
"suggestions": [
[
"NRZT 2015-1A B4",
"US64829CAM01",
"64829CAM0"
],
[
"NRZT 2015-1A B5",
"US64829CAS70",
"64829CAS7"
],
[
"NRZT 2014-2A B4",
"US64828YAJ01",
"64828YAJ0"
],
[
"NRZT 2015-1A B3",
"US64829CAL28",
"64829CAL2"
],
[
"NRZT 2014-3A B4",
"US64829DAR70",
"64829DAR7"
]
]
}
]
}
GET /api/mbsfeed/
Retrieve the latest BWIC related events from the news feed.
Request parameters:
n (must be an integer between 1 and 50), app_id, req_sig
Response fields:
events
bbg_tickers, event_type, list_id, timestamp
meta
errors, num_records, requests_left, results
Example Response:
{
"events": [
{
"timestamp": "2015-05-29 14:56:53",
"bbg_tickers": [
"CARR 2006-FRE1 A2",
"LBMLT 2005-WL2 M1",
"MSAC 2004-WMC3 M2",
"RAAC 2006-SP2 A3",
"GSAMP 2006-NC1 A2",
"AMIT 2004-1 M5",
"ELAT 2007-1 A2B"
],
"list_id": "150529N",
"event_type": "add_color"
}
],
"meta": {
"errors": [],
"requests_left": 4803,
"num_records": 1,
"results": "OK"
}
}
POST /api/deal-classes/
Retrieve all tranches for a deal
Request parameters
bond (cusip, isin or ticker), app_id, req_sig
Response fields
bonds
bbg_ticker, cusip, figi, isin
meta
errors, requests_left, results
Example Reponse:
{
"bonds": [
{
"bbg_ticker": "FNW 2009-W1 A",
"cusip": "31398F7A3",
"figi": "BBG0009YWDY4",
"isin": "US31398F7A36"
},
{
"bbg_ticker": "FNW 2009-W1 B1",
"cusip": "31398F7D7",
"figi": "BBG0009YWF06",
"isin": "US31398F7D74"
},
{
"bbg_ticker": "FNW 2009-W1 B2",
"cusip": "31398F7E5",
"figi": "BBG0009YWF24",
"isin": "US31398F7E57"
},
{
"bbg_ticker": "FNW 2009-W1 IO",
"cusip": "31398F7B1",
"figi": "BBG0009YWFH8",
"isin": "US31398F7B19"
},
{
"bbg_ticker": "FNW 2009-W1 PO",
"cusip": "31398F7C9",
"figi": "BBG0009YWFF0",
"isin": "US31398F7C91"
},
{
"bbg_ticker": "FNW 2009-W1 R",
"cusip": "31398F7F2",
"figi": "BBG0009YWF79",
"isin": "US31398F7F23"
},
{
"bbg_ticker": "FNW 2009-W1 RL",
"cusip": "31398F7G0",
"figi": "BBG0009YWF97",
"isin": "US31398F7G06"
}
],
"meta": {
"errors": [],
"requests_left": 2500,
"results": "OK"
}
}
GET /api/all-bonds/
Retrieve all bonds for a given date.
Request parameters
dt (current date to current date - 60), figi_marketsector (Mtge, Corp), app_id, kind (bwics, runs, empty), req_sig
Response fields
bonds
bbg_ticker, cusip, figi, figi_marketsector, figi_securitytype, figi_securitytype2, isin
meta
errors, num_records, requests_left, results
Example Reponse:
{
"bonds": [
{
"bbg_ticker": "AOMT 2018-2 A1",
"cusip": "03463VAA3",
"figi": "BBG00L5B6T49",
"figi_marketsector": "Mtge",
"figi_securitytype": "Prvt CMO Other",
"figi_securitytype2": "Whole Loan",
"isin": "US03463VAA35"
},
{
"bbg_ticker": "ARCLO 2020-FL1 C",
"cusip": "03880WAG3",
"figi": "BBG00RRX5Y53",
"figi_marketsector": "Mtge",
"figi_securitytype": "CF",
"figi_securitytype2": "CRE",
"isin": "US03880WAG33"
},
{
"bbg_ticker": "AHPT 2017-ATRM D",
"cusip": "04965JAG8",
"figi": "BBG00JFF8QB0",
"figi_marketsector": "Mtge",
"figi_securitytype": "CMBS",
"figi_securitytype2": "CMBS",
"isin": "US04965JAG85"
},
{
"bbg_ticker": "BBCCR 2015-GTP A",
"cusip": "05490TAA0",
"figi": "BBG009Q03KG6",
"figi_marketsector": "Mtge",
"figi_securitytype": "CMBS",
"figi_securitytype2": "CMBS",
"isin": "US05490TAA07"
},
{
"bbg_ticker": "BBCMS 2018-RRI E",
"cusip": "05492CAN7",
"figi": "BBG00JYJRDF5",
"figi_marketsector": "Mtge",
"figi_securitytype": "CMBS",
"figi_securitytype2": "CMBS",
"isin": "US05492CAN74"
},
{
"bbg_ticker": "BBCMS 2020-C6 D",
"cusip": "05492TAK6",
"figi": "BBG00RK46FX3",
"figi_marketsector": "Mtge",
"figi_securitytype": "CMBS",
"figi_securitytype2": "CMBS",
"isin": "US05492TAK60"
},
{
"bbg_ticker": "BAMLL 2018-DSNY C",
"cusip": "054967AJ3",
"figi": "BBG00M6W54G3",
"figi_marketsector": "Mtge",
"figi_securitytype": "CMBS",
"figi_securitytype2": "CMBS",
"isin": "US054967AJ31"
},
{
"bbg_ticker": "BAMLL 2015-200P E",
"cusip": "05526QAL0",
"figi": "BBG008FK2G30",
"figi_marketsector": "Mtge",
"figi_securitytype": "CMBS",
"figi_securitytype2": "CMBS",
"isin": "US05526QAL05"
},
{
"bbg_ticker": "BBCMS 2017-DELC C",
"cusip": "05552EAJ9",
"figi": "BBG00HFRCJ10",
"figi_marketsector": "Mtge",
"figi_securitytype": "CMBS",
"figi_securitytype2": "CMBS",
"isin": "US05552EAJ91"
},
{
"bbg_ticker": "BBCMS 2017-DELC D",
"cusip": "05552EAL4",
"figi": "BBG00HFRCJ29",
"figi_marketsector": "Mtge",
"figi_securitytype": "CMBS",
"figi_securitytype2": "CMBS",
"isin": "US05552EAL48"
},
{
"bbg_ticker": "BX 2019-XL G",
"cusip": "056054AK5",
"figi": "BBG00QG2JNV5",
"figi_marketsector": "Mtge",
"figi_securitytype": "CMBS",
"figi_securitytype2": "CMBS",
"isin": "US056054AK52"
}
],
"meta": {
"errors": [],
"num_records": 11,
"requests_left": 2500,
"results": "OK"
}
}
GET /api/all-matchers/
Retrieve all bonds from the day's BWICs or Dealer Runs that also appear on recent Fund Holdings (N-PORT) and/or Insurance Transaction (NAIC) records.
Request parameters
dt (current date to current date - 30), app_id, req_sig
Response fields
matchers
bbg_ticker, isin, figi_securitytype2, figi_securitytype, BWIC, INVENTORY,
N-PORT, NAIC, num_total
meta
errors, num_records, requests_left, results
Example Reponse:
{
"matchers": [{
"BWIC": 0,
"INVENTORY": 1,
"N-PORT": 0,
"NAIC": 3,
"bbg_ticker": "ACAM 2019-FL1 B",
"figi_securitytype": "CF",
"figi_securitytype2": "CRE",
"isin": "US000825AE98",
"num_total": 4
}, {
"BWIC": 0,
"INVENTORY": 1,
"N-PORT": 0,
"NAIC": 3,
"bbg_ticker": "ACAM 2019-FL1 C",
"figi_securitytype": "CF",
"figi_securitytype2": "CRE",
"isin": "US000825AG47",
"num_total": 4
}, {
"BWIC": 0,
"INVENTORY": 1,
"N-PORT": 1,
"NAIC": 7,
"bbg_ticker": "ACRES 2021-FL1 AS",
"figi_securitytype": "CF",
"figi_securitytype2": "CRE",
"isin": "US00103CAC38",
"num_total": 9
},
...
],
"meta": {
"errors": [],
"num_records": 4138,
"requests_left": 2500,
"results": "OK"
}
}
GET /api/mystatus/
Check API status and see how many requests are left
Request parameters:
app_id, req_sig
Response fields:
errors
results
requests_left
Example Response:
{
"meta": {
"errors": [],
"requests_left": 4584,
"results": "OK"
}
GET /api/query_log/
Retrieve a log of queries made on a given date.
Request parameters:
dt, app_id, req_sig
Response fields:
errors
query_log
cid, client_ip, d0, d1, format, query, query_id, timestamp, uid_ct
results
Example Reponse:
{
"meta": {
"errors": [],
"requests_left": 4936,
"results": "OK"
},
"query_log": [
{
"d0": 20150513,
"timestamp": "2015-05-14T13:44:10",
"cid": null,
"query_id": 3356141,
"query": "BWIC-agcmo",
"format": "csv",
"client_ip": "50.74.176.138",
"uid_ct": 0,
"d1": null
}
]
}
Request Signature Generation
# APP_ID - your Empirasign API username
# PW - your Empirasign API password
# TODAY - today's date in 'YYYYMMDD' format
sig_keys = [] # SEE BELOW for endpoint-specific sig_key definitions
req_sig = hashlib.sha1("".join(sig_keys).encode("utf-8")).hexdigest()
/bwics/
# for single date
sig_keys = [APP_ID, sector, dt, PW]
# for a date range
sig_keys = [APP_ID, sector, d0, d1, PW]
/cusip/
sig_keys = [APP_ID, cusip, TODAY, PW]
/bonds/, /nport/, /collab/
sig_keys = [APP_ID, bonds, TODAY, PW]
/offers/
# if dealer & sector parameters are used
sig_keys = [APP_ID, dealer, sector, dt, PW]
# else
sig_keys = [APP_ID, dt, PW]
/all-bonds/
sig_keys = [APP_ID, figi_marketsector, dt, PW]
/deal-classes/
sig_keys = [APP_ID, bond, PW]
/all-matchers/, /query_log/
sig_keys = [APP_ID, dt, PW]
/mystatus/
sig_keys = [APP_ID, TODAY, PW]
/mbsfeed/
sig_keys = [APP_ID, n, TODAY, PW]
Do I need to enter a Proxy Server?
For those of you sitting behind a proxy server (most banks, and many hedge funds), our API plays nicely with them. Just enter the proxy server address in the appropriate cell on the credentials tab.
The best way to determine your proxy server is via our Proxy Finding macro located on the proxy_finder tab of the example spreadsheet. Click the button, and if your site uses a proxy its value will appear in cell B4.
Python
You can use this value to power all your Python scripts as well. In your scripts set the global variable PROXY_SERVER to this value. e.g. PROXY_SERVER = 'proxy.mycompany.net:8080'. Sometimes this will not work. For example, if upon executing your script you receive an error similar to the following 407 Proxy Authentication Required, you will need to enter credentials alongside your PROXY_SERVER. e.g. PROXY_SERVER = 'username:[email protected]:8080'. Your internal IT help desk can provide guidance as to which username and password to use.
Summary
The above examples are all illustrated via our demo Excel spreadsheet. The spreadsheet code that interacts with the Market Data API is written in VBA. Above, we have also linked to demonstration scripts written in Python. The Empirasign Market Data API is REST-based so it should have no issues interacting with any programming language offering HTTP and JSON support. While not officially supported, we can provide limited assistance for customers using JavaScript, C#, or Java.