API to Get Portugal Bond Yields

API to Get Portugal Bond Yields

You need reliable, programmatic access to Portugal’s sovereign bond yields that you can feed into models, dashboards, and risk tools. By the end of this guide you will query the Bonds API for Portugal (PT) across maturities, fetch specific dates and time ranges, calculate spreads, assemble the full yield curve, pull intraday snapshots, and compute fluctuations—then integrate the results into Python, JavaScript, or PHP code.

What you get from Bonds API for Portugal

Bonds API serves sovereign yields as JSON over HTTPS from https://bonds-api.com. For Portugal (ISO2: PT), you can request:

Illustration: API to Get Portugal Bond Yields
  • Latest yields by maturity (e.g., 1M to 30Y).
  • Historical yields on a specific date.
  • Daily time series between two dates.
  • Intraday snapshots for a given date and maturity.
  • Spreads versus a benchmark (e.g., German Bund or US Treasuries).
  • Full yield curve and inversion flag.
  • Fluctuation stats: start, end, change, min, max over a period.

All endpoints use GET, the base URL is https://bonds-api.com/api/v1/, and you authenticate using an X-API-Key header. Yields are returned as percentages unless otherwise noted (spreads are in basis points). Dates are ISO format (Y-m-d). Intraday timestamps are UTC.

Portugal sovereign bonds: maturities, business days, and updates

Portugal’s sovereign curve typically spans money market bills (1M, 3M, 6M), short coupons (1Y, 2Y), and benchmarks out the curve (5Y, 10Y, 30Y). The API’s /curve endpoint returns the broad set available for the requested date, while /latest supports filtering to a subset via the maturities parameter.

Yields generally update on market business days. On weekends and market holidays, the latest date may remain the last business day. For intraday snapshots, timestamps are UTC. When building applications, implement caching aligned to your frequency needs: for end-of-day analytics cache daily; for trading dashboards consider short-lived caches (e.g., a few minutes) and use /intraday for finer granularity.

Endpoints at a glance

  • /latest: Current yields for one or more countries and maturities.
  • /historical: Yield for a single country and maturity on a specified date.
  • /timeseries: Daily yields across a date range.
  • /spread: Spread versus a benchmark country at a maturity (bps).
  • /curve: Full yield curve for a country on a given date or latest.
  • /intraday: Intraday snapshots for a maturity on a date (UTC timestamps).
  • /fluctuation: Start/end yields, change, min, max over a period.

Explore the API and tools at the MCP, and get your key at Register. You can also visit the homepage at bonds-api.com.

Authentication and request pattern

Use an API key via the X-API-Key header. All endpoints are GET.

  • Base URL: https://bonds-api.com/api/v1/
  • Header: X-API-Key: YOUR_API_KEY
  • Method: GET

Error responses follow a common shape: success=false with an error message. Typical HTTP statuses include 401 (missing/invalid key), 403 (quota exceeded), 404 (no data for that combination), 422 (invalid parameters), 429 (rate limit), and 500 (server error).

Official sample: live latest request and response

The following official sample demonstrates a latest request and a live-style response schema. Copy exactly as-is to test your connectivity and JSON parsing.

curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"
{
    "success": true,
    "date": "2026-11-13",
    "rates": {
        "US_10Y": 5.15
    },
    "dates": {
        "US_10Y": "2026-11-13"
    },
    "currencies": {
        "US_10Y": "USD"
    },
    "meta": {
        "request_id": "6d37bda8-3a12-42d5-871a-03d6d6269774",
        "timestamp": "2026-11-14T00:04:05+00:00"
    }
}

How to read it:

  • success: true indicates a valid response.
  • date is the latest business date with data (Y-m-d).
  • rates contains yield values in percent (here, US_10Y is 5.15%).
  • dates maps symbols to their effective dates.
  • currencies indicates the reporting currency for that instrument.
  • meta.timestamp is an ISO-8601 UTC time when the response was generated.

Current yields for Portugal: /latest

Fetch the current PT yields. Include maturities to limit the response; omit maturities to retrieve all available for Portugal.

cURL

JSON response

Field notes:

  • yield is a percentage (e.g., 4.52 means 4.52%).
  • date is the effective market date (Y-m-d), typically the last business day.
  • source indicates the origin (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"}
)
resp.raise_for_status()
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)

async function getLatestPT() {
const url = new URL("https://bonds-api.com/api/v1/latest");
url.searchParams.set("countries", "PT");
url.searchParams.set("maturities", "2Y,10Y");
const res = await fetch(url.toString(), {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const json = await res.json();
const twoY = json.data.PT["2Y"].yield;
const tenY = json.data.PT["10Y"].yield;
console.log({ twoY, tenY });
}
getLatestPT();

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"]];
$context = stream_context_create($opts);
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
echo "PT 10Y: " . $data["data"]["PT"]["10Y"]["yield"] . "%\n";

Yield on a specific date: /historical

Request one maturity for PT on a given date (Y-m-d). Use this to backfill model inputs or align yields with economic releases.

cURL

JSON response

yield is a percent value. If the requested date is a non-business day, expect the service to return data for that date only if it exists; otherwise use /timeseries to find the nearest previous business day programmatically.

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)
r.raise_for_status()
row = r.json()
print(f'{row["country"]} {row["maturity"]} on {row["date"]}: {row["yield"]}%')

JavaScript (fetch)

async function getPTOnDate() {
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");
const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await res.json();
console.log(json.country, json.maturity, json.date, json.yield + "%");
}
getPTOnDate();

PHP (Guzzle)

<?php
require 'vendor/autoload.php';
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://bonds-api.com/api/v1/',
'headers' => ['X-API-Key' => 'YOUR_API_KEY']
]);
$res = $client->get('historical', ['query' => [
'country' => 'PT', 'maturity' => '10Y', 'date' => '2025-06-15'
]]);
echo $res->getBody();

Time series for Portugal: /timeseries

Pull daily yields between two dates to compute rolling metrics, regressions, or charting.

cURL

JSON response

Each element is a business-day observation with date (Y-m-d) and yield (percent). Non-trading days are typically absent from the series. Cache at the grain you query; for analytics, daily cache aligns with business calendars.

Python (requests)

import requests, pandas as pd
params = {"country": "PT", "maturity": "10Y", "start": "2025-11-14", "end": "2026-11-14"}
res = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"}, params=params)
res.raise_for_status()
series = res.json()["series"]
df = pd.DataFrame(series).assign(yield_pct=lambda d: d["yield"])
print(df.head())

JavaScript (fetch)

async function getPTSeries() {
const url = new URL("https://bonds-api.com/api/v1/timeseries");
url.searchParams.set("country", "PT");
url.searchParams.set("maturity", "10Y");
url.searchParams.set("start", "2025-11-14");
url.searchParams.set("end", "2026-11-14");
const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await res.json();
console.log(json.series.slice(0, 3));
}
getPTSeries();

PHP (file_get_contents)

<?php
$url = "https://bonds-api.com/api/v1/timeseries?country=PT&maturity=10Y&start=2025-11-14&end=2026-11-14";
$opts = ["http" => ["header" => "X-API-Key: YOUR_API_KEY\r\n"]];
$ctx = stream_context_create($opts);
$data = json_decode(file_get_contents($url, false, $ctx), true);
foreach ($data["series"] as $row) {
echo $row["date"] . " " . $row["yield"] . "%\n";
}

Spread versus benchmark: /spread

Compare Portugal’s yield to a benchmark such as the US (US Treasuries) or DE (German Bund). Spreads are returned in basis points (bps).

cURL

JSON response

Interpretation:

  • spread_bps is in basis points (215 bps = 2.15%).
  • country_yield and benchmark_yield are both percentages.

Python (requests)

import requests
q = {"country": "PT", "benchmark": "US", "maturity": "10Y"}
r = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"}, params=q)
r.raise_for_status()
s = r.json()
print(f"PT vs {s['benchmark']} {s['maturity']}: {s['spread_bps']} bps")

JavaScript (fetch)

async function getPTSpread() {
const url = new URL("https://bonds-api.com/api/v1/spread");
url.searchParams.set("country", "PT");
url.searchParams.set("benchmark", "US");
url.searchParams.set("maturity", "10Y");
const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await res.json();
console.log(`Spread: ${json.spread_bps} bps`);
}
getPTSpread();

PHP (Guzzle)

<?php
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://bonds-api.com/api/v1/',
'headers' => ['X-API-Key' => 'YOUR_API_KEY']
]);
$r = $client->get('spread', ['query' => ['country' => 'PT', 'benchmark' => 'US', 'maturity' => '10Y']]);
echo $r->getBody();

Full yield curve for Portugal: /curve

Get the entire PT curve. If you omit date, the API returns the latest available business day. Use inverted to detect curve inversion.

cURL

JSON response

All curve values are yields in percent. inverted indicates whether shorter maturities yield more than longer ones (a classic inversion signal).

Python (requests)

import requests
r = requests.get("https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "PT"})
r.raise_for_status()
curve = r.json()["curve"]
teny = curve["10Y"]
print("PT curve 10Y:", teny, "%")

JavaScript (fetch)

async function getPTCurve() {
const url = new URL("https://bonds-api.com/api/v1/curve");
url.searchParams.set("country", "PT");
const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await res.json();
console.log("Inverted:", json.inverted, "10Y:", json.curve["10Y"]);
}
getPTCurve();

PHP (file_get_contents)

<?php
$url = "https://bonds-api.com/api/v1/curve?country=PT";
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$data = json_decode(file_get_contents($url, false, $ctx), true);
echo "PT 30Y: " . $data["curve"]["30Y"] . "%\n";

Intraday Portugal yields: /intraday

Use this endpoint for multiple snapshots through the session. Timestamps are in UTC and include a fetched_at field.

cURL

JSON response

yield is percent; fetched_at is an ISO-8601 UTC timestamp. The meta.timezone echoes UTC for clarity. Use count to confirm completeness when reconciling snapshots.

Python (requests)

import requests, statistics
p = {"country": "PT", "maturity": "10Y", "date": "2026-11-14"}
r = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"}, params=p)
r.raise_for_status()
snapshots = r.json()["snapshots"]
yields = [s["yield"] for s in snapshots]
print("PT 10Y intraday mean:", statistics.fmean(yields))

JavaScript (fetch)

async function getPTIntraday() {
const url = new URL("https://bonds-api.com/api/v1/intraday");
url.searchParams.set("country", "PT");
url.searchParams.set("maturity", "10Y");
url.searchParams.set("date", "2026-11-14");
const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await res.json();
const last = json.snapshots[json.snapshots.length - 1];
console.log("Last snapshot:", last.yield, "@", last.fetched_at);
}
getPTIntraday();

PHP (Guzzle)

<?php
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://bonds-api.com/api/v1/',
'headers' => ['X-API-Key' => 'YOUR_API_KEY']
]);
$res = $client->get('intraday', ['query' => [
'country' => 'PT', 'maturity' => '10Y', 'date' => '2026-11-14'
]]);
$data = json_decode($res->getBody(), true);
echo "Snapshots: " . $data["count"] . "\n";

Fluctuation stats for Portugal: /fluctuation

Get summary stats for a period: start yield, end yield, total change, and the observed min/max. Ideal for reporting and alerts.

cURL

JSON response

All values are in percent. change is end_yield minus start_yield (percentage points). Use this to drive portfolio commentary and risk summaries.

Python (requests)

import requests
q = {"countries": "PT", "maturity": "10Y", "start": "2025-11-14", "end": "2026-11-14"}
r = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"}, params=q)
r.raise_for_status()
d = r.json()["data"]["PT"]
print("Δ:", d["change"], "pp; range:", d["min"], "-", d["max"])

JavaScript (fetch)

async function getPTFluctuation() {
const url = new URL("https://bonds-api.com/api/v1/fluctuation");
url.searchParams.set("countries", "PT");
url.searchParams.set("maturity", "10Y");
url.searchParams.set("start", "2025-11-14");
url.searchParams.set("end", "2026-11-14");
const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await res.json();
const stats = json.data.PT;
console.log(`Change ${stats.change} pp; min ${stats.min}; max ${stats.max}`);
}
getPTFluctuation();

PHP (file_get_contents)

<?php
$url = "https://bonds-api.com/api/v1/fluctuation?countries=PT&maturity=10Y&start=2025-11-14&end=2026-11-14";
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents($url, false, $ctx);
$data = json_decode($json, true);
$pt = $data["data"]["PT"];
echo "Start: {$pt['start_yield']}%, End: {$pt['end_yield']}%, Change: {$pt['change']} pp\n";

Building a multi-maturity PT curve and reading units

You can build a PT curve in two ways:

  • Call /curve once for the full set of maturities and use the inverted flag.
  • Call /latest with countries=PT and a comma-separated maturities list (e.g., 1M,3M,6M,1Y,2Y,5Y,10Y,30Y) to assemble your own curve object alongside other countries for cross-market dashboards.

All yields are in percent. Spreads from /spread are in basis points (1 bp = 0.01%). Dates are Y-m-d, and intraday timestamps include a Z suffix (UTC). For consistent timeseries joins, normalize to UTC and use the date key as your daily index.

Error handling and caching tips

  • 401/403: Ensure your X-API-Key is present and active.
  • 404: Verify the combination country/maturity/date exists; for non-business days, consider fetching the previous business day with /timeseries.
  • 422: Check ISO2 codes (PT), maturity strings (e.g., 10Y), and date formats (Y-m-d).
  • 429: Back off and retry with jitter; implement client-side caching according to your refresh cadence.

For EOD analytics, caching per business day is effective. For near-real-time displays, keep caches short and rely on /intraday to refresh panels without overwhelming your rate budget.

Use cases: Portugal-focused fixed-income analytics

  • Trader dashboards: Show PT 2Y, 5Y, 10Y with color-coded changes, plus /intraday micro-charts.
  • Risk engines: Pull /timeseries for PT 10Y to recompute DV01 or scenario shocks daily.
  • Macro research: Compare PT 10Y to DE 10Y via /spread and summarize with /fluctuation.
  • Curve modeling: Fit splines to /curve outputs and detect inversions (inverted flag) programmatically.

Test interactively in the MCP and integrate into your stack with the examples above. For access, Register. Also see bonds-api.com for product details and coverage.

FAQ

What units are yields and spreads in?
Yields are percentages (e.g., 4.52 means 4.52%). Spreads from /spread are in basis points (bps). 100 bps equals 1.00%.

How should I handle weekends and holidays for Portugal?
Results are keyed by market business days. On non-trading days, the latest data may remain the prior business day. For historical lookups on a weekend, prefer /timeseries over a single /historical date if you need the prior close reliably.

What timezone are timestamps in?
Dates are Y-m-d (no time). Intraday snapshots include fetched_at as an ISO-8601 UTC timestamp with Z, and meta.timezone clarifies UTC.

Can I build cross-country dashboards with Portugal?
Yes. Use /latest with countries=PT,DE,US and selected maturities to align instruments by tenor. For spreads, /spread returns basis-point deltas relative to your chosen benchmark.

How do I detect curve inversion for Portugal?
/curve returns an inverted boolean. You can also compute it by comparing short vs long maturities from /curve or a multi-maturity /latest response.

Ready to integrate Portugal’s sovereign yield curve into your models and dashboards? Get started with Bonds API and explore endpoints interactively in the Bonds API MCP.

Start building with bond data today

Get your API key and access sovereign bond yields across 60+ countries. 7-day free trial, no credit card required.