Fetching a Government Bond Curve

Use the /gov_yield endpoint to retrieve government bond yields and construct yield curves for risk-free rate benchmarking.

Government bond yield curves show the relationship between yields and maturities for sovereign debt. They're commonly used as:

• Risk-free rate benchmarks for discounting and valuation

• Credit spread references (e.g., calculating swap spreads over treasuries)

• Economic indicators (curve shape signals market expectations)

---

Example: US Treasury Curve

Fetch yields across multiple tenors to construct the full curve using the /gov_yield endpoint:

import requests

url = "https://api.bluegamma.io/v1/gov_yield"
headers = {"x-api-key": "your_api_key_here"}

tenors = ["1Y", "2Y", "3Y", "5Y", "7Y", "10Y", "20Y", "30Y"]
curve_data = []

for tenor in tenors:
    params = {
        "country_code": "US",
        "maturity": tenor
    }
    response = requests.get(url, headers=headers, params=params)
    data = response.json()
    curve_data.append({
        "tenor": tenor,
        "yield": data["yield"] * 100  # Convert to percentage
    })

for point in curve_data:
    print(f"{point['tenor']}: {point['yield']:.2f}%")

Tip: The maturity parameter accepts both tenors (e.g., "5Y", "10Y") and specific dates (e.g., "2030-06-15"). Use dates when you need the yield for a bond maturing on an exact date.

Example Output:

1Y: 3.55%
2Y: 3.54%
3Y: 3.56%
5Y: 3.73%
7Y: 3.95%
10Y: 4.19%
20Y: 4.98%
30Y: 4.96%

---

Understanding the Response

Each API call returns:

{
  "country_code": "US",
  "maturity": "2035-12-11",
  "forward_start": "2025-12-11",
  "valuation_time": "2025-12-11T09:44:21.413045",
  "yield": 0.04188022272897296
}

Field	Description
country_code	ISO country code (e.g., "US", "UK", "DE")
maturity	The resolved maturity date
forward_start	Start date for the yield calculation (spot by default)
valuation_time	Timestamp of the market data used
yield	The zero-coupon yield as a decimal (multiply by 100 for percentage)

---

Visualizing the Curve

US Treasury yield curve showing yields across maturities

💡 Note: The shape of the yield curve provides economic insights. An upward-sloping curve (as shown) is typical, indicating higher yields for longer maturities. An inverted curve can signal recession expectations.

---

Historical Government Bond Yields

Add valuation_time to fetch yields as of a specific historical date:

params = {
    "country_code": "US",
    "maturity": "10Y",
    "valuation_time": "2024-06-15T16:00:00Z"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

---

Forward-Starting Bond Yields

Use forward_start to get yields for bonds starting at a future date:

params = {
    "country_code": "US",
    "maturity": "10Y",
    "forward_start": "1Y"  # Yield for a 10Y bond, 1 year forward
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

---

Available Government Bond Curves

Country Code	Description	Currency
US	US Treasury yields	USD
UK	UK Gilt yields	GBP
DE	German Bund yields	EUR
FR	French OAT yields	EUR
IT	Italian BTP yields	EUR
ES	Spanish Bonos yields	EUR
JP	Japanese Government Bond yields	JPY
CA	Canadian Government Bond yields	CAD
AU	Australian Government Bond yields	AUD

---

Complete Example: Building a Treasury Curve DataFrame

import requests
import pandas as pd

url = "https://api.bluegamma.io/v1/gov_yield"
headers = {"x-api-key": "your_api_key_here"}

tenors = ["1Y", "2Y", "3Y", "5Y", "7Y", "10Y", "20Y", "30Y"]
data = []

for tenor in tenors:
    response = requests.get(url, headers=headers, params={
        "country_code": "US",
        "maturity": tenor
    })
    result = response.json()
    data.append({
        "tenor": tenor,
        "maturity_date": result["maturity"],
        "yield_pct": result["yield"] * 100
    })

df = pd.DataFrame(data)
print(df.to_string(index=False))

Output:

tenor maturity_date  yield_pct
   1Y    2026-12-11       3.55
   2Y    2027-12-13       3.54
   3Y    2028-12-11       3.56
   5Y    2030-12-11       3.73
   7Y    2032-12-13       3.95
  10Y    2035-12-11       4.19
  20Y    2045-12-11       4.98
  30Y    2055-12-13       4.96

---

Key Conventions

Government bond yields in BlueGamma use the following conventions:

• Compounding: Semi-annual (for US Treasuries)

• Day Count: Actual/Actual ISMA

• Output: Zero-coupon yields

📘 For more details on methodology, see How do you construct your govt. bond yield curves?