You're building a finance feature that needs the Hong Kong Monetary Authority’s Base Rate inside your app—accurate, machine-readable, and ready for calculations. By the end of this guide, you’ll know exactly how to fetch HKMA_BASE from the Interest Rates API, interpret effective dates and units, stream it into your code with cURL/Python/JavaScript/PHP, analyze history and fluctuations, and compute spreads or loan metrics without guesswork—all using simple GET requests authenticated via api_key.
HKMA_BASE in practice: What it represents and how it’s expressed
HKMA_BASE is the HKMA Base Rate, a central bank policy benchmark for Hong Kong dollars (HKD). In the Interest Rates API, it is represented as a percentage per annum, not a decimal. For example, a value of 4.25 means a 4.25% annual rate.
Frequency: HKMA_BASE is monthly in the symbol catalogue, but downstream endpoints can surface daily records when decisions occur during the month or when the provider publishes effective-day granularity. Always rely on the dates field or time series keys to read the effective date of each observation—don’t assume calendar month-end or business-day schedules.
Effective dates: Each response that returns values also includes dates or date keys. Use those to tag your data warehouse entries and to align accrual windows. The API’s timestamps are ISO date strings (Y-m-d), and units are percentage points per annum.
All requests are GET and authenticated with the api_key query parameter. Base URL: https://interestratesapi.com/api/v1/
Documentation and platform resources: visit interestratesapi.com and the MCP.
Endpoint 1: Catalogue of symbols (/symbols)
Use the catalogue to confirm that HKMA_BASE exists and to discover other central bank or interbank benchmarks. You can filter by category, base currency, or provider.
cURL
curl -s "https://interestratesapi.com/api/v1/latest?api_key=YOUR_API_KEY&symbols=HKMA_BASE"
Sample JSON response
{
"success": true,
"date": "2026-10-31",
"base": "HKD",
"rates": {
"HKMA_BASE": 4.25
},
"dates": {
"HKMA_BASE": "2026-10-31"
},
"currencies": {
"HKMA_BASE": "HKD"
},
"base_filter_note": null
}
Field notes:
- symbol: canonical identifier (e.g., HKMA_BASE).
- frequency: expected publication cadence; treat as guidance for cache and ETL scheduling.
- description: short definition to display in your UI.
Python
import requests
resp = requests.get(
'https://interestratesapi.com/api/v1/symbols',
params=dict(category='central_bank', base='HKD', api_key='YOUR_KEY')
)
symbols = resp.json()
JavaScript (fetch)
const response = await fetch(
'https://interestratesapi.com/api/v1/symbols?category=central_bank&base=HKD&api_key=YOUR_KEY'
);
const data = await response.json();
PHP
<?php
$url = 'https://interestratesapi.com/api/v1/symbols?category=central_bank&base=HKD&api_key=YOUR_KEY';
$json = file_get_contents($url);
$data = json_decode($json, true);
?
Endpoint 2: Latest value (/latest) for HKMA_BASE
Fetch the current HKMA Base Rate. Use this for dashboards, pricing, and immediate calculations.
cURL (official sample)
JSON (official sample)
How to read it:
- rates.HKMA_BASE: 4.25 means 4.25% p.a. in HKD terms.
- dates.HKMA_BASE: effective date for the quoted value.
- date: response-wide as-of date; prefer the per-symbol dates map for symbol-level accuracy.
Python
import requests
response = requests.get(
'https://interestratesapi.com/api/v1/latest',
params=dict(symbols='HKMA_BASE', api_key='YOUR_KEY')
)
data = response.json()
hkma_rate = data['rates']['HKMA_BASE']
hkma_date = data['dates']['HKMA_BASE']
currency = data['currencies']['HKMA_BASE']
JavaScript (fetch)
const response = await fetch(
'https://interestratesapi.com/api/v1/latest?symbols=HKMA_BASE&api_key=YOUR_KEY'
);
const data = await response.json();
const rate = data.rates.HKMA_BASE;
const effectiveDate = data.dates.HKMA_BASE;
const currency = data.currencies.HKMA_BASE;
PHP
<?php
$url = 'https://interestratesapi.com/api/v1/latest?symbols=HKMA_BASE&api_key=YOUR_KEY';
$json = file_get_contents($url);
$data = json_decode($json, true);
$rate = $data['rates']['HKMA_BASE'];
$date = $data['dates']['HKMA_BASE'];
$ccy = $data['currencies']['HKMA_BASE'];
?
Endpoint 3: Historical value on a specific date (/historical)
Use historical to align the rate to an exact day. For monthly symbols, the API returns the last day with data within that month.
cURL
Sample JSON response
Field notes:
- date: the query anchor date.
- rates map: value for HKMA_BASE on or aligned to that date.
- For monthly series, plan your ETL to anchor to end-of-month or to the returned date’s effective alignment.
Python
import requests
params = dict(date='2025-06-15', symbols='HKMA_BASE', api_key='YOUR_KEY')
resp = requests.get('https://interestratesapi.com/api/v1/historical', params=params)
hist = resp.json()
value = hist['rates']['HKMA_BASE']
JavaScript (fetch)
const url = 'https://interestratesapi.com/api/v1/historical?date=2025-06-15&symbols=HKMA_BASE&api_key=YOUR_KEY';
const res = await fetch(url);
const hist = await res.json();
const value = hist.rates.HKMA_BASE;
PHP
<?php
$url = 'https://interestratesapi.com/api/v1/historical?date=2025-06-15&symbols=HKMA_BASE&api_key=YOUR_KEY';
$json = file_get_contents($url);
$hist = json_decode($json, true);
$value = $hist['rates']['HKMA_BASE'];
?
Endpoint 4: Time series between two dates (/timeseries)
Pull a continuous range for charting and quant analysis. The API returns a map of date-to-value pairs per symbol.
cURL
Sample JSON response
Field notes:
- rates.HKMA_BASE: object keyed by ISO dates.
- frequencies: actual cadence returned for the series in this query window.
- Use start_date and end_date for metadata and to validate stitched windows.
Python
import requests
params = dict(start='2025-11-18', end='2026-11-18', symbols='HKMA_BASE', api_key='YOUR_KEY')
resp = requests.get('https://interestratesapi.com/api/v1/timeseries', params=params)
ts = resp.json()
series = ts['rates']['HKMA_BASE'] # dict(date -> value)
JavaScript (fetch)
const res = await fetch(
'https://interestratesapi.com/api/v1/timeseries?start=2025-11-18&end=2026-11-18&symbols=HKMA_BASE&api_key=YOUR_KEY'
);
const ts = await res.json();
const series = ts.rates.HKMA_BASE; // { "YYYY-MM-DD": number }
PHP
<?php
$url = 'https://interestratesapi.com/api/v1/timeseries?start=2025-11-18&end=2026-11-18&symbols=HKMA_BASE&api_key=YOUR_KEY';
$json = file_get_contents($url);
$ts = json_decode($json, true);
$series = $ts['rates']['HKMA_BASE'];
?
Endpoint 5: Fluctuation statistics (/fluctuation)
Summarize how HKMA_BASE changed over a period—start, end, absolute change, percentage, and observed high/low.
cURL
Sample JSON response
Field notes:
- change_pct is null only when start_value is 0.
- high and low are observed extrema in the window—useful for guardrails in pricing engines.
Python
import requests
params = dict(start='2025-11-18', end='2026-11-18', symbols='HKMA_BASE', api_key='YOUR_KEY')
resp = requests.get('https://interestratesapi.com/api/v1/fluctuation', params=params)
fl = resp.json()['rates']['HKMA_BASE']
JavaScript (fetch)
const res = await fetch(
'https://interestratesapi.com/api/v1/fluctuation?start=2025-11-18&end=2026-11-18&symbols=HKMA_BASE&api_key=YOUR_KEY'
);
const data = await res.json();
const stats = data.rates.HKMA_BASE;
PHP
<?php
$url = 'https://interestratesapi.com/api/v1/fluctuation?start=2025-11-18&end=2026-11-18&symbols=HKMA_BASE&api_key=YOUR_KEY';
$json = file_get_contents($url);
$data = json_decode($json, true);
$stats = $data['rates']['HKMA_BASE'];
?
Endpoint 6: OHLC candlesticks (/ohlc)
Build charts using open-high-low-close aggregates over monthly, weekly, or quarterly periods. OHLC is computed on-the-fly from the daily data in the requested window.
cURL
Sample JSON response
Field notes:
- period: aggregation interval used in the calculation (default monthly).
- data_points: number of daily observations used to compute OHLC for that period.
Python
import requests
params = dict(symbols='HKMA_BASE', period='monthly', start='2025-11-18', end='2026-11-18', api_key='YOUR_KEY')
resp = requests.get('https://interestratesapi.com/api/v1/ohlc', params=params)
ohlc = resp.json()['rates']['HKMA_BASE']
JavaScript (fetch)
const res = await fetch(
'https://interestratesapi.com/api/v1/ohlc?symbols=HKMA_BASE&period=monthly&start=2025-11-18&end=2026-11-18&api_key=YOUR_KEY'
);
const data = await res.json();
const candles = data.rates.HKMA_BASE;
PHP
<?php
$url = 'https://interestratesapi.com/api/v1/ohlc?symbols=HKMA_BASE&period=monthly&start=2025-11-18&end=2026-11-18&api_key=YOUR_KEY';
$json = file_get_contents($url);
$data = json_decode($json, true);
$candles = $data['rates']['HKMA_BASE'];
?
Endpoint 7: Compare loan interest cost between rates (/convert)
Use convert to compare the simple interest cost of a loan priced off two different benchmarks using their latest values. This is useful to quantify spreads in monetary terms.
cURL
Sample JSON response
Field notes:
- amount and term_months: input principal and tenor for a simple loan.
- rate_spread: difference between the two latest rates in percentage points.
- total_interest: simple interest calculation based on the latest rate; use this to translate basis points into currency impact.
Python
import requests
params = dict(from='HKMA_BASE', to='ECB_MRO', amount=100000, term_months=12, api_key='YOUR_KEY')
resp = requests.get('https://interestratesapi.com/api/v1/convert', params=params)
cmp = resp.json()
spread = cmp['difference']['rate_spread']
JavaScript (fetch)
const res = await fetch(
'https://interestratesapi.com/api/v1/convert?from=HKMA_BASE&to=ECB_MRO&amount=100000&term_months=12&api_key=YOUR_KEY'
);
const cmp = await res.json();
const spread = cmp.difference.rate_spread;
PHP
<?php
$url = 'https://interestratesapi.com/api/v1/convert?from=HKMA_BASE&to=ECB_MRO&amount=100000&term_months=12&api_key=YOUR_KEY';
$json = file_get_contents($url);
$cmp = json_decode($json, true);
$spread = $cmp['difference']['rate_spread'];
?>
How to interpret units, effective dates, and business days
Units: All rates are percentages per annum. Multiply by 0.01 to convert to a decimal for calculations. For a rough monthly accrual, divide the annual decimal by 12. The convert endpoint already handles simple interest math for you.
Effective dates: Always prefer dates.HKMA_BASE (from /latest) or the date keys returned by /timeseries. If you need month-end alignment for reporting, use /historical with a month-end date or apply your own month-close logic on the time series.
Business days: Policy rates can change on scheduled decision days or on ad hoc announcements. Time series may include only those days with changes. When you need a value for a non-business day, use the most recent available value prior to that date (backfill/last observation carried forward) or use /historical to anchor.
Caching and scheduling strategies
HKMA_BASE updates are relatively infrequent compared to interbank overnight benchmarks. Suitable caching approaches:
- Latest endpoint: cache for a day; invalidate on known decision windows if needed.
- Time series: cache immutable past periods; refresh the most recent month more frequently.
- Fluctuation and OHLC: cache by parameter tuple; recalc only when input windows or underlying latest data change.
Respect rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) and implement backoff if you receive 429 with Retry-After. For ETL, schedule daily pulls and add ad hoc refresh jobs when you detect a new effective date via /latest.
How to compute spreads and monthly payments from returned values
Spread: Given two rates r1 and r2 from the API (in percentage points p.a.), spread = r1 − r2 (also in percentage points). To annualize the cost difference on a principal amount A using simple interest approximation: delta_cost = A × spread/100. For a monthly view: delta_cost_month = A × (spread/100)/12.
Monthly payment (amortized loan): Using a benchmark rate r (percentage per annum) and adding your product margin m (percentage points), set annual_rate = (r + m)/100. Then monthly_rate = annual_rate/12. For principal P and term n months, payment = P × monthly_rate × (1 + monthly_rate)^n / ((1 + monthly_rate)^n − 1). If your product uses interest-only or simple interest, adapt accordingly; the Interest Rates API’s /convert endpoint demonstrates simple interest totals.
Currency: HKMA_BASE is quoted for HKD. Your payment currency may differ; convert currencies externally before combining with billing calculations if required.
Error handling patterns and common responses
All error responses share the shape success=false with error=message and sometimes details. Typical cases:
- 401: missing or invalid api_key.
- 403: account without an active plan.
- 404: no symbols matched or no data for the requested date/range.
- 422: validation error (e.g., invalid date format or symbol).
- 429: request quota exhausted—use Retry-After and X-RateLimit-* to back off.
Add guardrails: check success before reading fields, and verify a symbol key exists in rates or dates maps. Log details where provided to aid debugging.
Building production integrations with HKMA_BASE
Use cases that benefit directly from HKMA_BASE:
- Interest rate dashboards: show HKMA_BASE next to interbank rates like SOFR or ESTR. For daily overviews, use /latest; for trend charts, use /timeseries and /ohlc.
- Lending and mortgage pricing: compute spreads to your product’s margin; use /convert to translate the spread into total interest cost.
- Macro research and risk models: pull long-date windows via /timeseries and quantify regime shifts with /fluctuation.
- Treasury and ALM: snapshot HKMA_BASE each close for transfer pricing and internal benchmarking.
Reference and onboarding: interestratesapi.com, and the MCP provide the base URL and endpoint descriptions.
End-to-end example workflow for HKMA_BASE
1) Discover symbol metadata
Call /symbols to confirm central bank listings and frequencies. Cache metadata weekly.
2) Fetch the latest rate for your UI
Use /latest with symbols=HKMA_BASE. Store rates and effective dates; re-render your UI when the date changes.
3) Backfill time series
Use /timeseries to populate charts and to compute moving averages or vol buckets. For reporting, aggregate with /ohlc.
4) Communicate changes
Use /fluctuation to summarize the magnitude and direction of changes in your change logs or emails.
5) Quantify price impact
Use /convert to translate a spread vs. another policy rate into expected interest differences on a sample principal and tenor.
Operational notes and tips
- Idempotency: All endpoints are GET; cache responses by full URL, including query string.
- Pagination: The API segments by date ranges rather than pages. For very long histories, request windows by year or quarter.
- Precision: Values are decimal numbers; store as decimal (not float) if your stack supports it to avoid rounding drift in downstream totals.
- Data hygiene: Always read currency from currencies.HKMA_BASE and effective date from dates.HKMA_BASE or from the series keys.
FAQ
Q1: What unit is HKMA_BASE in, and is it annualized?
A: The API returns HKMA_BASE in percentage points per annum (e.g., 4.25 means 4.25% per year). Convert to decimals by dividing by 100.
Q2: Which date should I store for each observation?
A: Store dates.HKMA_BASE from /latest and the ISO date keys from /timeseries. For monthly reporting, use /historical with a month-end date or your preferred business day convention.
Q3: How often should I poll HKMA_BASE?
A: Policy rates change infrequently; polling once daily with cache is typical. Add an on-demand refresh triggered by a change in dates.HKMA_BASE.
Q4: How do I compute a payment using HKMA_BASE?
A: Convert the percentage to a monthly rate (r/100/12), add your product margin if applicable, and apply your loan formula (amortized, interest-only, or simple). The /convert endpoint demonstrates simple interest totals.
Q5: What if I get a 404 for a date range?
A: It means no data exists for that period or symbol. Check details (if present) for available ranges, or reduce your window to known coverage.
Ready to integrate HKMA_BASE into your pricing or analytics stack? Use the base URL https://interestratesapi.com/api/v1/ and authenticate with the api_key query parameter. Start now: Register. For reference materials and endpoint behavior, see the MCP. Also explore interestratesapi.com for platform updates and resources.