> For the complete documentation index, see [llms.txt](https://bluegamma.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluegamma.io/documentation/integrations/api/how-to-guides/fetching-a-government-bond-curve.md).

# Fetching a Government Bond Curve

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:

```python
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}%")
```

```bash
# Example for a single tenor (repeat for each tenor)
curl -X GET "https://api.bluegamma.io/v1/gov_yield?country_code=US&maturity=10Y" \
  -H "x-api-key: your_api_key_here"
```

{% hint style="info" %}
**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.
{% endhint %}

**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:

```json
{
  "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

<figure><img src="/files/YlgI3HQz63Iw2JddmaZw" alt="US Treasury Yield Curve"><figcaption><p>US Treasury yield curve showing yields across maturities</p></figcaption></figure>

> 💡 **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.

{% hint style="success" %}
**Need bond yields for your models?** Get an API key and start pulling live data. [Book a demo →](https://app.lemcal.com/@alivohra/website-demo?back=1)
{% endhint %}

***

## Historical Government Bond Yields

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

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

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

```bash
curl -X GET "https://api.bluegamma.io/v1/gov_yield?country_code=US&maturity=10Y&valuation_time=2024-06-15T16%3A00%3A00Z" \
  -H "x-api-key: your_api_key_here"
```

***

## Forward-Starting Bond Yields

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

```python
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())
```

```bash
curl -X GET "https://api.bluegamma.io/v1/gov_yield?country_code=US&maturity=10Y&forward_start=1Y" \
  -H "x-api-key: your_api_key_here"
```

***

## 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

```python
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))
```

```bash
# Example for a single tenor (repeat for each tenor)
curl -X GET "https://api.bluegamma.io/v1/gov_yield?country_code=US&maturity=10Y" \
  -H "x-api-key: your_api_key_here"
```

**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 [Government Bond Curves](/documentation/methodology/government-bond-curves.md)

***

**Need an API key?**\
📩 <support@bluegamma.io> | 📅 [Book a call](https://app.lemcal.com/@alivohra/website-demo?back=1)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bluegamma.io/documentation/integrations/api/how-to-guides/fetching-a-government-bond-curve.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.