> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmquantdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 宏观历史时间序列

> 单个美国宏观指标的 latest-vintage 历史时间序列。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`macro_indicator_search` + `macro_indicator_history` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="blue" size="sm">1 credit · history</Badge>
 
<Badge color="gray" size="sm">免费 · search</Badge>

## 它为 Agent 做什么

`macro_indicator_history` 返回单个支持的美国宏观指标（CPI、UNRATE、Fed Funds、10Y 收益率、GDP 等）的 **latest-vintage 历史时间序列** —— 一组 `{ date, value, realtime_start, realtime_end }` observation。它是 agent 的 **宏观时间序列拉取器**：要把过去 5 年通胀画图、要算收益率曲线斜率、要把 observation 喂下游模型时调它。

canonical 的 agent 流程是两步：先调 `macro_indicator_search`（免费）找到正确的 `indicator` alias，再调 `macro_indicator_history` 拉序列。两种查询模式：

* **Recent 模式** —— 传 `limit`（默认 `60`）取最近 N 个 observation。
* **Range 模式** —— 传 `start_date + end_date` 取一个固定窗口。

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: macro_indicator_search(q?, category?, frequency?)
  MCP-->>Agent: items[] · indicator · series_id · frequency · units
  Note over Agent: 选出正确的 alias
  alt 问题是"近期趋势"
    Agent->>MCP: macro_indicator_history(indicator, limit=60)
    MCP-->>Agent: observations[] · date · value · realtime_start
  else 问题是"两个日期之间"
    Agent->>MCP: macro_indicator_history(indicator, start_date, end_date)
    MCP-->>Agent: observations[] · 范围内
  end
  Note over Agent: 画图 / 对比 / 喂下游
```

## 返回值

<ResponseField name="data" type="MacroHistorical" required>
  指标元信息 + observations 数组。

  <Expandable title="MacroHistorical 字段">
    <ResponseField name="indicator" type="string" required>
      回显的平台稳定 alias（如 `us.cpi.headline`）。
    </ResponseField>

    <ResponseField name="series_id" type="string" required>
      Raw series ID（如 `CPIAUCSL`）。
    </ResponseField>

    <ResponseField name="title" type="string" required>
      指标的可读标题。
    </ResponseField>

    <ResponseField name="frequency" type="string" required>
      原生发布频率：`Daily`、`Weekly`、`Monthly`、`Quarterly`、`Annual`。
    </ResponseField>

    <ResponseField name="units" type="string" required>
      单位字符串（如 `Index 1982-1984=100`、`Percent`）。
    </ResponseField>

    <ResponseField name="observations" type="MacroObservation[]" required>
      时间升序的 observation（旧 → 新）。

      <Expandable title="MacroObservation 字段">
        <ResponseField name="date" type="string" required>
          观测期起始日（YYYY-MM-DD）。
        </ResponseField>

        <ResponseField name="value" type="number" nullable>
          上报值。该周期缺失时为 `null`。
        </ResponseField>

        <ResponseField name="realtime_start" type="string" required>
          该值首次发布日（YYYY-MM-DD）。用来识别 revision。
        </ResponseField>

        <ResponseField name="realtime_end" type="string" required>
          该值的有效结束日。当前 latest vintage 通常等于 `realtime_start`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="attribution" type="string" required>
      展示数据时必须保留的署名字符串。
    </ResponseField>

    <ResponseField name="stale" type="boolean" required>
      刷新失败、返回较旧可用数据时为 `true`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `1`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · macro_indicator_history" expandable theme={null}
{
  "data": {
    "indicator": "us.cpi.headline",
    "series_id": "CPIAUCSL",
    "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
    "frequency": "Monthly",
    "units": "Index 1982-1984=100",
    "observations": [
      {
        "date": "2026-01-01",
        "value": 318.412,
        "realtime_start": "2026-02-12",
        "realtime_end": "2026-02-12"
      },
      {
        "date": "2026-02-01",
        "value": 319.082,
        "realtime_start": "2026-03-12",
        "realtime_end": "2026-03-12"
      },
      {
        "date": "2026-03-01",
        "value": 319.799,
        "realtime_start": "2026-04-10",
        "realtime_end": "2026-04-10"
      }
    ],
    "attribution": "Source: U.S. Bureau of Labor Statistics via FRED",
    "stale": false
  },
  "meta": {
    "creditsUsed": 1,
    "remainingCredits": 99
  }
}
```

<Note>
  每条 series 在 `data` 下都带有自己的 `attribution` 字符串（FRED 来源说明）—— 展示数据时请一并呈现。本产品使用 FRED® API，但未经 Federal Reserve Bank of St. Louis 背书或认证。
</Note>

## 说明

<Tip>
  **Revision-aware**：宏观 observation 会被修订。我们返回的是**当前 latest vintage**，不一定是当初首发的值。用 `realtime_start` / `realtime_end` 判断你是不是看到了修订后的版本。暂不支持 as-of vintage 历史回放。
</Tip>

<Tip>
  默认 `limit=60` 大致覆盖月频 5 年、周频 1 年、日频 3 个月。需要更长就提到 `500` 或改用 Range 模式。热门指标重复查询通常更快。
</Tip>

<Warning>
  **Recent 与 Range 模式互斥。** 要么单传 `limit`，要么同时传 `start_date + end_date`。只传一个 date 返回 `400`。
</Warning>

<Warning>
  **仅支持目录内。** 约 50 个精选美国指标，目录之外返回 `404`。用 `macro_indicator_search` 浏览可用列表。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) 找 alias
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_search",
        "arguments": { "q": "cpi", "category": "Inflation" }
      }
    }

    // 2) 取最近的 history（默认 60）
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_history",
        "arguments": { "indicator": "us.cpi.headline", "limit": 60 }
      }
    }

    // 2b) 或取一个明确的日期范围
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_history",
        "arguments": {
          "indicator": "us.cpi.headline",
          "start_date": "2020-01-01",
          "end_date": "2026-03-01"
        }
      }
    }
    ```

    ```python Python (HTTP) theme={null}
    import os, requests

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 1) 找 alias
    catalog = requests.get(
        f"{base}/api/macro/indicators",
        headers=headers,
        params={"q": "cpi", "category": "Inflation"},
    ).json()["data"]

    alias = catalog[0]["indicator"]  # 例如 us.cpi.headline

    # 2) 取最近的 history
    hist = requests.get(
        f"{base}/api/macro/historical",
        headers=headers,
        params={"indicator": alias, "limit": 60},
    ).json()
    for obs in hist["data"]["observations"][-3:]:
        print(obs["date"], obs["value"])
    ```

    ```bash cURL theme={null}
    # 1) 找 alias
    curl "https://api.llmquantdata.com/api/macro/indicators?q=cpi&category=Inflation" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 2) Recent 模式
    curl "https://api.llmquantdata.com/api/macro/historical?indicator=us.cpi.headline&limit=60" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 2b) Range 模式
    curl "https://api.llmquantdata.com/api/macro/historical?indicator=us.cpi.headline&start_date=2020-01-01&end_date=2026-03-01" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<AccordionGroup>
  <Accordion title="macro_indicator_search — 请求参数" icon="magnifying-glass">
    <ParamField query="q" type="string">
      自由文本关键词，匹配 indicator alias、指标标题、`series_id`。
    </ParamField>

    <ParamField query="category" type="string">
      按主题过滤（`Inflation`、`Rates`、`Labor`、`Growth`、`Housing`、`Liquidity`、`Conditions`、`FX`、`Credit`、`Sentiment`、`Energy`、`Inflation Expectations`、`Consumption`）。
    </ParamField>

    <ParamField query="frequency" type="string">
      按发布频率过滤（`Daily`、`Weekly`、`Monthly`、`Quarterly`、`Annual`）。
    </ParamField>

    <ParamField query="limit" type="number" default={20}>
      返回上限。范围 `1–100`。
    </ParamField>
  </Accordion>

  <Accordion title="macro_indicator_history — 请求参数" icon="chart-line">
    <ParamField query="indicator" type="string">
      平台 alias（如 `us.cpi.headline`、`us.rates.fed_funds`）。与 `series_id` **二选一**。
    </ParamField>

    <ParamField query="series_id" type="string">
      Raw series ID（如 `CPIAUCSL`）。与 `indicator` **二选一**。必须在支持目录内。
    </ParamField>

    <ParamField query="start_date" type="string">
      Range 模式。ISO 日期 `YYYY-MM-DD`。必须与 `end_date` 同时使用。
    </ParamField>

    <ParamField query="end_date" type="string">
      Range 模式。ISO 日期 `YYYY-MM-DD`。必须与 `start_date` 同时使用。
    </ParamField>

    <ParamField query="limit" type="number" default={60}>
      Recent 模式返回条数。范围 `1–500`。Range 模式下被忽略。
    </ParamField>
  </Accordion>
</AccordionGroup>

## 相关接口

<Columns cols={2}>
  <Card title="宏观指标目录" icon="landmark" href="/zh-CN/api/macro/indicators">
    浏览约 50 个精选指标目录（免费）。
  </Card>

  <Card title="宏观指标快照" icon="gauge-high" href="/zh-CN/api/macro/snapshot">
    只看最新值 + 涨跌（不返回完整序列）。
  </Card>
</Columns>