Map (bản đồ URL)

Trích xuất mọi URL từ một website bằng sitemap, công cụ tìm kiếm và phân tích liên kết trang.

Giới thiệu

API Map của AnyCrawl trích URL từ website bằng cách kết hợp nhiều nguồn khám phá: phân tích sitemap, kết quả công cụ tìm kiếm và trích liên kết HTML. Cung cấp khám phá URL toàn diện cho bản đồ site, lập chỉ mục nội dung và lập kế hoạch crawl.

Điểm nổi bật: API trả dữ liệu ngay, đồng bộ — không cần polling hay webhook. Kết hợp ba nguồn URL để phủ tối đa.

Tính năng cốt lõi

Khám phá đa nguồn: Kết hợp phân tích sitemap, kết quả tìm kiếm và trích liên kết trang
Hỗ trợ sitemap: Phân tích robots.txt và sitemap.xml (kể cả sitemap index và gzip)
Tích hợp tìm kiếm: Tự động dùng công cụ tìm kiếm với toán tử site: để khám phá URL
Trích liên kết: Trích mọi liên kết <a href> từ trang đích
Lọc theo domain: Lọc theo domain chính xác hoặc gồm subdomain
Phản hồi tức thì: API đồng bộ — có kết quả ngay, không polling

Endpoint API

POST https://api.anycrawl.dev/v1/map

Ví dụ sử dụng

cURL

Map URL cơ bản

curl -X POST "https://api.anycrawl.dev/v1/map" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'

Gồm subdomain

curl -X POST "https://api.anycrawl.dev/v1/map" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "include_subdomains": true,
    "limit": 1000
  }'

Bỏ qua phân tích sitemap

Để nhanh hơn khi chỉ cần liên kết trang và kết quả tìm kiếm:

curl -X POST "https://api.anycrawl.dev/v1/map" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "ignore_sitemap": true
  }'

Tham số request

Parameter	Type	Required	Default	Description
`url`	string	Yes	-	URL đích để map, phải là địa chỉ HTTP/HTTPS hợp lệ
`limit`	number	No	`5000`	Số URL tối đa trả về (1–50000)
`include_subdomains`	boolean	No	`false`	Gồm URL từ subdomain (ví dụ blog.example.com)
`ignore_sitemap`	boolean	No	`false`	Bỏ qua phân tích sitemap, chỉ dùng tìm kiếm và liên kết trang
`max_age`	number	No	-	Tuổi tối đa cache (ms). Dùng `0` để bỏ đọc cache; bỏ trống dùng mặc định server
`use_index`	boolean	No	`true`	Có dùng chỉ mục Page Cache (`page_cache`) làm nguồn URL bổ sung hay không

Hành vi cache

max_age điều khiển đọc Map Cache. 0 buộc làm mới.
use_index=false tắt nguồn chỉ mục Page Cache (cần Page Cache bật mới có tác dụng).
/v1/map không trả fromCache trong response (dùng cache là nội bộ).

Nguồn khám phá URL

API Map kết hợp ba nguồn:

1. Phân tích sitemap

Phân tích robots.txt để tìm vị trí sitemap
Thử đường dẫn thường gặp: /sitemap.xml, /sitemap.xml.gz
Hỗ trợ sitemap index (sitemap chứa sitemap khác)
Hỗ trợ sitemap nén gzip

2. Kết quả công cụ tìm kiếm

Tự động dùng toán tử site:domain.com để khám phá trang đã được index
Cung cấp metadata tiêu đề và mô tả cho URL tìm được

3. Trích liên kết trang

Trích mọi liên kết <a href> từ HTML trang đích
Lấy text liên kết làm metadata tiêu đề
Lấy thuộc tính title và aria-label làm mô tả

Nguồn metadata

Source	Title	Description
Sitemap	-	-
Search Engine	Tiêu đề kết quả tìm	Đoạn snippet tìm kiếm
Page Links	Text liên kết hoặc thuộc tính title	Thuộc tính aria-label

Định dạng response

Response thành công (HTTP 200)

{
    "success": true,
    "data": [
        {
            "url": "https://example.com/page1",
            "title": "Page Title",
            "description": "Page description from search results"
        },
        {
            "url": "https://example.com/page2",
            "title": "Another Page"
        },
        {
            "url": "https://example.com/page3"
        }
    ]
}

Response lỗi

400 - Lỗi validation

{
    "success": false,
    "error": "Validation error",
    "message": "Invalid url",
    "details": {
        "issues": [
            {
                "field": "url",
                "message": "Invalid url",
                "code": "invalid_string"
            }
        ]
    }
}

402 - Không đủ credits

{
    "success": false,
    "error": "Insufficient credits",
    "message": "Estimated credits required (1) exceeds available credits (0).",
    "details": {
        "estimated_total": 1,
        "available_credits": 0
    }
}

500 - Lỗi server nội bộ

{
    "success": false,
    "error": "Internal server error",
    "message": "Error message details"
}

Thực hành tốt

Trường hợp sử dụng

Lập kế hoạch crawl: Dùng Map để khám phá URL trước khi crawl toàn site
Lập chỉ mục nội dung: Xây chỉ mục đầy đủ các trang của website
Kiểm tra site: Tìm mọi trang cho SEO hoặc audit khả năng truy cập
Phân tích liên kết: Phân tích cấu trúc liên kết nội bộ

Gợi ý hiệu năng

Dùng ignore_sitemap: true để nhanh hơn khi không cần sitemap
Đặt limit phù hợp để tránh xử lý URL thừa
Dùng include_subdomains: false (mặc định) trừ khi cần khám phá qua subdomain

Kết hợp với Crawl

Map phù hợp để lập kế hoạch crawl:

// Bước 1: Khám phá URL bằng Map
const mapResponse = await fetch("/v1/map", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        url: "https://docs.example.com",
        limit: 100,
    }),
});
const { data: urls } = await mapResponse.json();

// Bước 2: Dùng URL đã tìm để lập crawl
const crawlResponse = await fetch("/v1/crawl", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        url: "https://docs.example.com",
        include_paths: urls.map((u) => new URL(u.url).pathname),
        limit: 100,
    }),
});

Credits

Operation	Credits
Thao tác Map	1

Tổng: 1 credit mỗi request.

Câu hỏi thường gặp

Q: Khác biệt giữa Map và Crawl?

A: Map khám phá URL mà không tải nội dung trang — nhanh và nhẹ. Crawl tải và xử lý nội dung từng trang. Dùng Map để khám phá và lập kế hoạch, Crawl để trích nội dung.

Q: Vì sao một số URL không có trong kết quả?

A: Có thể do:

URL thuộc domain/subdomain khác (dùng include_subdomains: true)
Website không có sitemap
URL được tạo động bằng JavaScript
Vượt quá tham số limit