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

# 宏观指标快照

> 单个美国宏观指标的最新值 + 前值 + 涨跌。

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

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="gray" size="sm">免费 · latest</Badge>

## 它为 Agent 做什么

`macro_indicator_snapshot` 返回某个美国宏观指标的**最新 observation**，加上**前值**和两者的**差值**。它是 agent 的 **宏观 checkpoint**：要回答 "现在联邦基金利率多少？"、"失业率比上月升了还是降了？"、"当前宏观 regime 是什么？" 时，不需要拉完整序列，调它一次就够。

`macro_indicator_snapshot({ indicator })` → `latest`、`previous`、`delta_abs`、`delta_pct`。仅此而已。要完整时间序列，请用 [`macro_indicator_history`](/zh-CN/api/macro/historical)。

## 返回值

<ResponseField name="data" type="MacroSnapshot" required>
  <Expandable title="MacroSnapshot 字段">
    <ResponseField name="indicator" type="string" required>
      平台稳定 alias（如 `us.rates.fed_funds`）。
    </ResponseField>

    <ResponseField name="series_id" type="string" required>
      Raw series ID（如 `FEDFUNDS`）。
    </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>
      单位字符串（如 `Percent`、`Index 1982-1984=100`）。
    </ResponseField>

    <ResponseField name="latest" type="object" nullable required>
      最新 observation。还没有可用数据时为 `null`。

      <Expandable title="latest 字段">
        <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>该值首次发布日。</ResponseField>
        <ResponseField name="realtime_end" type="string" required>该值有效结束日。</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="previous" type="object" nullable required>
      前一笔 observation。只有一笔时为 `null`。

      <Expandable title="previous 字段">
        <ResponseField name="date" type="string" required>前值观测日期。</ResponseField>
        <ResponseField name="value" type="number" nullable>前值。</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="delta_abs" type="number" nullable required>
      `latest.value − previous.value`。任何一边缺失时为 `null`。
    </ResponseField>

    <ResponseField name="delta_pct" type="number" nullable required>
      相对前值的百分比变化（即 `delta_abs / previous.value * 100`）。任一边缺失或前值为 `0` 时为 `null`。
    </ResponseField>

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

<ResponseField name="meta.creditsUsed" type="number">固定 `0` —— 本接口免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · macro_indicator_snapshot" expandable theme={null}
{
  "data": {
    "indicator": "us.unemployment_rate",
    "series_id": "UNRATE",
    "title": "Unemployment Rate",
    "frequency": "Monthly",
    "units": "Percent",
    "latest": {
      "date": "2026-03-01",
      "value": 4.1,
      "realtime_start": "2026-04-04",
      "realtime_end": "2026-04-04"
    },
    "previous": {
      "date": "2026-02-01",
      "value": 4.0
    },
    "delta_abs": 0.1,
    "delta_pct": 2.5,
    "attribution": "Source: U.S. Bureau of Labor Statistics via FRED"
  },
  "meta": {
    "creditsUsed": 0,
    "remainingCredits": 99
  }
}
```

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

## 说明

<Tip>
  **Revision-aware**：snapshot 返回的是**当前 latest vintage** —— 不是当初首发的值。如果最近一笔被修订，你看到的是修订后的值。看 `latest.realtime_start` 可以判断该值最后发布于哪天。
</Tip>

<Tip>
  snapshot 比 `macro_indicator_history` 返回的 token 体量小得多，而且本接口免费。当 agent 只关心 "当前是多少" 时用 snapshot，不需要序列。
</Tip>

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

<Warning>
  按频率刷新：日频/周频指标 24h 内更新；月频/季频 7 天内更新。snapshot 可能比当前最新发布滞后几个小时。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_snapshot",
        "arguments": { "indicator": "us.unemployment_rate" }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/macro/snapshot",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"indicator": "us.unemployment_rate"},
    ).json()
    d = resp["data"]
    print(f"{d['indicator']}: {d['latest']['value']}{d['units'][:1]} "
          f"({d['delta_abs']:+.2f} vs prev)")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/macro/snapshot?indicator=us.unemployment_rate" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

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

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

## 相关接口

<Columns cols={2}>
  <Card title="宏观历史时间序列" icon="chart-line" href="/zh-CN/api/macro/historical">
    同一指标的完整 latest-vintage 时间序列（Recent 或 Range 模式）。
  </Card>

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