You need a reliable way to fetch, chart, and analyze the Portugal 10-year government bond yield inside your own tools. By the end of this article, you will be able to pull the latest PT 10Y yield, get historical and intraday snapshots, compute spreads to benchmarks, assemble the full Portuguese yield curve, and summarize fluctuations over any period using Bonds API’s REST endpoints.
What the PT 10Y yield represents and how to use it
The Portugal 10-year bond yield is the market’s required return to lend to the Portuguese government over ten years. Analysts use it to price risk, derive discount rates, and benchmark Portuguese assets. In applications, the PT 10Y is typically displayed as a percentage (for example 4.52 means 4.52%). Spreads to benchmarks (for example vs. US Treasuries or German Bunds) are often expressed in basis points (1 basis point = 0.01%).
With bonds-api.com, you can source these yields as JSON via a simple, authenticated GET request. Yields are provided by maturity and date, and the API covers snapshots (intraday), daily historical series, and full yield curves for Portugal (ISO2: PT).
Quick start and request patterns
All Bonds API requests use GET against the base URL https://bonds-api.com/api/v1/ and are authenticated with the X-API-Key header. You can explore models and endpoints at the MCP. To obtain an API key, use the Register link.
Units and timestamps:
- yield: percentage (e.g., 4.52 means 4.52%)
- spread_bps: basis points (e.g., 215 means 2.15%)
- date: ISO 8601 calendar date in Y-m-d (e.g., 2026-10-15)
- fetched_at (intraday): ISO 8601 timestamp in UTC (e.g., 2026-10-15T12:00:00Z)
For production, cache daily endpoints by country and maturity for the active trading day. Intraday snapshots change more frequently; consider shorter TTLs for them.
Compatibility sample (copy exactly as shown)
The following official sample must be included verbatim. It demonstrates a call to the latest endpoint. Note that this block uses a query parameter for the API key and returns a schema with US data; copy it exactly as shown:
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"{
"success": true,
"date": "2026-10-15",
"rates": {
"US_10Y": 5.16
},
"dates": {
"US_10Y": "2026-10-15"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "2b89da21-1a4e-4aa2-9a9a-0aed156af0f0",
"timestamp": "2026-10-15T00:04:46+00:00"
}
}Latest yields for Portugal (PT) — focus on 10Y
Use /latest to fetch the most recent daily yields for one or more maturities. This is the fastest way to display the current PT 10Y on a dashboard. Omit the maturities parameter to retrieve all available maturities for Portugal, or pass a comma-separated list (e.g., 2Y,10Y).
cURL
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_10y = data["data"]["PT"]["10Y"]["yield"]
as_of = data["data"]["PT"]["10Y"]["date"]
print("PT 10Y:", pt_10y, "as of", as_of)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(), {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
const tenY = json.data.PT["10Y"].yield;
const date = json.data.PT["10Y"].date;
console.log(`PT 10Y ${tenY}% on ${date}`);
});PHP (file_get_contents)
<?php
$url = "https://bonds-api.com/api/v1/latest?countries=PT&maturities=2Y,10Y";
$opts = ["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]];
$ctx = stream_context_create($opts);
$json = file_get_contents($url, false, $ctx);
$data = json_decode($json, true);
$pt10 = $data["data"]["PT"]["10Y"]["yield"];
$date = $data["data"]["PT"]["10Y"]["date"];
echo "PT 10Y $pt10% on $date\n";Sample JSON response
How to read it: yields are percentages; date is the trading date (Y-m-d). The source field indicates provenance (for example “official”). For UI display, format 4.52 as “4.52%”. For math, treat 4.52 as 0.0452 when a decimal rate is required.
Historical yield on a specific date (PT 10Y)
Use /historical to retrieve the PT 10Y on a given calendar date. If the date is a non-business day, the API may return a 404 for that exact date; request the nearest business day instead.
cURL
Python (requests)
import requests
params = {"country": "PT", "maturity": "10Y", "date": "2025-06-15"}
r = requests.get("https://bonds-api.com/api/v1/historical",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
hist = r.json()
print(hist["country"], hist["maturity"], hist["date"], hist["yield"])JavaScript (fetch)
const params = new URLSearchParams({
country: "PT", maturity: "10Y", date: "2025-06-15"
});
fetch(`https://bonds-api.com/api/v1/historical?${params}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
console.log(`PT ${j.maturity} on ${j.date}: ${j.yield}%`);
});PHP (file_get_contents)
<?php
$url = "https://bonds-api.com/api/v1/historical?country=PT&maturity=10Y&date=2025-06-15";
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$res = file_get_contents($url, false, $ctx);
$j = json_decode($res, true);
echo "PT {$j['maturity']} on {$j['date']}: {$j['yield']}%\n";Sample JSON response
Interpretation: yield is a percentage for the provided date. Use the date as displayed for labeling charts. Handle 404 errors by prompting users to choose a nearby business day.
Time series for PT 10Y (for charts and analytics)
Use /timeseries to fetch a daily series between two dates for Portugal’s 10-year. This is ideal for plotting trend lines, computing rolling statistics, and feeding analytics pipelines.
cURL
Python (requests)
import requests
p = {"country": "PT", "maturity": "10Y", "start": "2025-10-15", "end": "2026-10-15"}
resp = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"}, params=p)
ts = resp.json()["series"]
first = ts[0]
print("First point:", first["date"], first["yield"])JavaScript (fetch)
const q = new URLSearchParams({
country: "PT", maturity: "10Y", start: "2025-10-15", end: "2026-10-15"
});
fetch(`https://bonds-api.com/api/v1/timeseries?${q}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
j.series.forEach(p => {
// p.date in Y-m-d, p.yield as percentage
});
});PHP (file_get_contents)
<?php
$q = http_build_query([
"country" => "PT", "maturity" => "10Y", "start" => "2025-10-15", "end" => "2026-10-15"
]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/timeseries?$q", false, $ctx);
$out = json_decode($json, true);
echo count($out["series"]), " points\n";Sample JSON response
Interpretation: series is an array of daily points (business days). You can fill non-trading days in your UI if desired, but the API returns the actual observation dates only.
Intraday snapshots (PT 10Y)
/intraday yields give multiple snapshots within a trading day, timestamped in UTC. Use them for dashboards that need within-day changes.
cURL
Python (requests)
import requests
p = {"country": "PT", "maturity": "10Y", "date": "2026-10-15"}
r = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"}, params=p)
snap = r.json()
for s in snap["snapshots"]:
print(s["fetched_at"], s["yield"])JavaScript (fetch)
const u = new URL("https://bonds-api.com/api/v1/intraday");
u.searchParams.set("country", "PT");
u.searchParams.set("maturity", "10Y");
u.searchParams.set("date", "2026-10-15");
fetch(u.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
// j.meta.timezone = "UTC"
j.snapshots.forEach(s => console.log(s.fetched_at, s.yield));
});PHP (file_get_contents)
<?php
$url = "https://bonds-api.com/api/v1/intraday?country=PT&maturity=10Y&date=2026-10-15";
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$res = file_get_contents($url, false, $ctx);
$j = json_decode($res, true);
foreach ($j["snapshots"] as $s) {
echo $s["fetched_at"], " ", $s["yield"], "\n";
}Sample JSON response
Interpretation: yields are percentages; fetched_at is an ISO 8601 UTC timestamp. Use meta.timezone for display conversions. The count field is a convenience tally of snapshots in the array.
Full Portugal yield curve (build curves and interpolate)
/curve returns the full sovereign curve for Portugal for the latest available date (or a specific date if provided). Use it to build curve charts or perform interpolations for off-the-run tenors.
cURL
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()
date = curve["date"]
ten_y = curve["curve"]["10Y"]
print("Curve date:", date, "PT 10Y:", ten_y)JavaScript (fetch)
const q = new URLSearchParams({ country: "PT" });
fetch(`https://bonds-api.com/api/v1/curve?${q}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
// j.inverted indicates whether short rates exceed long rates overall
console.log("PT 10Y:", j.curve["10Y"], "on", j.date);
});PHP (file_get_contents)
<?php
$url = "https://bonds-api.com/api/v1/curve?country=PT";
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$j = json_decode(file_get_contents($url, false, $ctx), true);
echo "Date ", $j["date"], " PT 10Y ", $j["curve"]["10Y"], "%\n";Sample JSON response
Interpretation: all values are percentages by maturity bucket. inverted is a boolean flag indicating whether the curve is broadly inverted. The date is in Y-m-d and represents the latest trading day with complete curve data (or the requested date when specified).
Portugal maturities returned by /curve (example)
| Maturity | Yield (%) |
|---|---|
| 1M | 5.31 |
| 3M | 5.27 |
| 6M | 5.18 |
| 1Y | 4.98 |
| 2Y | 4.25 |
| 5Y | 4.39 |
| 10Y | 4.52 |
| 30Y | 4.71 |
To build a curve in your UI, you can also call /latest with maturities=1M,3M,6M,1Y,2Y,5Y,10Y,30Y if you prefer one endpoint for multiple points. /curve is simpler when you want a synchronized set from a single valuation date.
Spread to benchmark (e.g., PT vs US 10Y)
/spread computes the difference between Portugal’s yield and a benchmark country at a given maturity (default 10Y). The result is returned in basis points alongside both absolute yields.
cURL
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("Spread (bps):", s["spread_bps"], "PT:", s["country_yield"], "US:", s["benchmark_yield"])JavaScript (fetch)
const paramsS = new URLSearchParams({ country: "PT", benchmark: "US", maturity: "10Y" });
fetch(`https://bonds-api.com/api/v1/spread?${paramsS}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
// spread_bps is in basis points (1 bp = 0.01%)
console.log(`PT-US 10Y spread: ${j.spread_bps} bps`);
});PHP (file_get_contents)
<?php
$url = "https://bonds-api.com/api/v1/spread?country=PT&benchmark=US&maturity=10Y";
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$j = json_decode(file_get_contents($url, false, $ctx), true);
echo "Spread (bps): {$j['spread_bps']}, PT: {$j['country_yield']}%, US: {$j['benchmark_yield']}%\n";Sample JSON response
Interpretation: spread_bps is the absolute difference in basis points. For example, 215 bps equals 2.15 percentage points. Use this to monitor Portugal’s relative risk premium.
Fluctuation summary over a period (PT 10Y)
/fluctuation summarizes start, end, change, minimum, and maximum yields over a time window. Useful for quick fact panels and risk summaries.
cURL
Python (requests)
import requests
p = {"countries": "PT", "maturity": "10Y", "start": "2025-10-15", "end": "2026-10-15"}
r = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"}, params=p)
f = r.json()["data"]["PT"]
print("Δ:", f["change"], "min:", f["min"], "max:", f["max"])JavaScript (fetch)
const pf = new URLSearchParams({
countries: "PT", maturity: "10Y", start: "2025-10-15", end: "2026-10-15"
});
fetch(`https://bonds-api.com/api/v1/fluctuation?${pf}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
const f = j.data.PT;
console.log(`Change: ${f.change} (min ${f.min}, max ${f.max})`);
});PHP (file_get_contents)
<?php
$q = http_build_query([
"countries" => "PT", "maturity" => "10Y", "start" => "2025-10-15", "end" => "2026-10-15"
]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$j = json_decode(file_get_contents("https://bonds-api.com/api/v1/fluctuation?$q", false, $ctx), true);
$pt = $j["data"]["PT"];
echo "Start {$pt['start_yield']} End {$pt['end_yield']} Δ {$pt['change']} Min {$pt['min']} Max {$pt['max']}\n";Sample JSON response
Interpretation: values are percentages. change is end_yield - start_yield in percentage points. Use this endpoint to quickly surface “range and change” insights without post-processing a time series.
Error handling and operational notes
Common error responses share a standard shape: success=false and an error message. Handle these with appropriate UI feedback and logging.
- 401: Missing or invalid X-API-Key
- 403: Account quota exceeded
- 404: No data for requested country/maturity/date combination
- 422: Invalid parameter (wrong date format, unknown ISO2 code, etc.)
- 429: Rate limit exceeded
- 500: Server error
Trading days and holidays: Daily endpoints reflect the latest business day with available data; weekends and market holidays typically do not produce new daily observations. For charts, either omit missing days or forward-fill to the next observation as appropriate for your analytics.
Update frequency: Daily endpoints update once per business day. Intraday endpoints include multiple snapshots; design your polling interval conservatively and cache short-lived responses to reduce load.
Caching guidance:
- Daily endpoints (/latest, /historical, /timeseries, /curve, /fluctuation): cache by country, maturity, and date for the trading day.
- Intraday (/intraday): cache for minutes, not hours; merge snapshots client-side if you maintain an internal time grid.
Timezones and timestamps: All dates are Y-m-d. Intraday timestamps are ISO 8601 UTC. Convert to local timezones in your UI as needed.
For full reference and additional guidance, see bonds-api.com and the MCP.
Putting it all together for Portugal 10Y
For a production-grade PT 10Y widget or analytics module:
- Fetch /latest for PT 10Y (and optionally neighboring maturities) at app start and on a daily refresh schedule.
- For charts, call /timeseries for the visible window; append new days as they close.
- On the current trading day, optionally augment with /intraday snapshots to display within-day moves.
- For cross-market context, compute /spread vs DE (Bund) or US to display the premium in basis points.
- Use /curve for a synchronized set of maturities when you need the entire Portuguese curve at a single date/time.
- Provide a quick facts panel driven by /fluctuation for change, min, and max over the selected period.
These endpoints use consistent shapes: percentages for yield, basis points for spread_bps, and Y-m-d dates. This uniformity makes it straightforward to standardize transformations, caching keys, and tests across your codebase.
FAQ
Q: How are yields expressed?
A: As percentages (for example 4.52). Display “4.52%” in UI. For calculations that require a decimal rate, convert to 0.0452.
Q: What timezone should I assume for intraday timestamps?
A: Intraday fetched_at is in UTC (ISO 8601). Convert to user-local timezones for display if needed.
Q: What happens on weekends and market holidays?
A: Daily endpoints typically do not produce new data for non-trading days. Use the latest available business day or request a specific earlier date.
Q: Can I get multiple maturities in one request?
A: Yes. /latest supports a comma-separated list via maturities=..., and /curve returns a full set for the chosen date.
Q: How should I handle errors and rate limits?
A: Check success in responses, back off on 429, validate parameters to avoid 422, and log server-side 500s for retry. Cache daily results to reduce request volume.
Ready to integrate Portugal’s 10-year yield into your tools? Get an API key and start building today: Register. You can also explore endpoints and schemas in the MCP. For more, visit bonds-api.com.