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

# 宏观指标目录

> 浏览或搜索支持的美国宏观指标目录（约 50 个）。

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

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

## 它为 Agent 做什么

`macro_indicator_search` 返回 LLMQuant Data **支持的约 50 个美国宏观指标目录** —— 通胀（CPI / PCE）、利率（联邦基金利率、国债收益率）、就业（失业率、非农）、增长（GDP）、住房、流动性（M2、Fed 资产负债表）、金融条件、汇率等。它是 agent 的 **catalog discovery 入口**：在调用 `macro_indicator_history` / `macro_indicator_snapshot` 之前，先用它通过 `category`、`frequency` 或自由文本关键词浏览目录，确定要用哪个 `indicator` alias 或 `series_id`。

它**不**暴露所有可能的宏观 series —— 只返回精选、已澄清署名的支持目录。不传任何参数 = 列出全部。

## 返回值

<ResponseField name="data" type="MacroIndicatorCatalogItem[]" required>
  Curated catalog 条目，每条对应一个支持的指标。

  <Expandable title="MacroIndicatorCatalogItem 字段">
    <ResponseField name="indicator" type="string" required>
      平台稳定 alias。传给 `macro_indicator_history` / `macro_indicator_snapshot`（如 `us.cpi.headline`、`us.rates.fed_funds`）。
    </ResponseField>

    <ResponseField name="series_id" type="string" required>
      Raw series ID（如 `CPIAUCSL`、`FEDFUNDS`）。history/snapshot 工具同样接收。
    </ResponseField>

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

    <ResponseField name="category" type="string" required>
      主题分类：`Growth`、`Consumption`、`Inflation`、`Labor`、`Housing`、`Rates`、`Inflation Expectations`、`Liquidity`、`Conditions`、`FX`、`Credit`、`Sentiment`、`Energy`。
    </ResponseField>

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

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

    <ResponseField name="observation_start" type="string" required>
      当前可用的最早 observation 日期（YYYY-MM-DD）。
    </ResponseField>

    <ResponseField name="observation_end" type="string" required>
      当前可用的最近 observation 日期（YYYY-MM-DD）。
    </ResponseField>

    <ResponseField name="copyright_status" type="string" required>
      `Public Domain: Citation requested` 或 `Copyrighted: Citation required`。`Pre-approval required` 的 series 不会出现。
    </ResponseField>

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

<ResponseField name="meta.creditsUsed" type="number">固定 `0`，catalog 浏览免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">本次调用后余额剩余的 credits。</ResponseField>

```json title="200 OK · macro_indicator_search" 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",
      "category": "Inflation",
      "frequency": "Monthly",
      "units": "Index 1982-1984=100",
      "observation_start": "1947-01-01",
      "observation_end": "2026-03-01",
      "copyright_status": "Public Domain: Citation requested",
      "attribution": "Source: U.S. Bureau of Labor Statistics via FRED"
    },
    {
      "indicator": "us.unemployment_rate",
      "series_id": "UNRATE",
      "title": "Unemployment Rate",
      "category": "Labor",
      "frequency": "Monthly",
      "units": "Percent",
      "observation_start": "1948-01-01",
      "observation_end": "2026-03-01",
      "copyright_status": "Public Domain: Citation requested",
      "attribution": "Source: U.S. Bureau of Labor Statistics via FRED"
    }
  ],
  "meta": {
    "creditsUsed": 0,
    "remainingCredits": 500
  }
}
```

<Note>
  每条 catalog 条目在 `data` 里自带 `attribution` 来源说明（FRED 署名）—— 展示数据时一并显示。本目录使用 FRED® API，但未获 Federal Reserve Bank of St. Louis 背书或认证。
</Note>

## 说明

<Tip>
  **两步检索**：先调 `macro_indicator_search`（免费）确定 alias，再调 `macro_indicator_history`（1 credit）取时间序列，或 `macro_indicator_snapshot`（免费）取最新值。catalog 不消耗 credit，可以放心多调几次。
</Tip>

<Tip>
  优先用平台 `indicator` alias（`us.cpi.headline`），不要用裸 `series_id`（`CPIAUCSL`）—— alias 在 raw series 命名变化时仍然稳定，agent trace 里也更清晰。
</Tip>

<Warning>
  **仅支持目录内。** 大约 50 个美国宏观 series。目录之外的 `series_id` 返回 `404`。需要的指标不在列表里，请提 issue。
</Warning>

<Warning>
  catalog 行**不是实时**：`observation_end` 反映 LLMQuant Data 当前可用的最后已知发布时间，不一定是今天。
</Warning>

## 直接调用

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

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/macro/indicators",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"category": "Inflation", "limit": 10},
    ).json()
    for item in resp["data"]:
        print(f"{item['indicator']}  ({item['series_id']})  {item['frequency']}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/macro/indicators?category=Inflation&limit=10" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

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

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

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

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

## 相关接口

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

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