Bond Search

Government and corporate bond search

curl --request POST \
  --url https://terrapinfinance.com/api/v1/bond_search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "country_codes": [
    "IT"
  ],
  "coupon_max": 4,
  "coupon_min": 3,
  "maturity_date_max": "2028-11-01",
  "maturity_date_min": "2028-10-22"
}
'

import requests

url = "https://terrapinfinance.com/api/v1/bond_search"

payload = {
    "country_codes": ["IT"],
    "coupon_max": 4,
    "coupon_min": 3,
    "maturity_date_max": "2028-11-01",
    "maturity_date_min": "2028-10-22"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    country_codes: ['IT'],
    coupon_max: 4,
    coupon_min: 3,
    maturity_date_max: '2028-11-01',
    maturity_date_min: '2028-10-22'
  })
};

fetch('https://terrapinfinance.com/api/v1/bond_search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://terrapinfinance.com/api/v1/bond_search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'country_codes' => [
        'IT'
    ],
    'coupon_max' => 4,
    'coupon_min' => 3,
    'maturity_date_max' => '2028-11-01',
    'maturity_date_min' => '2028-10-22'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://terrapinfinance.com/api/v1/bond_search"

	payload := strings.NewReader("{\n  \"country_codes\": [\n    \"IT\"\n  ],\n  \"coupon_max\": 4,\n  \"coupon_min\": 3,\n  \"maturity_date_max\": \"2028-11-01\",\n  \"maturity_date_min\": \"2028-10-22\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://terrapinfinance.com/api/v1/bond_search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country_codes\": [\n    \"IT\"\n  ],\n  \"coupon_max\": 4,\n  \"coupon_min\": 3,\n  \"maturity_date_max\": \"2028-11-01\",\n  \"maturity_date_min\": \"2028-10-22\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://terrapinfinance.com/api/v1/bond_search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country_codes\": [\n    \"IT\"\n  ],\n  \"coupon_max\": 4,\n  \"coupon_min\": 3,\n  \"maturity_date_max\": \"2028-11-01\",\n  \"maturity_date_min\": \"2028-10-22\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "country": "Italy",
      "country_code": "IT",
      "coupon": 3.75,
      "currency": "EUR",
      "isin": "IT0005571952",
      "issue_rating_group": null,
      "issuer_name": "BPER BANCA SPA",
      "issuer_rating_group": "investment_grade",
      "maturity_date": "2028-10-22",
      "ticker": "BPEIM 3.75 10/22/28 EMTN"
    }
  ],
  "next_cursor": null,
  "total": 1
}

{
  "errors": [
    {
      "detail": "Unauthorized",
      "reason": "Your account tier does not allow this operation. Contact team@terrapinfinance.com for an upgrade."
    }
  ]
}

{
  "errors": [
    {
      "detail": "Payment Required",
      "reason": "You have run out of your granted quota for this resource as defined by your account tier. Contact team@terrapinfinance.com for an upgrade."
    }
  ]
}

{
  "errors": [
    {
      "detail": "Forbidden",
      "reason": "Your account tier does not allow this operation. Contact team@terrapinfinance.com for an upgrade."
    }
  ]
}

{
  "errors": [
    {
      "detail": "Invalid string. Got: integer",
      "source": {
        "pointer": "/isins/0"
      },
      "title": "Invalid value"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Too Many Requests",
      "reason": "<string>"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Internal Server Error",
      "reason": "<string>"
    }
  ]
}

POST

api

bond_search

Government and corporate bond search

curl --request POST \
  --url https://terrapinfinance.com/api/v1/bond_search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "country_codes": [
    "IT"
  ],
  "coupon_max": 4,
  "coupon_min": 3,
  "maturity_date_max": "2028-11-01",
  "maturity_date_min": "2028-10-22"
}
'

import requests

url = "https://terrapinfinance.com/api/v1/bond_search"

payload = {
    "country_codes": ["IT"],
    "coupon_max": 4,
    "coupon_min": 3,
    "maturity_date_max": "2028-11-01",
    "maturity_date_min": "2028-10-22"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    country_codes: ['IT'],
    coupon_max: 4,
    coupon_min: 3,
    maturity_date_max: '2028-11-01',
    maturity_date_min: '2028-10-22'
  })
};

fetch('https://terrapinfinance.com/api/v1/bond_search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://terrapinfinance.com/api/v1/bond_search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'country_codes' => [
        'IT'
    ],
    'coupon_max' => 4,
    'coupon_min' => 3,
    'maturity_date_max' => '2028-11-01',
    'maturity_date_min' => '2028-10-22'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://terrapinfinance.com/api/v1/bond_search"

	payload := strings.NewReader("{\n  \"country_codes\": [\n    \"IT\"\n  ],\n  \"coupon_max\": 4,\n  \"coupon_min\": 3,\n  \"maturity_date_max\": \"2028-11-01\",\n  \"maturity_date_min\": \"2028-10-22\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://terrapinfinance.com/api/v1/bond_search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country_codes\": [\n    \"IT\"\n  ],\n  \"coupon_max\": 4,\n  \"coupon_min\": 3,\n  \"maturity_date_max\": \"2028-11-01\",\n  \"maturity_date_min\": \"2028-10-22\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://terrapinfinance.com/api/v1/bond_search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country_codes\": [\n    \"IT\"\n  ],\n  \"coupon_max\": 4,\n  \"coupon_min\": 3,\n  \"maturity_date_max\": \"2028-11-01\",\n  \"maturity_date_min\": \"2028-10-22\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "country": "Italy",
      "country_code": "IT",
      "coupon": 3.75,
      "currency": "EUR",
      "isin": "IT0005571952",
      "issue_rating_group": null,
      "issuer_name": "BPER BANCA SPA",
      "issuer_rating_group": "investment_grade",
      "maturity_date": "2028-10-22",
      "ticker": "BPEIM 3.75 10/22/28 EMTN"
    }
  ],
  "next_cursor": null,
  "total": 1
}

{
  "errors": [
    {
      "detail": "Unauthorized",
      "reason": "Your account tier does not allow this operation. Contact team@terrapinfinance.com for an upgrade."
    }
  ]
}

{
  "errors": [
    {
      "detail": "Payment Required",
      "reason": "You have run out of your granted quota for this resource as defined by your account tier. Contact team@terrapinfinance.com for an upgrade."
    }
  ]
}

{
  "errors": [
    {
      "detail": "Forbidden",
      "reason": "Your account tier does not allow this operation. Contact team@terrapinfinance.com for an upgrade."
    }
  ]
}

{
  "errors": [
    {
      "detail": "Invalid string. Got: integer",
      "source": {
        "pointer": "/isins/0"
      },
      "title": "Invalid value"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Too Many Requests",
      "reason": "<string>"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Internal Server Error",
      "reason": "<string>"
    }
  ]
}

This endpoint is deprecated. See Bond Search instead. The endpoint will be maintained and available until February 1, 2027.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

asset_classes

enum<string>[]

Asset classes:

structured product: Structured debt instrument.
medium-term note: Bond with medium-term maturity.
money market: Short-term debt instrument.
bond: Standard debt security.
asset-backed security: Securitized debt backed by assets.
mortgage-backed security: Securitized debt backed by mortgages.
convertible note: Can be converted to equity.

Available options:

asset-backed security,

bond,

bond with warrants attached,

certificate of deposit,

convertible note,

depository receipt on debt instruments,

depository shares,

medium-term note,

money market,

mortgage-backed security,

preferred stock,

share certificate,

structured product

country_codes

string[]

Countries of issuing entity (ISO 3166-1 alpha-2 country codes):

Examples:

DE: Country of issue is Germany.
FR: Country of issue is France.
US: Country of issue is United States of America.

Required string length: 2

coupon_max

number

Maximum coupon of the bond.

coupon_min

number

Minimum coupon of the bond.

currencies

string[]

Bond currencies, 3-letter ISO 4217 code.

Required string length: 3

cursor

string | null

The next_cursor of the previous page. Leave out, or send null, for the first page. Only cursor and limit may change between pages. See Pagination.

full_reference_data

boolean

Return full reference data as in from /api/v1/bond_reference. This option requires a special account tier.

handles

enum<string>[]

Bond handles - predefined categories for filtering bonds by type and characteristics.

Available options by country:

German Bonds (DE):

de_bund: German long-term government bonds (Bundesanleihen).
de_bobl: German medium-term government bonds (Bundesobligationen).
de_schatz: German short-term government bonds (Bundesschatzanweisungen).
de_bubill: German short-term government bills (Bundesschatzanweisungen).
de_ilb: German inflation-linked government bonds.
de_green: German green government bonds.

UK Bonds (GB):

uk_gilt: UK government bonds (Gilts).
uk_green_gilt: UK green government bonds.
uk_il_gilt: UK inflation-linked government bonds.
uk_bill: UK short-term government bills.

French Bonds (FR):

fr_oat: French long-term government bonds (Obligations Assimilables du Trésor).
fr_oatei: French inflation-linked government bonds (OATi).
fr_oati: French inflation-linked government bonds (alternative naming).
fr_btf: French short-term government bills (Bons du Trésor à taux fixe).
fr_bond: French government bonds (general category).

Dutch Bonds (NL):

nl_dsl: Dutch government loans (Dutch State Loans).
nl_dtc: Dutch short-term government securities (Dutch Treasury Certificates).

Canadian Bonds (CA):

ca_bond: Canadian government bonds.
ca_bill: Canadian short-term government bills.
ca_cmb: Canadian mortgage-backed securities (Canada Mortgage Bonds).
ca_ulbond: Canadian ultra-long government bonds (>30 years).
ca_rrbond: Canadian inflation-linked bonds (Real Return Bonds).
ca_green: Canadian green government bonds.

Swiss Bonds (CH):

ch_bond: Swiss government bonds.

Czech Bonds (CZ):

cz_bond: Czech government bonds.
cz_bill: Czech short-term government bills.
cz_fr_bond: Czech floating-rate government bonds.
cz_zr_bond: Czech zero-coupon government bonds.

Spanish Bonds (ES):

es_bill: Spanish short-term government bills.
es_bond: Spanish government bonds.
es_ilb_bond: Spanish inflation-linked government bonds.
es_zr_bond: Spanish zero-coupon government bonds.
es_vr_bond: Spanish variable-rate government bonds.

Chinese Bonds (CN):

cn_bill: Chinese government short-term bills.
cn_bond: Chinese government bonds.
cn_bond_vr: Chinese government variable-rate bonds.
cn_bond_zr: Chinese government zero-coupon bonds.

US Treasury Bonds (US):

us_tips: US Treasury Inflation-Protected Securities (TIPS).
us_frn: US Treasury Floating Rate Notes (FRN).
us_bill: US Treasury Bills (short-term securities).
us_cmb: US Treasury Cash Management Bills (CMB).
us_note: US Treasury Notes (medium-term securities).
us_bond: US Treasury Bonds (long-term securities).

Thai Bonds (TH):

th_bill: Thai short-term government bills.
th_bond: Thai government bonds.
th_ilb_bond: Thai inflation-linked government bonds.
th_green_bond: Thai green government bonds.
th_zr_bond: Thai zero-coupon government bonds.
th_vr_bond: Thai variable-rate government bonds.

Japanese Bonds (JP):

jp_bill: Japanese short-term government bills (Treasury discount bills).
jp_bond: Japanese government bonds.
jp_zr_bond: Japanese zero-coupon government bonds.
jp_vr_bond: Japanese variable-rate government bonds.
jp_ilb: Japanese inflation-linked government bonds.
jp_transition: Japanese climate transition government bonds.

Italian Bonds (IT):

it_bill: Italian short-term government bills (BOT).
it_bond: Italian government bonds (BTP).
it_green: Italian green government bonds (BTP Green).
it_ilb: Italian inflation-linked government bonds (BTP Italia).
it_ilb_euro: Italian euro inflation-linked government bonds (BTPi).
it_zr_bond: Italian zero-coupon government bonds.
it_vr_bond: Italian variable-rate government bonds (CCTeu).

Available options:

ca_bill,

ca_bond,

ca_cmb,

ca_green,

ca_rrbond,

ca_ulbond,

ch_bond,

cn_bill,

cn_bond,

cn_bond_vr,

cn_bond_zr,

cz_bill,

cz_bond,

cz_fr_bond,

cz_zr_bond,

de_bobl,

de_bubill,

de_bund,

de_green,

de_ilb,

de_schatz,

es_bill,

es_bond,

es_ilb_bond,

es_vr_bond,

es_zr_bond,

fr_btf,

fr_oat,

fr_oatei,

fr_oati,

it_bill,

it_bond,

it_green,

it_ilb,

it_ilb_euro,

it_vr_bond,

it_zr_bond,

jp_bill,

jp_bond,

jp_ilb,

jp_transition,

jp_vr_bond,

jp_zr_bond,

nl_dsl,

nl_dtc,

uk_bill,

uk_gilt,

uk_green_gilt,

uk_il_gilt,

us_bill,

us_bond,

us_cmb,

us_frn,

us_note,

us_tips

include_callable

boolean

Whether to include callable bonds, bonds that can be redeemed by the issuer before maturity.

include_non_outstanding

boolean

default:false

Whether to include non-outstanding bonds (matured or redeemed bonds), vastly increases results.

include_puttable

boolean

Whether to include puttable bonds, bonds that can be sold back to the issuer before maturity.

interest_types

enum<string>[]

Types of interest:

zero rate / discount rate: A bond that does not pay or accrue interest.
fixed rate: Pays a fixed coupon throughout the bond's life.
variable rate: Coupon varies with a reference rate (e.g., SOFR, SONIA, Inflation indexes, etc.).
step rate: The bond's interest rate increases ("steps up") at predetermined intervals.
misc.: Miscellaneous interest types.
payment in kind: Interest paid in additional securities.
dividend payments: Interest paid as dividends.
cash payment: Interest paid in cash.
at maturity: Interest paid at maturity.

Available options:

at maturity,

cash payment,

dividend payments,

fixed rate,

misc.,

payment in kind,

step rate,

variable rate,

zero rate / discount rate

isins

string[]

International Securities Identification Number (ISIN), unique 12-character code for the security.

Required string length: 12

issue_rating_group

enum<string> | null

Issue rating group, based on TP composite long-term ratings:

investment_grade: High credit quality (BBB- and above)
high_yield: Lower credit quality (BB+ and below)

Available options:

high_yield,

investment_grade

issued_amount_max

integer

Maximum size of total amount issued (in nominal value).

Required range: x >= 0

issued_amount_min

integer

Minimum size of total amount issued (in nominal value).

Required range: x >= 0

issuer_name

string | null

Name of the issuing entity.

issuer_rating_group

enum<string> | null

Issuer rating group, based on TP composite long-term ratings:

investment_grade: High credit quality (BBB- and above)
high_yield: Lower credit quality (BB+ and below)

Available options:

high_yield,

investment_grade

issuer_types

enum<string>[]

Available options:

corporate,

government,

government_linked,

international_organization,

municipal,

state

last_trade_date_min

string<date>

Include only bonds that have traded since this date in ISO-8601 format (YYYY-MM-DD).

leis

string[]

Legal Entity Identifiers (LEI) of the issuer:

A 20-character, alpha-numeric code based on the ISO 17442 standard used to uniquely identify legal entities in financial transactions. Most LEIs follow this structure, but there are exceptions that use local national standards.

Required string length: 20

leis_direct_parent

string[]

LEIs of the direct parent of the issuer:

Required string length: 20

leis_ultimate_parent

string[]

LEIs of the ultimate parent of the issuer:

Required string length: 20

limit

integer

default:100

Number of results per page. A limit of 0 returns only total, the number of matching results.

Required range: x >= 0

maturity_date_max

string<date>

Maximum maturity date of the bond in ISO-8601 format (YYYY-MM-DD).

maturity_date_min

string<date>

Minimum maturity date of the bond in ISO-8601 format (YYYY-MM-DD).

maturity_types

enum<string>[]

Maturity types:

fixed: Principal repaid at maturity.
amortized: Principal repaid gradually before maturity.
perpetual: No maturity date; principal is never repaid.
extendible: Maturity date can be extended by issuer or holder.

Available options:

amortized,

extendible,

fixed,

perpetual

offset

integer

deprecated

Deprecated, will be removed on April 2, 2027. Use cursor instead, see Pagination. Number of results to skip. Can't be combined with cursor unless 0.

Required range: x >= 0

price_max

number

Maximum latest price of the bond, expressed as a percentage of the bond's face value.

price_min

number

Minimum latest price of the bond, expressed as a percentage of the bond's face value.

sort

enum<string>[]

Fields to sort by. Prefix a field with '-' for descending order. Results with no value come last. See Order for how ties are broken.

Available options:

-country,

-country_code,

-coupon,

-currency,

-isin,

-issue_rating_group,

-issuer_name,

-issuer_rating_group,

-maturity_date,

-ticker,

country,

country_code,

coupon,

currency,

isin,

issue_rating_group,

issuer_name,

issuer_rating_group,

maturity_date,

ticker

yield_to_maturity_max

number

Maximum yield to maturity of the bond.

yield_to_maturity_min

number

Minimum yield to maturity of the bond.

Response

Partial reference data

data

object[]

required

List of response data objects, often capped to 1000.

Show child attributes

next_cursor

string | null

required

Send as cursor to get the next page. null on the last page, or when limit is 0.

total

integer

required

Total number of results in the database that match the query filters.

Getting started

Data dictionaries

Other concepts

Fixed income securities

US municipal securities

US municipal bond statistics

Government Yield Curves

Inflation Factors

US agency bonds (soon to be deprecated)

Government & corporate bonds (deprecated)

Utilities

Authorizations

Body

Response