# Map (/zh/features/map)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 2085 · updated: 2026-07-30 -->
Related: [搜索](/zh/features/search.md), [搜索高亮](/zh/features/search-highlights.md), [研究索引](/zh/features/research.md), [抓取](/zh/features/scrape.md), [更快的抓取](/zh/features/fast-scraping.md), [批量抓取](/zh/features/batch-scrape.md)

<div id="introducing-map">
  ## 介绍 /map [#介绍-map]
</div>

从单个 URL 快速生成整站链接地图的最简方式。这在以下场景特别有用：

* 需要让终端用户选择要抓取的链接时
* 需要快速了解网站包含哪些链接
* 需要抓取与特定主题相关的页面 (使用 `search` 参数)
* 只需抓取网站中的特定页面

<Card title="在 Playground 中试用" icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M18.8906 12.846C18.5371 14.189 16.8667 15.138 13.5257 17.0361C10.296 18.8709 8.6812 19.7884 7.37983 19.4196C6.8418 19.2671 6.35159 18.9776 5.95624 18.5787C5 17.6139 5 15.7426 5 12C5 8.2574 5 6.3861 5.95624 5.42132C6.35159 5.02245 6.8418 4.73288 7.37983 4.58042C8.6812 4.21165 10.296 5.12907 13.5257 6.96393C16.8667 8.86197 18.5371 9.811 18.8906 11.154C19.0365 11.7084 19.0365 12.2916 18.8906 12.846Z&#x22; stroke=&#x22;currentColor&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" href="https://www.firecrawl.dev/playground?endpoint=map">
  在交互式 Playground 中测试映射功能——无需写代码。
</Card>

<div id="mapping">
  ## 映射 [#映射]
</div>

<div id="map-endpoint">
  ### /map 端点 [#map-端点]
</div>

用于映射一个 URL 并获取该网站的 URL。会返回站点上大部分的链接。

URL 主要从网站的 sitemap 中获取，并辅以 SERP (搜索引擎结果页) 结果和之前抓取的页面，以提升覆盖率。你可以使用 `sitemap` 参数来控制 sitemap 的行为。

<div id="installation">
  ### 安装 [#安装]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="cli+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="CLI">
        CLI
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      # 使用 pip 安装 firecrawl-py

      from firecrawl import Firecrawl

      firecrawl = Firecrawl(
        # 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：
        # api_key="fc-YOUR-API-KEY",
      )
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      // 使用 npm 安装 firecrawl

      import { Firecrawl } from 'firecrawl';

      const firecrawl = new Firecrawl({
        // 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：
        // apiKey: "fc-YOUR-API-KEY",
      });
      ```
    </CodeBlockTab>

    <CodeBlockTab value="CLI">
      ```bash  
      # 使用 npm 全局安装
      npm install -g firecrawl

      # 身份验证(一次性设置)
      firecrawl login
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="usage">
  ### 使用方法 [#使用方法]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="cli+curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="CLI">
        CLI
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      from firecrawl import Firecrawl

      firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
      res = firecrawl.map(url="https://firecrawl.dev", limit=50, sitemap="include")
      print(res)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      import { Firecrawl } from 'firecrawl';

      const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

      const res = await firecrawl.map('https://firecrawl.dev', { limit: 50, sitemap: 'include' });
      console.log(res);
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      curl -X POST https://api.firecrawl.dev/v2/map \
          -H 'Content-Type: application/json' \
          -H 'Authorization: Bearer YOUR_API_KEY' \
          -d '{
            "url": "https://firecrawl.dev"
          }'
      ```
    </CodeBlockTab>

    <CodeBlockTab value="CLI">
      ```bash  
      # Map a website to discover URLs
      firecrawl map https://firecrawl.dev

      # 以 JSON 格式输出并限制数量
      firecrawl map https://firecrawl.dev --json --limit 100 --pretty
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<Info>
  每次 map 请求都会消耗 1 个 credit，与返回的 URL 数量无关。例如，即使将 `limit` 设置为 100,000，也只会使用 1 个 credit。
</Info>

<div id="response">
  ### 响应 [#响应]
</div>

SDK 会直接返回数据对象。cURL 会按下方所示原样返回负载。

```json
{
  "success": true,
  "links": [
    {
      "url": "https://docs.firecrawl.dev/features/scrape",
      "title": "Scrape | Firecrawl",
      "description": "将任意 URL 转换为干净的数据",
    },
    {
      "url": "https://www.firecrawl.dev/blog/5_easy_ways_to_access_glm_4_5",
      "title": "访问 GLM-4.5 的 5 种简单方式",
      "description": "了解如何在本地、通过聊天应用、通过官方 API，以及借助 LLM 市场 API 实现无缝集成地访问 GLM-4.5 模型……",
    },
    {
      "url": "https://www.firecrawl.dev/playground",
      "title": "Playground - Firecrawl",
      "description": "预览 API 响应并获取该 API 的代码片段",
    },
    {
      "url": "https://www.firecrawl.dev/?testId=2a7e0542-077b-4eff-bec7-0130395570d6",
      "title": "Firecrawl - 面向 AI 的 Web 数据 API",
      "description": "面向 AI 的网页爬取、抓取与搜索 API，面向规模而构建。Firecrawl 为 AI 代理与构建者提供全网数据：干净、结构化，并且……",
    },
    {
      "url": "https://www.firecrawl.dev/?testId=af391f07-ca0e-40d3-8ff2-b1ecf2e3fcde",
      "title": "Firecrawl - 面向 AI 的 Web 数据 API",
      "description": "面向 AI 的网页爬取、抓取与搜索 API，面向规模而构建。Firecrawl 为 AI 代理与构建者提供全网数据：干净、结构化，并且……"
    },
    ...
  ]
}
```

<Warning>
  标题和描述不一定都会提供，具体取决于网站。
</Warning>

<div id="map-with-search">
  #### 带搜索参数的 Map [#带搜索参数的-map]
</div>

使用 `search` 参数的 Map 可在站内搜索特定的 URL。

```bash title="cURL"
curl -X POST https://api.firecrawl.dev/v2/map \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "url": "https://firecrawl.dev",
    "search": "docs"
  }'
```

响应将按相关性从高到低返回一个有序列表。

```json
{
  "status": "success",
  "links": [
    {
      "url": "https://docs.firecrawl.dev",
      "title": "Firecrawl 文档",
      "description": "Firecrawl 文档"
    },
    {
      "url": "https://docs.firecrawl.dev/sdks/python",
      "title": "Firecrawl Python SDK",
      "description": "Firecrawl Python SDK 文档"
    },
    ...
  ]
}
```

<div id="location-and-language">
  ## 位置与语言 [#位置与语言]
</div>

指定国家和首选语言，根据你的目标位置与语言偏好获取更相关的内容，方式与 /scrape 端点相似。

<div id="how-it-works">
  ### 工作原理 [#工作原理]
</div>

当你指定位置设置时，Firecrawl 会在可用时使用合适的代理，并模拟相应的语言和时区设置。默认情况下，若未指定，位置将设为“US”。

### 用法 [#用法]

要配置位置和语言，请在请求体中包含 `location` 对象，并设置以下属性：

* `country`：ISO 3166-1 alpha-2 国家代码 (如 'US'、'AU'、'DE'、'JP') 。默认值为 'US'。
* `languages`：按优先级排序的首选语言与区域设置数组。默认使用所设位置的语言。

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      from firecrawl import Firecrawl

      firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

      res = firecrawl.map('https://example.com',
          location={
              'country': 'US',
              'languages': ['en']
          }
      )

      print(res)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      import { Firecrawl } from 'firecrawl';

      const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

      const res = await firecrawl.map('https://example.com', {
        location: { country: 'US', languages: ['en'] },
      });

      console.log(res.metadata);
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      curl -X POST "https://api.firecrawl.dev/v2/map" \
        -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "url": "https://example.com",
          "location": { "country": "US", "languages": ["en"] }
        }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

有关支持的地区与位置的更多信息，请参见 [Proxies 文档](/zh/features/proxies)。

<div id="considerations">
  ## 注意事项 [#注意事项]
</div>

该端点优先考虑速度，因此可能无法捕获所有网站链接。它主要依赖网站的 sitemap，并结合缓存的爬取数据和搜索引擎结果。若需要更全面且最新的 URL 列表，请考虑改用 [/crawl](/zh/features/crawl) 端点。

> 你是需要 Firecrawl API 密钥的 AI 代理吗？请参见 [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) 获取自动化接入说明。