Skip to main content
POST
/
api
/
v1
/
muni_search
US municipal bond search
curl --request POST \
  --url https://terrapinfinance.com/api/v1/muni_search \
  --header 'Accept: <accept>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "interest_types": [
    "variable rate"
  ],
  "issuer_name": "ABAG Finance Authority for Nonprofit Corporations",
  "maturity_date_min": "2030-10-30"
}
'
{
  "data": [
    {
      "coupon": 5,
      "has_official_statement": true,
      "interest_type": "fixed rate",
      "is_callable": true,
      "isin": "US00037CUQ13",
      "issuer_name": "ABAG Finance Authority for Nonprofit Corporations",
      "maturity_date": "2035-11-15",
      "rating_group": "investment_grade",
      "state": "CA",
      "ticker": "CA AFAGEN 5 11/15/2035"
    }
  ],
  "total": 1
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
Accept
enum<string>
default:application/json
required

Specify text/csv if you would like to receive a CSV file.

Available options:
application/json,
text/csv

Body

application/json
​
coupon_max
number

Maximum coupon rate of the municipal bond (in percentage).

​
coupon_min
number

Minimum coupon rate of the municipal bond (in percentage).

​
full_reference_data
boolean

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

​
include_bonds_without_os
boolean
default:false

Whether to include municipal bonds for which a final official statement is not found or is not yet available. This will most often correspond to recently issued bonds.

The fields in these bonds are provided on a best-effort basis from the limited information available at that stage.

​
include_callable
boolean

Whether to include callable municipal bonds, bonds that can be redeemed before maturity.

​
interest_types
enum<string>[]

Types of interest:

  • fixed rate: The bond pays a fixed interest rate throughout its life.
  • cab: Capital Appreciation Bond (CAB), interest accrues and is paid at maturity rather than periodically.
  • variable rate: The bond's interest rate can change over time, typically based on a reference rate or formula (e.g., SOFR, CPI).
  • term rate: The bond pays interest at a rate set for a specific term or period.
  • cab-to-fixed: The bond starts as a capital appreciation bond and converts to a fixed rate bond.
  • step rate: The bond's interest rate increases ("steps up") at predetermined intervals.
  • zero rate / discount rate: A bond that does pay or accrue interest.
Available options:
at maturity,
cab,
cab-to-fixed,
cash payment,
dividend payments,
fixed interest payments,
fixed rate,
misc.,
no payments,
payment in kind,
step rate,
term rate,
variable interest payments,
variable rate,
zero rate / discount rate
​
is_insured
boolean | null

Whether the bond is insured by a bond insurance company.

​
isins
string[]

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

Required string length: 12
​
issue_date_max
string<date>

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

​
issue_date_min
string<date>

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

​
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

Name of the issuing entity (municipality, district, etc.).

​
last_traded_since
string<date>

Optional date filter to only return bonds that have been traded since the specified UTC date in ISO-8601 format (YYYY-MM-DD).

​
limit
integer
default:100

Result count limit. E.g. if total number of results is 1450, limit of 100 with offset of 0 would return the first 100 results. Use limit of -1 to opt out of limits.

Required range: x >= -1
​
maturity_date_max
string<date>

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

​
maturity_date_min
string<date>

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

​
offset
integer
default:0

Offset for query pagination. E.g. limit of 100 with offset of 50 would return the results 50 to 150.

Required range: x >= 0
​
sectors
enum<string>[]

Sector of the municipal bond:

  • education: Educational institutions (schools, universities, colleges).
  • local: Local government entities (cities, counties, towns).
  • utilities: Utility companies and infrastructure.
  • transportation: Transportation and transit systems.
  • state: State government entities.
  • healthcare: Healthcare facilities and medical institutions.
  • housing: Housing and residential development.
  • industrial: Industrial and economic development.
  • tobacco: Tobacco settlement bonds.
Available options:
education,
healthcare,
housing,
industrial,
local,
state,
tobacco,
transportation,
utilities
​
sort
enum<string>[]

Sort order. Prefix with '-' for descending order.

Available options:
-coupon,
-has_official_statement,
-interest_type,
-is_callable,
-isin,
-issuer_name,
-maturity_date,
-rating_group,
-state,
-ticker,
coupon,
has_official_statement,
interest_type,
is_callable,
isin,
issuer_name,
maturity_date,
rating_group,
state,
ticker
​
sources_of_repayment
enum<string>[]

Sources of repayment for municipal bonds. Determines how the bond will be repaid.

  • Revenue: Repaid from specific project revenues (e.g., tolls, utilities).
  • General Obligation: Repaid from the issuer's general fund.
  • Double Barrel: A combination of General Obligation and Revenue sources.
Available options:
Double Barrel,
General Obligation,
Revenue
​
states
string[]

US states or territory where the bond is issued (ANSI 2-letter code).

Required string length: 2
​
use_categories
enum<string>[]

Filter bonds by use categories (middle level of use of funds hierarchy).

For the complete taxonomy, see the Use of Funds Taxonomy reference page.

Available options:
airport,
bridges,
communication,
culture,
economic development,
electrical,
essential services,
gas,
gas prepay,
general purpose,
health system,
higher education,
hospitals,
industrial development,
military housing,
miscellaneous,
multi-family housing,
parking,
port,
power,
pre-school,
primary and secondary education,
public housing,
public transit,
recreational,
roads,
senior living,
single family housing,
student loan,
waste removal,
water and sewer
​
use_sectors
enum<string>[]

Filter bonds by use sectors (top level of use of funds hierarchy).

For the complete taxonomy, see the Use of Funds Taxonomy reference page.

Available options:
development,
education,
government,
healthcare,
housing,
miscellaneous,
recreation,
securitized,
transportation,
utility
​
uses_of_proceeds
enum<string>[]

Filter bonds by uses of proceeds (most granular level of use of funds hierarchy).

For the complete taxonomy, see the Use of Funds Taxonomy reference page.

Available options:
airport,
alternative source power,
assisted living,
broadband,
buses,
charter school,
coal power,
combined port authority,
community centre,
community college,
continuing care retirement community,
correctional facilities,
courts,
critical access hospital,
development district,
electrical infrastructure,
ferries,
fire,
flood control,
gas infrastructure,
gas power,
gas prepay,
health system,
hospitality,
independent living,
industrial development,
irrigation,
library,
local hfa multi-family housing,
local hfa single family housing,
local standalone multi-family housing,
local standalone single family housing,
military housing,
miscellaneous,
museum,
non-toll bridges,
non-toll roads,
nuclear power,
nursing home,
office buildings,
parking facilities,
parks,
police,
pollution control,
pre-school and daycare,
private college,
public buildings,
public college,
public housing,
public school district,
regional toll bridges,
regional toll roads,
sewer,
shopping centres,
solar power,
specialty hospital,
stadium,
standalone hospital,
standalone port,
standalone public school,
state hfa multi-family housing,
state hfa single family housing,
state toll bridges,
state toll roads,
storm water,
student housing,
student loan,
telephone,
trains,
tribal,
waste removal,
water,
wind power
​
values_updated_since
string<date>

Optional date filter to only return bonds whose reference data has been updated since the specified UTC date in ISO-8601 format (YYYY-MM-DD).

Response

Partial reference data

​
data
object[]
required

List of response data objects, often capped to 1000.

​
total
integer
required

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