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

# 网站 URL 地图与 sitemap API（WEB_MAP）

> 从起始页链接和 sitemap 列出站点的地址，并按路径过滤。

`WEB_MAP` 列出站点的地址，但不读取其内容。一个任务会读取起始页上的链接、`robots.txt` 中列出的 sitemap（未列出时读取 `/sitemap.xml` 和 `/sitemap_index.xml`），以及这些 sitemap。可用它挑选要用 [`WEB_SCRAPE`](/zh/engines/web-scrape) 读取的页面，或限定 [`WEB_CRAWL`](/zh/engines/web-crawl) 的范围。

| | |
| - | - |
| `taskType` | `WEB_MAP` |
| 输入 | `url`（必填）；`limit`、`includePaths`、`excludePaths`、`includeSubdomains`、`country` |
| 积分 | 每个任务 1 积分 |
| 国家 | 默认 `US`。 |
| 位置 | 不支持（`422 LOCATION_UNSUPPORTED`）。 |

## 请求

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "WEB_MAP", "payload": { "url": "https://www.example.com", "limit": 500, "includePaths": ["/blog/**"] } }'
```

## 参数

| 字段 | 必填 | 说明 |
| - | - | - |
| `url` | 是 | 站点的起始地址。规则与 `WEB_SCRAPE` 相同：公开的 `http` 或 `https`、默认端口、最长 2,048 个字符。 |
| `limit` | 否 | 返回的地址数，1 到 10,000 的整数，默认 1,000。 |
| `includePaths` | 否 | 只保留路径匹配其中某个模式的地址。最多 20 个模式，每个以 `/` 开头，最长 200 个字符。 |
| `excludePaths` | 否 | 去掉路径匹配其中某个模式的地址。限制相同。`excludePaths` 优先于 `includePaths`。 |
| `includeSubdomains` | 否 | 设为 `true` 时加入站点的子域名，默认 `false`。 |
| `country` | 否 | 请求站点时使用的地区，默认 `US`。 |

在模式中，`*` 在一个路径段内匹配，`**` 跨多个路径段匹配；其他字符都匹配其自身。`/blog/**` 也匹配 `/blog`。路径按百分号解码后匹配。

站点是起始地址经重定向后到达的主机，带不带 `www.` 视为同一站点。

## 响应

例如：

```json theme={"theme":"css-variables"}
{
  "url": "https://www.example.com",
  "urls": [
    { "url": "https://www.example.com/", "source": "page" },
    { "url": "https://www.example.com/blog/launch", "source": "sitemap", "lastmod": "2026-10-01" }
  ],
  "sitemaps": ["https://www.example.com/sitemap.xml"],
  "truncated": false
}
```

| 字段 | 说明 |
| - | - |
| `url` | 你发送的起始地址。 |
| `urls` | 先是起始页，再是其上的链接，然后是 sitemap 条目。每个地址只出现一次，并去掉片段和追踪参数（`utm_*`、`gclid`、`fbclid` 等）。 |
| `urls[].source` | 起始页上的链接为 `page`，sitemap 条目为 `sitemap`。 |
| `urls[].lastmod` | sitemap 提供的最后修改日期（如有）。 |
| `sitemaps` | 读取过的 sitemap 文件，按读取顺序排列。 |
| `truncated` | 列表在站点地址穷尽之前停止时为 `true`：达到 `limit`、达到 50 个 sitemap 文件上限，或用完 90 秒时间预算。 |

## 限制与错误

* 没有地址匹配 `includePaths` 和 `excludePaths`，或起始页无法读取且站点没有列出 sitemap 时，任务以 `PAGE_UNAVAILABLE` 失败。
* 无效选项返回 `422 VALIDATION_ERROR`，并指出相应字段。
* `WEB_MAP` 忽略 `markdown`、`rawResponse` 和 `searchQueries`。它以 `422` 拒绝 `html` 和 `analysis`，以 `400` 拒绝 `citationAnalysis`；见[不支持的标志](/zh/engines/response-options.md#不支持的标志)。
* 其他请求错误见[错误](/zh/concepts/errors.md)。

## 相关内容

* [网站爬取](/zh/engines/web-crawl.md)：以 Markdown 读取这些页面
* [网页抓取](/zh/engines/web-scrape.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.