US 30-Year Mortgage Convert API - InterestRatesAPI Blog

Your team needs a reliable way to fetch and compare the US 30-year fixed mortgage benchmark directly inside your product, compute spreads against other policy rates, and turn those values into loan costs and payments. By the end of this guide you will integrate the MORTGAGE_30Y symbol from the Interest Rates API into dashboards, pricing engines, and research pipelines, and you will be able to query latest, historical, time series, fluctuation, OHLC, and the convert endpoint to compare loan interest costs between benchmarks.

What the MORTGAGE_30Y benchmark represents

MORTGAGE_30Y is the Freddie Mac 30-Year Fixed Mortgage Rate (reference, USD, weekly). It is a widely followed reference for US mortgage pricing and a key input for consumer finance, risk analytics, and housing market research. In the Interest Rates API:

Illustration: US 30-Year Mortgage Convert API

Symbol: MORTGAGE_30Y
Category: reference
Currency: USD
Publication cadence: weekly (the API may present daily time stamps where the weekly value is carried forward until the next publication)
Unit: percent per annum (e.g., 5.33 means 5.33% annual rate)

All endpoints are served from https://interestratesapi.com/api/v1/ and authenticated with the api_key query parameter. All requests are HTTP GET. See interestratesapi.com for more details and Register to obtain an API key.

How to interpret values and dates

Rates are expressed in percent per annum. For example, a response of 5.33 is 5.33% annualized. Effective dates vary by series:

Latest endpoint includes a date (top-level) and a dates map per symbol. Use dates[symbol] to pin the effective date for each rate returned.
Historical endpoint resolves to the last known observation on or before the requested date for frequencies such as weekly or monthly.
Time series may present a daily index even for weekly series; in that case, the value is stable until the next release date.

When you compute monthly payments or spreads, convert the annual rate to a periodic rate consistent with your term (e.g., monthly_rate = annual_rate / 12 for simple approximations). For exact amortization, use the standard annuity formula with the periodic rate.

Endpoint 1: Catalogue of available symbols

Use this endpoint to discover symbols and metadata. Filter by category, base currency, or provider. For MORTGAGE_30Y, you will typically filter by category=reference and base=USD.

cURL

curl -s "https://interestratesapi.com/api/v1/latest?api_key=YOUR_API_KEY&symbols=SOFR"

Python (requests)

import requests

resp = requests.get(
"https://interestratesapi.com/api/v1/symbols",
params=dict(category="reference", base="USD", api_key="YOUR_API_KEY")
)
data = resp.json()
# Find the MORTGAGE_30Y entry
mortgage_30y = next((s for s in data.get("symbols", []) if s.get("symbol") == "MORTGAGE_30Y"), None)

JavaScript (fetch)

const res = await fetch(
"https://interestratesapi.com/api/v1/symbols?category=reference&base=USD&api_key=YOUR_API_KEY"
);
const data = await res.json();
const mortgage30y = (data.symbols || []).find(s => s.symbol === "MORTGAGE_30Y");

PHP

<?php
$url = "https://interestratesapi.com/api/v1/symbols?category=reference&base=USD&api_key=YOUR_API_KEY";
$json = file_get_contents($url);
$data = json_decode($json, true);
$mortgage30y = null;
if (isset($data["symbols"])) {
foreach ($data["symbols"] as $s) {
if ($s["symbol"] === "MORTGAGE_30Y") { $mortgage30y = $s; break; }
}
}
?>

Example response shape (illustrative from documentation):

{
"success": true,
"date": "2026-10-02",
"base": "USD",
"rates": {
"SOFR": 3.88
},
"dates": {
"SOFR": "2026-10-02"
},
"currencies": {
"SOFR": "USD"
},
"base_filter_note": null
}

Use fields like symbol, category, frequency, and description to build selection lists and to document rate provenance. For MORTGAGE_30Y, expect category=reference and frequency=weekly.

Endpoint 2: Latest value per symbol (MORTGAGE_30Y)

Fetch the most recent published value. For dashboards and nightly jobs, cache this result until the symbol’s expected publication cadence (weekly) or until your update cycle.

cURL

Python

import requests

resp = requests.get(
"https://interestratesapi.com/api/v1/latest",
params=dict(symbols="MORTGAGE_30Y", api_key="YOUR_API_KEY")
)
data = resp.json()
rate = data["rates"]["MORTGAGE_30Y"]
effective_date = data["dates"]["MORTGAGE_30Y"]
currency = data["currencies"]["MORTGAGE_30Y"]

JavaScript

const response = await fetch(
"https://interestratesapi.com/api/v1/latest?symbols=MORTGAGE_30Y&api_key=YOUR_API_KEY"
);
const data = await response.json();
const rate = data.rates["MORTGAGE_30Y"];
const effectiveDate = data.dates["MORTGAGE_30Y"];
const currency = data.currencies["MORTGAGE_30Y"];

PHP

<?php
$url = "https://interestratesapi.com/api/v1/latest?symbols=MORTGAGE_30Y&api_key=YOUR_API_KEY";
$json = file_get_contents($url);
$data = json_decode($json, true);
$rate = $data["rates"]["MORTGAGE_30Y"];
$effectiveDate = $data["dates"]["MORTGAGE_30Y"];
$currency = $data["currencies"]["MORTGAGE_30Y"];
?>

Official example with a different symbol (SOFR) that you can copy-paste to verify connectivity:

Key fields:

rates map: symbol to latest rate (percent per annum)
dates map: symbol to effective date of the last observation
currencies map: symbol to ISO currency

Endpoint 3: Historical value on a specific date

Request the value on a given date (Y-m-d). For weekly series like MORTGAGE_30Y, the API will give the latest available observation on or before that date in the requested period.

cURL

Python

import requests

params = dict(date="2025-06-15", symbols="MORTGAGE_30Y", api_key="YOUR_API_KEY")
data = requests.get("https://interestratesapi.com/api/v1/historical", params=params).json()
hist_rate = data["rates"]["MORTGAGE_30Y"]
hist_ccy = data["currencies"]["MORTGAGE_30Y"]

JavaScript

const url = "https://interestratesapi.com/api/v1/historical?date=2025-06-15&symbols=MORTGAGE_30Y&api_key=YOUR_API_KEY";
const hist = await fetch(url).then(r => r.json());
const value = hist.rates["MORTGAGE_30Y"];
const ccy = hist.currencies["MORTGAGE_30Y"];

PHP

<?php
$url = "https://interestratesapi.com/api/v1/historical?date=2025-06-15&symbols=MORTGAGE_30Y&api_key=YOUR_API_KEY";
$data = json_decode(file_get_contents($url), true);
$value = $data["rates"]["MORTGAGE_30Y"];
$ccy = $data["currencies"]["MORTGAGE_30Y"];
?>

Example JSON (from documentation):

Note: The returned date reflects your request; for weekly series, the underlying data point corresponds to the most recent publication on or before that date.

Endpoint 4: Time series between two dates

Use the time series endpoint for charting, backtesting, and analytics. For weekly series, the API may return a daily index with repeated values until the next observation. The frequencies map helps you understand the reporting cadence per symbol.

cURL

Python

import requests

params = dict(start="2025-10-06", end="2026-10-06", symbols="MORTGAGE_30Y", api_key="YOUR_API_KEY")
series = requests.get("https://interestratesapi.com/api/v1/timeseries", params=params).json()
points = series["rates"]["MORTGAGE_30Y"] # dict of date -> value
freq = series["frequencies"]["MORTGAGE_30Y"]

JavaScript

const tsUrl = "https://interestratesapi.com/api/v1/timeseries?start=2025-10-06&end=2026-10-06&symbols=MORTGAGE_30Y&api_key=YOUR_API_KEY";
const ts = await fetch(tsUrl).then(r => r.json());
const points = ts.rates["MORTGAGE_30Y"];
const freq = ts.frequencies["MORTGAGE_30Y"];

PHP

<?php
$tsUrl = "https://interestratesapi.com/api/v1/timeseries?start=2025-10-06&end=2026-10-06&symbols=MORTGAGE_30Y&api_key=YOUR_API_KEY";
$ts = json_decode(file_get_contents($tsUrl), true);
$points = $ts["rates"]["MORTGAGE_30Y"];
$freq = $ts["frequencies"]["MORTGAGE_30Y"];
?>

Example JSON (from documentation):

Key fields:

rates[symbol]: map of ISO date to rate (percent)
frequencies[symbol]: reported frequency for interpretation
currencies[symbol]: currency code

Endpoint 5: Fluctuation (change statistics)

Summarize changes between two dates, including high/low, absolute change, and percent change. This is useful for alerting and performance summaries in mortgage analytics.

cURL

Python

import requests

params = dict(start="2025-10-06", end="2026-10-06", symbols="MORTGAGE_30Y", api_key="YOUR_API_KEY")
fluc = requests.get("https://interestratesapi.com/api/v1/fluctuation", params=params).json()
stats = fluc["rates"]["MORTGAGE_30Y"]
# stats has: start_date, end_date, start_value, end_value, change, change_pct, high, low

JavaScript

const fUrl = "https://interestratesapi.com/api/v1/fluctuation?start=2025-10-06&end=2026-10-06&symbols=MORTGAGE_30Y&api_key=YOUR_API_KEY";
const fluc = await fetch(fUrl).then(r => r.json());
const stats = fluc.rates["MORTGAGE_30Y"];

PHP

<?php
$fUrl = "https://interestratesapi.com/api/v1/fluctuation?start=2025-10-06&end=2026-10-06&symbols=MORTGAGE_30Y&api_key=YOUR_API_KEY";
$fluc = json_decode(file_get_contents($fUrl), true);
$stats = $fluc["rates"]["MORTGAGE_30Y"];
?>

Example JSON (from documentation):

Interpretation:

change: arithmetic difference end_value − start_value
change_pct: (change / start_value) × 100 (null if start_value is 0)
high/low: extremes within the window

Endpoint 6: OHLC candlestick data

Compute open, high, low, close for a period (weekly, monthly, quarterly) over a date range. Useful for charting and regime detection in mortgage rate dashboards.

cURL

Python

import requests

params = dict(symbols="MORTGAGE_30Y", period="monthly", start="2025-10-06", end="2026-10-06", api_key="YOUR_API_KEY")
ohlc = requests.get("https://interestratesapi.com/api/v1/ohlc", params=params).json()
candles = ohlc["rates"]["MORTGAGE_30Y"] # list of dicts with period, open, high, low, close, data_points

JavaScript

const ohlcUrl = "https://interestratesapi.com/api/v1/ohlc?symbols=MORTGAGE_30Y&period=monthly&start=2025-10-06&end=2026-10-06&api_key=YOUR_API_KEY";
const ohlc = await fetch(ohlcUrl).then(r => r.json());
const candles = ohlc.rates["MORTGAGE_30Y"];

PHP

<?php
$ohlcUrl = "https://interestratesapi.com/api/v1/ohlc?symbols=MORTGAGE_30Y&period=monthly&start=2025-10-06&end=2026-10-06&api_key=YOUR_API_KEY";
$ohlc = json_decode(file_get_contents($ohlcUrl), true);
$candles = $ohlc["rates"]["MORTGAGE_30Y"];
?>

Example JSON (from documentation):

data_points indicates the number of underlying daily observations used to compute that candle. OHLC is derived from daily series; there is no separate storage for OHLC.

Endpoint 7: Convert — loan interest cost comparison

This endpoint compares the total interest cost of a simple loan priced at the latest rate of two symbols over a term. It is ideal for showing how a 30-year mortgage benchmark (MORTGAGE_30Y) differs from a policy rate or interbank rate for the same principal and term, e.g., to visualize potential savings.

cURL

Python

import requests

params = dict(from="MORTGAGE_30Y", to="ECB_MRO", amount=100000, term_months=12, api_key="YOUR_API_KEY")
conv = requests.get("https://interestratesapi.com/api/v1/convert", params=params).json()
from_leg = conv["from"]
to_leg = conv["to"]
spread = conv["difference"]["rate_spread"]
interest_saved = conv["difference"]["interest_saved"]

JavaScript

const cUrl = "https://interestratesapi.com/api/v1/convert?from=MORTGAGE_30Y&to=ECB_MRO&amount=100000&term_months=12&api_key=YOUR_API_KEY";
const conv = await fetch(cUrl).then(r => r.json());
const fromLeg = conv.from;
const toLeg = conv.to;
const spread = conv.difference.rate_spread;
const saved = conv.difference.interest_saved;

PHP

<?php
$cUrl = "https://interestratesapi.com/api/v1/convert?from=MORTGAGE_30Y&to=ECB_MRO&amount=100000&term_months=12&api_key=YOUR_API_KEY";
$conv = json_decode(file_get_contents($cUrl), true);
$fromLeg = $conv["from"];
$toLeg = $conv["to"];
$spread = $conv["difference"]["rate_spread"];
$saved = $conv["difference"]["interest_saved"];
?>

Example JSON (from documentation):

Interpretation:

from/to.rate: latest rate for each symbol (percent p.a.)
total_interest: simple interest over the term_months (API-defined comparison, not an amortizing schedule)
rate_spread: from.rate − to.rate (percent points)
interest_saved: difference in total interest between the two legs for the chosen amount and term

Reading effective dates, business days, and caching

Publication frequency for MORTGAGE_30Y is weekly. The dates map in latest ensures you know the effective observation date. Weekly publications may not align to every business day; in your UI or backtests, carry the last known value forward between publication dates.

Recommended caching patterns:

Latest: cache for the symbol’s cadence (weekly) or until you detect a change in dates[symbol].
Time series: cache per day range; refresh when your window moves or after new publications.
Fluctuation and OHLC: derive from existing cached time series if you can, to minimize calls.

Handle error codes and rate limits. 401/403 indicate auth/plan issues. 404 may return details about available ranges. 422 is validation. 429 includes Retry-After and X-RateLimit-* headers to coordinate retries.

Using values to compute spreads and payments

Spreads: if x is MORTGAGE_30Y and y is another symbol, spread = x − y. Use latest or aligned historical dates for apples-to-apples comparisons.

Monthly payment (amortizing) from an annual percentage rate r% over n months and principal P:

Convert to a decimal periodic rate i = (r / 100) / 12
Payment = P × [i × (1 + i)^n] / [(1 + i)^n − 1]

Example (code outline, no hard-coded numbers):

Python amortization snippet

def amortized_payment(principal, annual_rate_pct, months):
i = (annual_rate_pct / 100.0) / 12.0
if i == 0:
return principal / months
return principal * (i * (1 + i)**months) / ((1 + i)**months - 1)

# Plug in MORTGAGE_30Y latest rate from the API:
# payment = amortized_payment(loan_amount, rate, term_months)

JavaScript amortization snippet

function amortizedPayment(principal, annualRatePct, months) {
const i = (annualRatePct / 100) / 12;
if (i === 0) return principal / months;
return principal * (i * Math.pow(1 + i, months)) / (Math.pow(1 + i, months) - 1);
}

// payment = amortizedPayment(amount, latestRate, termMonths);

For simple interest comparisons (not amortizing), the /convert endpoint already computes total_interest and total_payment using the API’s consistent method.

End-to-end example: building a mortgage benchmark panel

Typical components for a mortgage dashboard or pricing engine:

Discovery: GET /symbols to list reference rates; pick MORTGAGE_30Y
Live card: GET /latest for MORTGAGE_30Y (show current rate and effective date)
Chart: GET /timeseries for the last 2–5 years
Performance: GET /fluctuation for YTD or rolling 12M
Candles: GET /ohlc monthly for a clean visual of regime changes
Comparisons: GET /convert to show interest cost differences vs policy rates (e.g., ECB_MRO) or interbank benchmarks

Keep an eye on 404 responses for ranges and 429 headers for pacing. Cache results according to your update cadence. All calls are GET with api_key in the query string. See MCP for model and capability references and interestratesapi.com for API overview.

Error handling and reliability

Standard error payloads look like success=false and include an error message, optionally a details field for 404. Use HTTP status codes to branch logic:

401/403: recheck api_key and ensure permissions
404: handle no data for the date/range; adjust or inform the user
422: validate inputs (date format Y-m-d; known symbols only)
429: back off using Retry-After and respect X-RateLimit-Reset

Use idempotent GETs and cache keys built from the full URL (including parameters). Time series and OHLC requests are deterministic given the same parameters.

Additional examples using official endpoint samples

The latest endpoint supports many symbols, including interbank rates like SOFR. You can test connectivity with the official sample below, then swap in MORTGAGE_30Y in your integration:

Once validated, use the same path and parameters with symbols=MORTGAGE_30Y. For broader discovery and setup, consult the MCP and Register links.

Use cases with MORTGAGE_30Y

Mortgage origination apps: display the current 30-year benchmark and compute borrower payments with amortization.
Treasury analytics: compare MORTGAGE_30Y to central bank policy rates using /convert to quantify interest cost differences.
Macro research: time series, fluctuation, and OHLC to identify turning points in housing finance cycles.
Risk monitoring: alert when change_pct breaches thresholds over rolling windows.

Get an API key to start building: Register for Interest Rates API. Explore the model catalog: Interest Rates API MCP. When you are ready to integrate, Get started with Interest Rates API.

FAQ

How often is MORTGAGE_30Y updated?
It is a weekly reference rate. The API may present values on a daily index with the last observation carried forward until the next publication. Use the dates map to identify the effective date.

What units are returned?
Percent per annum. For example, 5.33 means 5.33% annualized. Convert to periodic rates (e.g., monthly) when computing amortizing payments.

How should I cache results?
Cache /latest for the symbol’s cadence (weekly). Cache /timeseries and /ohlc by date window. On 429 responses, respect Retry-After and X-RateLimit-* headers.

How do I handle missing data on a requested historical date?
For weekly or monthly series, the API returns the last known observation on or before the requested date. If no data exists, you will receive a 404; adjust your window or inform users.

Can I compare MORTGAGE_30Y to a policy rate directly?
Yes. Use /convert with from=MORTGAGE_30Y and to=your policy rate symbol (e.g., ECB_MRO) to compute rate_spread and interest_saved for a given amount and term.

Ship your mortgage analytics faster. Start integrating MORTGAGE_30Y in minutes with the Interest Rates API. Register now, explore the MCP, and build with the endpoints above.

What the MORTGAGE_30Y benchmark represents

How to interpret values and dates

Endpoint 1: Catalogue of available symbols

cURL

Python (requests)

JavaScript (fetch)

PHP

Endpoint 2: Latest value per symbol (MORTGAGE_30Y)

cURL

Python

JavaScript

PHP

Endpoint 3: Historical value on a specific date

cURL

Python

JavaScript

PHP

Endpoint 4: Time series between two dates

cURL

Python

JavaScript

PHP

Endpoint 5: Fluctuation (change statistics)

cURL

Python

JavaScript

PHP

Endpoint 6: OHLC candlestick data

cURL

Python

JavaScript

PHP

Endpoint 7: Convert — loan interest cost comparison

cURL

Python

JavaScript

PHP

Reading effective dates, business days, and caching

Using values to compute spreads and payments

Python amortization snippet

JavaScript amortization snippet

End-to-end example: building a mortgage benchmark panel

Error handling and reliability

Additional examples using official endpoint samples

Use cases with MORTGAGE_30Y

FAQ

Ready to get started?

Related posts