You need reliable Colombian sovereign bond yields inside your models and dashboards, with clear endpoints for latest levels, historical points, time series, spreads, and an entire curve. By the end of this guide, you’ll be able to pull Colombia (ISO2: CO) yields from Bonds API, interpret the responses, build a yield curve, compute spreads, and productionize requests with caching and market-calendar awareness.
What this API delivers for Colombia (CO)
Bonds API provides standardized sovereign bond yields as percentages across maturities from short bills to long bonds. For Colombia, you can query:
- Latest yields for specific maturities or all available tenors.
- Historical points on a given business day.
- Daily time series between two dates.
- Intraday snapshots (UTC timestamps) for a date and maturity.
- Spreads versus a benchmark country (e.g., US Treasuries).
- A full on-the-run yield curve for a date, with an inverted flag.
- Fluctuation summaries with start/end yields, changes, and min/max.
All responses return yields as percentages (e.g., 4.52 means 4.52%). Spreads are returned in basis points (bps), where 1 bp = 0.01%.
Explore the product and coverage at bonds-api.com. To try calls in your environment, get an API key at the Register page or verify endpoints via the MCP.
Authentication and request pattern
Base URL: https://bonds-api.com/api/v1/
Authentication: include your API key in the X-API-Key header. All endpoints use GET and accept query parameters as shown below. Dates are Y-m-d; timestamps are in UTC.
- Header: X-API-Key: YOUR_API_KEY
- Method: GET (no POST/PUT/DELETE)
- Country: ISO2 code (CO for Colombia)
- Maturity: e.g., 2Y, 10Y, 30Y (comma-separated when supported)
You can always return here to bonds-api.com as the authoritative source while integrating.
Official sample block (verbatim)
The following official sample is reproduced exactly as provided:
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"
{
"success": true,
"date": "2026-11-10",
"rates": {
"US_10Y": 4.98
},
"dates": {
"US_10Y": "2026-11-10"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "f4979af1-97b8-4e71-bcb1-dc75d16a0ed4",
"timestamp": "2026-11-11T00:04:05+00:00"
}
}
Endpoint: Latest yields (CO)
Use /latest to fetch current yields for one or more maturities in Colombia. Omit maturities to return all available tenors. Dates reflect the market’s latest available business day.
cURL
JSON response
How to read:
- yield: Percentage level (e.g., 4.52 = 4.52%).
- date: Market date for the yield (Y-m-d).
- source: Data provenance tag (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": "CO", "maturities": "2Y,10Y"}
)
data = resp.json()
co_2y = data["data"]["CO"]["2Y"]["yield"]
co_10y = data["data"]["CO"]["10Y"]["yield"]
co_date = data["data"]["CO"]["10Y"]["date"]
print(co_2y, co_10y, co_date)
JavaScript (fetch)
const url = new URL("https://bonds-api.com/api/v1/latest");
url.search = new URLSearchParams({ countries: "CO", maturities: "2Y,10Y" }).toString();
fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" }})
.then(r => r.json())
.then(json => {
const co = json.data.CO;
console.log(co["2Y"].yield, co["10Y"].yield, co["10Y"].date);
});
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/latest?countries=CO&maturities=2Y,10Y";
$json = file_get_contents($url, false, $ctx);
$data = json_decode($json, true);
echo $data["data"]["CO"]["10Y"]["yield"];
Endpoint: Historical yield on a specific date
Use /historical to retrieve a single maturity’s yield on a specified date (Y-m-d). If the requested date is a non-business day, expect an error; use the previous business day when applicable in your logic.
cURL
JSON response
Fields:
- country, maturity, date: Your request echo.
- yield: Percentage on that date.
- source: Data provenance.
Python
import requests
params = {"country": "CO", "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)
print(r.json())
JavaScript
const params = { country: "CO", maturity: "10Y", date: "2025-06-15" };
fetch("https://bonds-api.com/api/v1/historical?" + new URLSearchParams(params), {
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json()).then(console.log);
PHP
<?php
$ctx = stream_context_create([
"http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]
]);
$url = "https://bonds-api.com/api/v1/historical?country=CO&maturity=10Y&date=2025-06-15";
echo file_get_contents($url, false, $ctx);
Endpoint: Time series between two dates
Use /timeseries to obtain a daily series between start and end (inclusive). Results are sampled by business day; weekends and holidays are omitted. Use this to chart yield trends, compute rolling vol, or run regressions.
cURL
JSON response
Each element contains date (Y-m-d) and yield (percentage). Build arrays keyed by date; when merging with other assets, ensure consistent calendar handling.
Python
import requests
p = {"country": "CO", "maturity": "10Y", "start": "2025-11-11", "end": "2026-11-11"}
js = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"}, params=p).json()
series = [(pt["date"], pt["yield"]) for pt in js["series"]]
print(series[:3])
JavaScript
const p = { country: "CO", maturity: "10Y", start: "2025-11-11", end: "2026-11-11" };
fetch("https://bonds-api.com/api/v1/timeseries?" + new URLSearchParams(p), {
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json()).then(json => {
console.log(json.series.length, json.series[0]);
});
PHP
<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$url = "https://bonds-api.com/api/v1/timeseries?country=CO&maturity=10Y&start=2025-11-11&end=2026-11-11";
$data = json_decode(file_get_contents($url, false, $ctx), true);
echo count($data["series"]);
Endpoint: Spread vs benchmark (e.g., vs US)
Use /spread to compute the Colombia-vs-benchmark spread at a given maturity. Spread is returned in basis points (bps). This is useful for relative value analysis, EM risk dashboards, and hedging.
cURL
JSON response
Interpretation:
- spread_bps: Colombia 10Y minus US 10Y, in basis points.
- country_yield / benchmark_yield: Input legs in percentages.
Python
import requests
params = {"country": "CO", "benchmark": "US", "maturity": "10Y"}
r = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"}, params=params)
sp = r.json()
print(sp["spread_bps"], sp["country_yield"], sp["benchmark_yield"])
JavaScript
const q = { country: "CO", benchmark: "US", maturity: "10Y" };
fetch("https://bonds-api.com/api/v1/spread?" + new URLSearchParams(q), {
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json()).then(console.log);
PHP
<?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=CO&benchmark=US&maturity=10Y";
echo file_get_contents($url, false, $ctx);
Endpoint: Full yield curve
Use /curve to retrieve all available Colombian maturities on a single date and an inverted flag. Great for curve construction, interpolation, and PCA across tenors.
cURL
JSON response
Notes:
- curve: Mapping tenor to yield (percentages).
- inverted: True when shorter maturities yield above longer ones overall.
- date: Curve reference date (Y-m-d).
Python
import requests
r = requests.get("https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "CO"})
curve = r.json()
tenors = list(curve["curve"].keys())
levels = list(curve["curve"].values())
print(curve["date"], curve["inverted"])
JavaScript
fetch("https://bonds-api.com/api/v1/curve?country=CO", {
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json()).then(curve => {
console.log(curve.date, curve.inverted, curve.curve["10Y"]);
});
PHP
<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$url = "https://bonds-api.com/api/v1/curve?country=CO";
$data = json_decode(file_get_contents($url, false, $ctx), true);
echo $data["curve"]["10Y"];
Endpoint: Intraday snapshots
Use /intraday for within-day snapshots of a single Colombian maturity, with fetched_at timestamps in UTC. This is helpful for high-frequency monitoring or calculating VWAP-like summary stats.
cURL
JSON response
Key points:
- yield: Percentage at snapshot time.
- fetched_at: ISO 8601 UTC timestamp (Z suffix).
- count: Total snapshots returned.
- meta.timezone: Always UTC for intraday.
Python
import requests
p = {"country": "CO", "maturity": "10Y", "date": "2026-11-11"}
js = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"}, params=p).json()
times = [s["fetched_at"] for s in js["snapshots"]]
levels = [s["yield"] for s in js["snapshots"]]
print(js["count"], times[0], levels[0])
JavaScript
const p2 = { country: "CO", maturity: "10Y", date: "2026-11-11" };
fetch("https://bonds-api.com/api/v1/intraday?" + new URLSearchParams(p2), {
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json()).then(json => {
console.log(json.count, json.snapshots.map(s => s.fetched_at));
});
PHP
<?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=CO&maturity=10Y&date=2026-11-11";
echo file_get_contents($url, false, $ctx);
Endpoint: Fluctuation summary
Use /fluctuation to summarize the change across a period for one or multiple countries at a chosen maturity. Returned fields include start_yield, end_yield, change, min, and max, all in percentage units.
cURL
JSON response
Interpretation:
- change: end_yield minus start_yield, in percentage points.
- min, max: Range extremes over the window (percentages).
Python
import requests
params = {"countries": "CO", "maturity": "10Y", "start": "2025-11-11", "end": "2026-11-11"}
r = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"}, params=params)
print(r.json()["data"]["CO"])
JavaScript
const f = { countries: "CO", maturity: "10Y", start: "2025-11-11", end: "2026-11-11" };
fetch("https://bonds-api.com/api/v1/fluctuation?" + new URLSearchParams(f), {
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json()).then(js => console.log(js.data.CO));
PHP
<?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=CO&maturity=10Y&start=2025-11-11&end=2026-11-11";
echo file_get_contents($url, false, $ctx);
Building a Colombian yield curve and spreads
There are two ways to assemble a curve:
- Fetch the full curve with /curve for CO. This guarantees a consistent date and tenor set.
- Alternatively, call /latest with countries=CO and a comma-separated maturities list to stitch a curve from requested tenors. Ensure the returned date fields match before using them together.
For spread analytics, use /spread for point-in-time comparisons to benchmarks like US Treasuries. To produce a tenor-by-tenor spread curve, iterate maturities and aggregate spread_bps into an array keyed by tenor. Use /fluctuation or /timeseries to study how those spreads evolve over windows.
Practical integration details
- Units: All yields are percentages (e.g., 4.52 = 4.52%). Spreads are basis points (integer or numeric, e.g., 215 bps = 2.15%).
- Dates and timestamps: Date fields are Y-m-d. Intraday fetched_at values are ISO 8601 UTC with a Z suffix, and meta.timezone is UTC.
- Business days and holidays: Colombian yields update on Colombian market business days; weekends and local holidays have no observations. Your backfills should skip non-trading days or use the previous available date.
- Update frequency: Use /latest for end-of-day snapshots; call /intraday if you need within-day changes. For daily charts, /timeseries covers each business day.
- Caching: Cache stable daily endpoints (/latest, /historical, /curve, /timeseries, /fluctuation) by country/maturity/date. For /intraday, apply short TTLs and respect timestamps to avoid redundant plots.
- Error handling: Expect JSON with success=false and an error message. Common statuses include 401 (missing/invalid key), 403 (quota exceeded), 404 (no data for the combination), 422 (invalid parameters), 429 (rate limit), 500 (server error). Retry idempotently with backoff on 429/500.
- Normalization: When combining time series across markets, align calendars, fill forward if appropriate, and store source fields for audit.
Use cases for fixed-income and fintech teams
- Dashboards: Display Colombia 2Y–30Y yields and the inverted flag using /curve; highlight daily changes via /fluctuation.
- Risk and scenario tools: Pull time series from /timeseries for factor models, VaR inputs, or stress by historical windows.
- Relative value: Compare CO vs US with /spread across multiple maturities; graph spread_bps and track deviations from trend.
- Execution monitoring: Track intraday moves around auction times or macro releases using /intraday and alert on large basis point shifts.
- Research backfills: Use /historical for specific event dates and /timeseries for longer pre/post windows.
Common error responses
All error payloads share a shape with success=false and a human-readable error message. Handle these cases explicitly:
- 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 (wait and retry with backoff).
- 500: Server error (transient; retry).
End-to-end example: Build and cache a CO 10Y chart
Workflow:
- Call /timeseries with country=CO, maturity=10Y, start and end for your window.
- Render a line chart of date vs yield (%). Label axes with units.
- Cache the response keyed by (CO, 10Y, start, end) with a TTL consistent with your refresh cadence.
- Supplement with /fluctuation for a concise change, min, and max summary.
Security, resilience, and observability
- Keys: Store X-API-Key in server-side config or secret manager. Never embed keys in client apps.
- Backoff: Exponential backoff with jitter on 429/500. Log request params and error messages for diagnosis.
- Validation: Assert expected fields exist (e.g., data.CO["10Y"].yield) before computing.
- Monitoring: Track latency and error rates per endpoint to tune caching and retries.
FAQ
How are yields expressed?
All yields are percentages (e.g., 4.52 means 4.52%). Spreads from /spread are in basis points (bps).
What timezone are timestamps in?
Date fields are Y-m-d. Intraday timestamps (fetched_at) are ISO 8601 in UTC, with meta.timezone indicating UTC.
How do I handle weekends or holidays in Colombia?
Daily endpoints only include business days. Skip non-trading dates or roll to the previous business day as needed. If you query a non-business date via /historical, handle a 404 gracefully.
Can I request multiple maturities at once?
Yes, /latest supports a comma-separated maturities list. For a full country curve on a consistent date, prefer /curve.
How do I get started?
Get an API key and test the calls with your toolchain. See the Register page and try requests in the MCP.
Build your Colombia fixed-income analytics today. Review the endpoints above, copy the code samples, and Get started with Bonds API using your API key from bonds-api.com.