You need high-quality, machine-readable yields for Colombia’s sovereign bond curve and spreads so you can power screens, models, and dashboards. By the end of this post, you’ll know how to retrieve the latest Colombian yields, build a full curve, calculate US–Colombia spreads, fetch intraday snapshots, and analyze historical behavior using the Bonds API over simple GET requests.
What you’ll build with Colombia’s sovereign yields
Colombian government bonds (TES) provide a term structure of interest rates that underpins asset pricing, risk, and macro analysis for COP-denominated markets. With bonds-api.com, you can fetch:
- Latest yields for specific maturities to drive dashboards and alerts.
- Historical and time-series context for models and backtests.
- Full yield curves to interpolate zero rates or price cash flows.
- Spreads versus benchmarks (e.g., US Treasuries) in basis points.
- Intraday snapshots for day-of monitoring.
- Fluctuation summaries for min/max/changes across a period.
All endpoints are GET requests under the same base URL and authenticated with an API key header. You can explore the API surface in the MCP or review the docs and start integrating at bonds-api.com.
Authentication, base URL, and conventions
All endpoints use:
- Base URL: https://bonds-api.com/api/v1/
- HTTP method: GET
- Header: X-API-Key: YOUR_API_KEY
Conventions used by the API in this article:
- Yields are expressed in percentage terms (e.g., 4.52 means 4.52%).
- Spreads are expressed in basis points (bps), where 1 bp = 0.01%.
- Dates are ISO-8601 in Y-m-d format (e.g., 2026-10-27).
- Timestamps (e.g., fetched_at) are in UTC.
Hint: Cache responses for intraday reuse and respect business days—markets close on weekends and local holidays, so daily series will show gaps on non-trading days.
Live sample block (verbatim)
The following live sample must be copied exactly as provided. It uses a US example and an api_key query parameter 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-27",
"rates": {
"US_10Y": 4.992
},
"dates": {
"US_10Y": "2026-10-27"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "0440bc9e-bfd5-4155-a217-c4a40f519740",
"timestamp": "2026-10-27T00:04:05+00:00"
}
}
Latest yields for Colombia (GET /latest)
Fetch current yields for Colombia (ISO2: CO). You can request specific maturities or omit the maturities parameter to return all available points.
cURL
Python (requests)
import requests
response = requests.get(
'https://bonds-api.com/api/v1/latest',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'countries': 'CO', 'maturities': '2Y,10Y'}
)
data = response.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_2y, 'CO 10Y:', co_10y, 'as of', co_date)
JavaScript (fetch)
const url = new URL('https://bonds-api.com/api/v1/latest');
url.searchParams.set('countries', 'CO');
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 co = json.data.CO;
console.log('CO 2Y %', co['2Y'].yield, 'CO 10Y %', co['10Y'].yield, 'date', co['10Y'].date);
});
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=CO&maturities=2Y,10Y';
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$co2y = $data['data']['CO']['2Y']['yield'];
$co10y = $data['data']['CO']['10Y']['yield'];
echo "CO 2Y: $co2y, CO 10Y: $co10y\n";
JSON response (fields)
How to read it:
- yield: percentage (e.g., 4.52 = 4.52%).
- date: the valuation date (Y-m-d) for these official end-of-day yields.
- source: data provenance tag.
Yield on a specific date (GET /historical)
Use this to pull a single historical observation for Colombia at a given maturity and date.
cURL
Python (requests)
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)
hist = r.json()
print(hist['country'], hist['maturity'], hist['date'], hist['yield'])
JavaScript (fetch)
const params = new URLSearchParams({country: 'CO', maturity: '10Y', date: '2025-06-15'});
fetch('https://bonds-api.com/api/v1/historical?' + params.toString(), {
headers: {'X-API-Key': 'YOUR_API_KEY'}
}).then(r => r.json()).then(json => {
console.log(json.country, json.maturity, json.date, json.yield);
});
PHP (file_get_contents)
<?php
$query = http_build_query(['country' => 'CO', 'maturity' => '10Y', 'date' => '2025-06-15']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents('https://bonds-api.com/api/v1/historical?' . $query, false, $ctx);
echo $json;
JSON response (fields)
Fields:
- yield: percent on that calendar date (if it’s a non-trading day, data refers to the last available business day).
- source: provenance of the reading.
Time series between two dates (GET /timeseries)
Pull a daily series for Colombia across a date range to run regressions, signals, or charting.
cURL
Python (requests)
import requests
params = {
'country': 'CO',
'maturity': '10Y',
'start': '2025-10-27',
'end': '2026-10-27'
}
ts = requests.get('https://bonds-api.com/api/v1/timeseries',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params).json()
series = ts['series'] # list of {date, yield}
print('Observations:', len(series), 'First:', series[0])
JavaScript (fetch)
const qs = new URLSearchParams({
country: 'CO', maturity: '10Y', start: '2025-10-27', end: '2026-10-27'
});
fetch('https://bonds-api.com/api/v1/timeseries?' + qs.toString(), {
headers: {'X-API-Key': 'YOUR_API_KEY'}
}).then(r => r.json()).then(json => {
json.series.forEach(pt => console.log(pt.date, pt.yield));
});
PHP (file_get_contents)
<?php
$params = http_build_query([
'country' => 'CO',
'maturity' => '10Y',
'start' => '2025-10-27',
'end' => '2026-10-27'
]);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/timeseries?' . $params, false, $ctx);
JSON response (fields)
Notes:
- series: ordered daily readings (business days; weekends/holidays are absent).
- Use the range to compute average yield, realized volatility, or rolling regressions.
Spread versus US benchmark (GET /spread)
Compute Colombia’s yield spread vs. a benchmark (e.g., US Treasuries). The default maturity is 10Y; specify maturity to change it.
cURL
Python (requests)
import requests
params = {'country': 'CO', 'benchmark': 'US', 'maturity': '10Y'}
sp = requests.get('https://bonds-api.com/api/v1/spread',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params).json()
print('Spread (bps):', sp['spread_bps'])
print('CO %:', sp['country_yield'], 'US %:', sp['benchmark_yield'])
JavaScript (fetch)
const s = new URLSearchParams({ country: 'CO', benchmark: 'US', maturity: '10Y' });
fetch('https://bonds-api.com/api/v1/spread?' + s.toString(), {
headers: {'X-API-Key': 'YOUR_API_KEY'}
}).then(r => r.json()).then(json => {
console.log('Spread bps', json.spread_bps, 'CO', json.country_yield, 'US', json.benchmark_yield);
});
PHP (file_get_contents)
<?php
$q = http_build_query(['country' => 'CO', 'benchmark' => 'US', 'maturity' => '10Y']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/spread?' . $q, false, $ctx);
JSON response (fields)
Interpretation:
- spread_bps: Colombia minus benchmark in basis points (215 bps = 2.15%).
- country_yield, benchmark_yield: both in percent.
Full Colombia yield curve (GET /curve)
Fetch the full Colombian term structure for the latest available date or a requested date. This is the fastest way to render a curve or to interpolate a zero-coupon curve offline.
cURL
Python (requests)
import requests
curve = requests.get('https://bonds-api.com/api/v1/curve',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'CO'}).json()
date = curve['date']
points = curve['curve'] # dict of maturity -> yield (%)
print('Curve date:', date)
for mat, y in points.items():
print(mat, y)
JavaScript (fetch)
const u = new URL('https://bonds-api.com/api/v1/curve');
u.searchParams.set('country', 'CO');
fetch(u.toString(), { headers: { 'X-API-Key': 'YOUR_API_KEY' }})
.then(r => r.json())
.then(json => {
console.log('Date', json.date, 'Inverted?', json.inverted);
Object.entries(json.curve).forEach(([mat, y]) => console.log(mat, y));
});
PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents('https://bonds-api.com/api/v1/curve?country=CO', false, $ctx);
echo $json;
JSON response (fields)
Fields:
- curve: maturity to yield mapping (percent). Use as-is for quick charts or feed to your fitting routines.
- inverted: boolean indicator if shorter maturities exceed longer ones.
Intraday snapshots (GET /intraday)
Monitor Colombia’s yield across the trading day at a chosen maturity. Timestamps are in UTC.
cURL
Python (requests)
import requests
params = {'country': 'CO', 'maturity': '10Y', 'date': '2026-10-27'}
r = requests.get('https://bonds-api.com/api/v1/intraday',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params)
snap = r.json()
for s in snap['snapshots']:
print(s['fetched_at'], s['yield'])
JavaScript (fetch)
const q = new URLSearchParams({country: 'CO', maturity: '10Y', date: '2026-10-27'});
fetch('https://bonds-api.com/api/v1/intraday?' + q.toString(), {
headers: {'X-API-Key': 'YOUR_API_KEY'}
}).then(r => r.json()).then(json => {
console.log('Count', json.count, 'TZ', json.meta.timezone);
json.snapshots.forEach(s => console.log(s.fetched_at, s.yield));
});
PHP (file_get_contents)
<?php
$p = http_build_query(['country' => 'CO', 'maturity' => '10Y', 'date' => '2026-10-27']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/intraday?' . $p, false, $ctx);
JSON response (fields)
Fields:
- snapshots: sequence of yield prints during the day.
- fetched_at: ISO-8601 UTC timestamps.
- count: number of intraday points returned.
Fluctuation summary (GET /fluctuation)
Summarize the change, min, and max over a period. This is useful for risk and performance reports.
cURL
Python (requests)
import requests
params = {'countries': 'CO', 'maturity': '10Y', 'start': '2025-10-27', 'end': '2026-10-27'}
fl = requests.get('https://bonds-api.com/api/v1/fluctuation',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params).json()
co = fl['data']['CO']
print('Δ (pct pts):', co['change'], 'min:', co['min'], 'max:', co['max'])
JavaScript (fetch)
const params = new URLSearchParams({
countries: 'CO', maturity: '10Y', start: '2025-10-27', end: '2026-10-27'
});
fetch('https://bonds-api.com/api/v1/fluctuation?' + params.toString(), {
headers: {'X-API-Key': 'YOUR_API_KEY'}
}).then(r => r.json()).then(json => {
const co = json.data.CO;
console.log('Start', co.start_yield, 'End', co.end_yield, 'Change', co.change);
});
PHP (file_get_contents)
<?php
$p = http_build_query([
'countries' => 'CO', 'maturity' => '10Y', 'start' => '2025-10-27', 'end' => '2026-10-27'
]);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/fluctuation?' . $p, false, $ctx);
JSON response (fields)
Fields:
- change: end_yield - start_yield (percentage points).
- min, max: extrema over the range (percent).
Building a Colombia yield curve in practice
There are two common ways to assemble a curve:
- Single-call approach: GET /curve with country=CO for a ready-to-plot curve object (1M…30Y).
- Multi-maturity approach: GET /latest with countries=CO and maturities spanning your target pillars (e.g., 1Y,2Y,5Y,10Y,30Y) to maintain fine-grained control over which points you fit.
The /curve endpoint is efficient when you need a canonical term structure for the latest date, and the response includes an inverted flag to quickly identify curve inversions. If you need an as-of date, specify date=Y-m-d on /curve to stay consistent across backtests or valuation batches.
Recommendations:
- Interpolate between adjacent maturities for continuous curves. Cubic splines or monotone convex fits can preserve arbitrage-free shapes.
- Cache the full curve per business day; refresh once daily after local market close to minimize latency and redundant calls.
- If you compute spreads to US Treasuries, retrieve Colombia curve via /curve and the US leg via /curve or use /spread per maturity when you only need point spreads.
Operational details that save time
- Business days and holidays: Colombia and the US observe different holidays; you may see different data availability by date. Handle missing days by forward-filling or skipping non-business days in analytics.
- Update cadence: End-of-day official yields update once per business day; intraday snapshots provide within-day prints with UTC timestamps.
- Caching: Cache GET responses keyed by endpoint and query params. For time series windows that don’t change (e.g., historical research), set long TTLs.
- Throttling and retries: If you receive 429 (rate limit exceeded), back off and retry with exponential delays. Avoid tight polling; use intraday endpoints for within-day needs.
- Error handling: Uniform error schema with success=false and error string. Watch for HTTP 401 (invalid key), 403 (quota), 404 (no data for selection), 422 (invalid parameters), and 500 (server error).
Error responses and handling
Every endpoint returns a consistent error shape.
- 401: Missing or invalid X-API-Key — confirm your header and key value.
- 403: Account quota exceeded — reduce frequency or wait before retrying.
- 404: No data — check country ISO2 code (CO), maturity, or date.
- 422: Invalid parameter — ensure dates are Y-m-d and maturities are valid (e.g., 2Y, 10Y).
- 429: Rate limit exceeded — implement retry with backoff.
- 500: Server error — log request and retry later.
Use cases for developers and quants
- Portfolio risk: Pull /timeseries for 2Y and 10Y to compute sensitivities and historical VaR drivers.
- Macro monitors: Use /curve daily to track steepening/flattening; alert on inverted=true.
- Relative value: Compare Colombia versus US using /spread for point-in-time basis or run panel analysis across horizons.
- Trader dashboards: Stream /intraday for the 10Y to monitor live moves and liquidity windows.
- Backtests: Use /historical to lock in as-of dates for reproducibility.
Explore endpoints interactively in the MCP and review integration tips at bonds-api.com.
Field units and timestamps recap
- yield: percent (e.g., 4.52 = 4.52%).
- spread_bps: basis points (1 bp = 0.01%).
- date: Y-m-d (local market day reference for the yield observation).
- fetched_at: timestamp in UTC for intraday snapshots.
FAQ
Q: How do I build a Colombia 10Y vs US 10Y daily spread series?
A: Loop over business days and call /spread with country=CO, benchmark=US, maturity=10Y, or compute the difference from two /timeseries pulls if you prefer full control over both legs.
Q: What maturity codes are supported?
A: Use standard codes like 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, 30Y. The /curve endpoint returns available pillars; /latest with maturities lets you request specific points.
Q: How should I handle non-trading days?
A: Expect gaps on weekends and Colombian market holidays. For analytics requiring uniform spacing, forward-fill the last available business-day value or restrict to business-day indices.
Q: In what unit is the spread returned?
A: spread_bps is in basis points. For example, 215 means 2.15% (0.0215 in decimal).
Q: Can I request the Colombia curve for a past date?
A: Yes, pass date=Y-m-d to /curve with country=CO to retrieve the curve snapshot for that day.
Ship your Colombia yield curve integration now. Generate an API key and start testing in minutes: Register. If you prefer to explore interactively first, open the MCP.