You need clean, dependable access to Portugal’s government bond yields to power analytics, dashboards, and trading or risk tools. By the end of this article, you will know how to fetch the latest Portuguese yields, query specific historical dates, pull time series, compute spreads, and build a full PT yield curve using the Bonds API endpoints—then ship that data into your own applications with cURL, Python, JavaScript, or PHP.
Scope, units, and how to read Portuguese sovereign yields
Bonds-API provides sovereign bond yields as JSON over HTTPS, covering Portugal (ISO2: PT) across a range of standard maturities (from bills such as 1M to long bonds such as 30Y, depending on availability). A “yield” value is expressed in percentage points (for example, 4.52 represents a 4.52% yield). Spreads, when returned in basis points, are denoted as integers (for example, 215 means 2.15%). Dates are given as Y-m-d (e.g., 2026-10-30), and timestamps are ISO 8601 in UTC where present.
On business days, updates reflect the latest available session. You should expect weekends and national market holidays to have no new daily data. For production systems, implement short-lived caching (for example, 30–60 seconds on intraday endpoints and 5–10 minutes on daily endpoints) and fallback handling for non-trading days. Visit bonds-api.com for product details, and see the Bonds API MCP to explore methods interactively.
Base URL, authentication, and request method
All endpoints use HTTPS GET at: https://bonds-api.com/api/v1/. Authenticate using an API key via the X-API-Key header. Example header: X-API-Key: YOUR_API_KEY. Each request is idempotent and safe to retry with exponential backoff. For systematic jobs, combine HTTP caching headers with application-level caching.
Get an API key and start integrating: Register for Bonds API, Get started with Bonds API, or jump to the Bonds API MCP. You can also use the UTM-tagged links here: Register and MCP.
Official sample blocks (verbatim)
The following sample request and response block is provided verbatim from the official documentation:
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"
{
"success": true,
"date": "2026-10-30",
"rates": {
"US_10Y": 4.928
},
"dates": {
"US_10Y": "2026-10-30"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "a8bd7318-3c83-4c56-bc94-b0afaba33e63",
"timestamp": "2026-10-30T00:04:05+00:00"
}
}
In this article, we focus on Portugal (PT) and use the PT-specific endpoints and schemas below.
Latest Portuguese yields: /api/v1/latest
Use this endpoint for current yields across one or many maturities. You can specify Portugal using ISO2 PT and select the maturities to build a quick snapshot or a yield curve input. If maturities are omitted, the API returns all available for that country.
cURL
JSON response
Fields:
- success: Boolean request status.
- data: Country code map. For PT, maturities like 2Y and 10Y appear with:
- yield: Percentage (e.g., 4.52 means 4.52%).
- date: Trading date in Y-m-d (UTC day with official data).
- source: Data provenance (e.g., “official”).
Python (requests)
import requests
resp = requests.get(
'https://bonds-api.com/api/v1/latest',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'countries': 'PT', 'maturities': '2Y,10Y'}
)
data = resp.json()
pt_2y = data['data']['PT']['2Y']['yield']
pt_10y = data['data']['PT']['10Y']['yield']
print('PT 2Y:', pt_2y, 'PT 10Y:', pt_10y)
JavaScript (fetch)
const url = new URL('https://bonds-api.com/api/v1/latest');
url.searchParams.set('countries', 'PT');
url.searchParams.set('maturities', '2Y,10Y');
fetch(url.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
.then(r => r.json())
.then(json => {
const pt2y = json.data.PT['2Y'].yield;
const pt10y = json.data.PT['10Y'].yield;
console.log('PT 2Y', pt2y, 'PT 10Y', pt10y);
});
PHP (file_get_contents)
<?php
$context = stream_context_create([
'http' => [
'method' => 'GET',
'header' => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = 'https://bonds-api.com/api/v1/latest?countries=PT&maturities=2Y,10Y';
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
echo 'PT 10Y: ' . $data['data']['PT']['10Y']['yield'];
Yield on a specific date: /api/v1/historical
Fetch a single country-maturity observation for a target date. This is useful for point-in-time backtesting, event studies, and reproducible research artifacts.
cURL
JSON response
Fields:
- country, maturity: The requested identifiers.
- date: Y-m-d.
- yield: Percentage value.
- source: Data source tag, e.g., “official”.
Python (requests)
import requests
params = {'country': 'PT', 'maturity': '10Y', 'date': '2025-06-15'}
resp = requests.get('https://bonds-api.com/api/v1/historical',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params)
pt10y_hist = resp.json()
print(pt10y_hist['yield'])
JavaScript (fetch)
const url = new URL('https://bonds-api.com/api/v1/historical');
url.searchParams.set('country', 'PT');
url.searchParams.set('maturity', '10Y');
url.searchParams.set('date', '2025-06-15');
fetch(url, { headers: { 'X-API-Key': 'YOUR_API_KEY' }})
.then(r => r.json())
.then(json => console.log(json.yield));
PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => [
'method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"
]]);
$u = 'https://bonds-api.com/api/v1/historical?country=PT&maturity=10Y&date=2025-06-15';
$data = json_decode(file_get_contents($u, false, $ctx), true);
echo $data['yield'];
Time series for Portugal: /api/v1/timeseries
Pull a continuous series to chart PT yields, compute rolling stats, or train models. Choose a maturity and supply a start and end date.
cURL
JSON response
Fields:
- series: List of date-yield objects with daily observations (business days only; no weekends/holidays).
Python (requests)
import requests, statistics
p = {'country': 'PT', 'maturity': '10Y', 'start': '2025-10-30', 'end': '2026-10-30'}
r = requests.get('https://bonds-api.com/api/v1/timeseries',
headers={'X-API-Key': 'YOUR_API_KEY'}, params=p)
ts = r.json()['series']
yields = [pt['yield'] for pt in ts]
print('Count:', len(yields), 'Mean:', statistics.mean(yields))
JavaScript (fetch)
const u = new URL('https://bonds-api.com/api/v1/timeseries');
u.searchParams.set('country', 'PT');
u.searchParams.set('maturity', '10Y');
u.searchParams.set('start', '2025-10-30');
u.searchParams.set('end', '2026-10-30');
fetch(u, { headers: { 'X-API-Key': 'YOUR_API_KEY' }})
.then(r => r.json())
.then(json => {
const dates = json.series.map(p => p.date);
const vals = json.series.map(p => p.yield);
console.log('First:', dates[0], vals[0]);
});
PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => [
'method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"
]]);
$q = http_build_query([
'country' => 'PT', 'maturity' => '10Y',
'start' => '2025-10-30', 'end' => '2026-10-30'
]);
$json = file_get_contents("https://bonds-api.com/api/v1/timeseries?$q", false, $ctx);
$data = json_decode($json, true);
echo count($data['series']);
Spread vs benchmark: /api/v1/spread
Compute the PT spread against a benchmark sovereign, such as German Bunds (DE) or US Treasuries (US). Spreads are returned in basis points (bps), simplifying portfolio and relative value analysis.
cURL
JSON response
Fields:
- spread_bps: Integer basis points (215 bps = 2.15%).
- country_yield, benchmark_yield: Percent yields for PT and the benchmark.
Python (requests)
import requests
p = {'country': 'PT', 'benchmark': 'US', 'maturity': '10Y'}
r = requests.get('https://bonds-api.com/api/v1/spread',
headers={'X-API-Key': 'YOUR_API_KEY'}, params=p)
s = r.json()
print('PT vs US 10Y spread (bps):', s['spread_bps'])
JavaScript (fetch)
const sp = new URL('https://bonds-api.com/api/v1/spread');
sp.searchParams.set('country', 'PT');
sp.searchParams.set('benchmark', 'US');
sp.searchParams.set('maturity', '10Y');
fetch(sp, { headers: { 'X-API-Key': 'YOUR_API_KEY' }})
.then(r => r.json())
.then(j => console.log('Spread bps:', j.spread_bps));
PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => [
'method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"
]]);
$url = 'https://bonds-api.com/api/v1/spread?country=PT&benchmark=US&maturity=10Y';
$resp = json_decode(file_get_contents($url, false, $ctx), true);
echo $resp['spread_bps'];
Full PT yield curve: /api/v1/curve
Request the entire Portuguese curve for a specific date (or the latest if no date is provided). This is ideal for curve visualization, bootstrapping, and scenario analyses.
cURL
JSON response
Fields:
- date: Y-m-d for the curve snapshot.
- inverted: Boolean flag indicating whether shorter maturities exceed longer ones.
- curve: Maturity-to-yield map; yields are percentages.
Python (requests)
import requests
r = requests.get('https://bonds-api.com/api/v1/curve',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'PT'})
curve = r.json()
tenor_order = ['1M','3M','6M','1Y','2Y','5Y','10Y','30Y']
points = [(t, curve['curve'].get(t)) for t in tenor_order if t in curve['curve']]
for t, y in points:
print(t, y)
JavaScript (fetch)
const cu = new URL('https://bonds-api.com/api/v1/curve');
cu.searchParams.set('country', 'PT');
fetch(cu, { headers: { 'X-API-Key': 'YOUR_API_KEY' }})
.then(r => r.json())
.then(j => {
console.log('Date:', j.date, 'Inverted:', j.inverted);
Object.entries(j.curve).forEach(([tenor, y]) => console.log(tenor, y));
});
PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => [
'method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"
]]);
$resp = json_decode(file_get_contents('https://bonds-api.com/api/v1/curve?country=PT', false, $ctx), true);
foreach ($resp['curve'] as $tenor => $y) {
echo $tenor . ': ' . $y . PHP_EOL;
}
Intraday snapshots for PT: /api/v1/intraday
For intraday monitoring, request snapshots at multiple timestamps within a single UTC date. This is useful for monitoring risk and P&L during Europe trading hours. The response includes fetched_at timestamps in UTC and a meta.timezone field to confirm the timezone basis.
cURL
JSON response
Fields:
- snapshots: List of intraday observations. fetched_at is ISO 8601 UTC.
- count: Number of snapshots returned.
- meta.timezone: Always “UTC” to anchor timestamps.
Python (requests)
import requests
p = {'country': 'PT', 'maturity': '10Y', 'date': '2026-10-30'}
r = requests.get('https://bonds-api.com/api/v1/intraday',
headers={'X-API-Key': 'YOUR_API_KEY'}, params=p)
j = r.json()
series = [(s['fetched_at'], s['yield']) for s in j['snapshots']]
print(series)
JavaScript (fetch)
const intr = new URL('https://bonds-api.com/api/v1/intraday');
intr.searchParams.set('country', 'PT');
intr.searchParams.set('maturity', '10Y');
intr.searchParams.set('date', '2026-10-30');
fetch(intr, { headers: { 'X-API-Key': 'YOUR_API_KEY' }})
.then(r => r.json())
.then(j => j.snapshots.forEach(s => console.log(s.fetched_at, s.yield)));
PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => [
'method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"
]]);
$url = 'https://bonds-api.com/api/v1/intraday?country=PT&maturity=10Y&date=2026-10-30';
$data = json_decode(file_get_contents($url, false, $ctx), true);
foreach ($data['snapshots'] as $s) {
echo $s['fetched_at'] . ' ' . $s['yield'] . PHP_EOL;
}
Fluctuation over a period: /api/v1/fluctuation
Summarize change, min, and max over a date range. This is ideal for heatmaps, risk dashboards, or alert thresholds.
cURL
JSON response
Fields:
- start_yield and end_yield: Period endpoints in percent.
- change: Arithmetic difference (end - start) in percentage points.
- min and max: Extremes observed within the period.
Python (requests)
import requests
p = {'countries': 'PT', 'maturity': '10Y', 'start': '2025-10-30', 'end': '2026-10-30'}
r = requests.get('https://bonds-api.com/api/v1/fluctuation',
headers={'X-API-Key': 'YOUR_API_KEY'}, params=p)
j = r.json()['data']['PT']
print('Δ (pp):', j['change'], 'Min:', j['min'], 'Max:', j['max'])
JavaScript (fetch)
const fl = new URL('https://bonds-api.com/api/v1/fluctuation');
fl.searchParams.set('countries', 'PT');
fl.searchParams.set('maturity', '10Y');
fl.searchParams.set('start', '2025-10-30');
fl.searchParams.set('end', '2026-10-30');
fetch(fl, { headers: { 'X-API-Key': 'YOUR_API_KEY' }})
.then(r => r.json())
.then(j => {
const d = j.data.PT;
console.log('Change', d.change, 'Min', d.min, 'Max', d.max);
});
PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => [
'method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"
]]);
$url = 'https://bonds-api.com/api/v1/fluctuation?countries=PT&maturity=10Y&start=2025-10-30&end=2026-10-30';
$j = json_decode(file_get_contents($url, false, $ctx), true);
$d = $j['data']['PT'];
echo $d['change'] . ' ' . $d['min'] . ' ' . $d['max'];
Practical implementation details for Portugal
- Maturities: Common tenors include 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, and 30Y. Availability depends on issuance and market data coverage on a given date.
- Business days and holidays: Expect data on Portuguese/European trading days. Weekends and national holidays will not produce new daily observations.
- Update frequency: Daily endpoints update once per trading day. Intraday snapshots reflect multiple points during market hours and return timestamps in UTC.
- Caching: Use in-memory caching (e.g., Redis) for 30–60 seconds for intraday and a few minutes for daily endpoints to reduce latency and rate consumption. For historical and time series data, longer caching is safe.
- Building a PT curve: You can either call /api/v1/curve for a ready-made curve or fetch selected points via /api/v1/latest with multiple maturities (e.g., 1Y, 2Y, 5Y, 10Y, 30Y) and interpolate.
- Error handling: Watch for 401 (missing/invalid key), 403 (quota exceeded), 404 (no data for the requested combination), 422 (invalid parameter), 429 (rate limit), and 500 (server error). Implement retries for 429/500 with exponential backoff.
Reference the docs and explore interactively at bonds-api.com. When you’re ready to build, Register and try the MCP console.
Use cases: Portugal-focused fixed income workflows
- Financial dashboards: Display PT 2Y–30Y yields with intraday updates and prior-close deltas, using /latest and /intraday.
- Portfolio risk tools: Track 10Y shifts using /fluctuation and alert when spreads vs. Bunds or UST breach thresholds from /spread.
- Economic research: Build charts and regressions from /timeseries over multiple regimes and annotate with /historical snapshots on key dates.
- Curve analysis: Construct a PT curve via /curve and examine inversion or steepening trends alongside macro events.
Error responses and resilience patterns
Every endpoint returns a common error shape on failure: success=false with an error message. Typical HTTP status codes include:
- 401: Missing or invalid X-API-Key — refresh credentials and retry after validation.
- 403: Account quota exceeded — back off and optimize polling/caching.
- 404: No data for the requested country/maturity/date — verify ISO2, maturity, and date range.
- 422: Invalid parameter — check date formats (Y-m-d) and maturity codes.
- 429: Rate limit exceeded — add client-side throttling and retry with exponential backoff.
- 500: Server error — retry with jitter; log correlation IDs if available.
Add circuit breakers around dependent services, and prefer idempotent retries for GET requests. When building time series workflows, tolerate occasional missing days on non-trading dates.
FAQ
What unit are the yields in?
Yields are expressed as percentages (e.g., 4.52 means 4.52%). Spreads from /spread are in basis points (e.g., 215 = 2.15%).
Which timezone applies to timestamps?
Dates (Y-m-d) reflect the trading day. Timestamps like intraday fetched_at are in ISO 8601 UTC, and meta.timezone confirms “UTC.”
How can I build a custom PT curve?
Either call /api/v1/curve for a complete curve on a date, or call /api/v1/latest with multiple maturities (e.g., 1Y,2Y,5Y,10Y,30Y) for the latest points and then interpolate.
How do weekends and holidays affect responses?
No new daily observations are produced on weekends or Portuguese market holidays. Time series skip non-trading days.
How should I cache results?
Cache intraday for tens of seconds and daily endpoints for a few minutes. Longer caches are safe for historical/time series endpoints. Implement retry/backoff for 429/500.
Ready to ship Portugal yield curve analytics into your product? Visit bonds-api.com, then Get started with Bonds API or Register and explore endpoints in the MCP.