맵(Map)

사이트맵, 검색 엔진, 페이지 링크 분석으로 웹사이트의 모든 URL을 추출합니다.

소개

AnyCrawl Map API는 사이트맵 파싱, 검색 엔진 결과, HTML 링크 추출을 결합해 웹사이트에서 URL을 추출합니다. 사이트 구조 파악, 콘텐츠 인덱싱, 크롤 계획을 위한 URL 발견에 적합합니다.

핵심: API는 즉시 동기적으로 데이터를 반환합니다. 폴링이나 웹훅이 필요 없으며, 세 가지 URL 소스를 조합해 범위를 넓힙니다.

주요 기능

다중 소스 발견: 사이트맵 파싱, 검색 결과, 페이지 링크 추출 결합
사이트맵 지원: robots.txt 및 sitemap.xml 파싱(사이트맵 인덱스·gzip 포함)
검색 연동: URL 발견을 위해 site: 연산자로 검색 엔진 자동 사용
링크 추출: 대상 페이지의 모든 <a href> 링크 추출
도메인 필터: 정확한 도메인 또는 하위 도메인 포함 여부
즉시 응답: 동기 API — 폴링 없이 바로 결과

API 엔드포인트

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

사용 예시

cURL

기본 URL 맵핑

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"
  }'

하위 도메인 포함

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
  }'

사이트맵 파싱 건너뛰기

페이지 링크와 검색 결과만 필요할 때 더 빠르게 받을 수 있습니다.

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
  }'

요청 파라미터

파라미터	타입	필수	기본값	설명
`url`	string	예	-	맵핑할 대상 URL. 유효한 HTTP/HTTPS 주소여야 함
`limit`	number	아니오	`5000`	반환할 최대 URL 수(1–50000)
`include_subdomains`	boolean	아니오	`false`	하위 도메인 URL 포함(예: blog.example.com)
`ignore_sitemap`	boolean	아니오	`false`	사이트맵 파싱 생략, 검색·페이지 링크만 사용
`max_age`	number	아니오	-	캐시 최대 유효 기간(ms). `0`이면 캐시 읽기 생략, 생략 시 서버 기본값
`use_index`	boolean	아니오	`true`	페이지 캐시 인덱스(`page_cache`)를 추가 URL 소스로 사용할지 여부

캐시 동작

max_age는 Map 캐시 읽기를 제어합니다. 0이면 강제로 새로 고칩니다.
use_index=false는 페이지 캐시 인덱스 소스를 끕니다(페이지 캐시가 켜져 있어야 효과가 있음).
/v1/map 응답에는 fromCache가 포함되지 않습니다(캐시 사용은 내부 동작).

URL 발견 소스

Map API는 세 가지 소스를 결합합니다.

1. 사이트맵 파싱

robots.txt를 파싱해 사이트맵 위치 탐색
일반적인 경로 시도: /sitemap.xml, /sitemap.xml.gz
사이트맵 인덱스(다른 사이트맵을 가리키는 사이트맵) 지원
gzip 압축 사이트맵 지원

2. 검색 엔진 결과

site:domain.com으로 색인된 페이지를 자동 발견
발견된 URL에 제목·설명 메타데이터 제공

3. 페이지 링크 추출

대상 페이지 HTML에서 모든 <a href> 추출
링크 텍스트를 제목 메타데이터로 사용
title 속성과 aria-label을 설명으로 사용

메타데이터 소스

소스	제목	설명
Sitemap	-	-
검색 엔진	검색 결과 제목	검색 스니펫
페이지 링크	링크 텍스트 또는 title	aria-label

응답 형식

성공(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"
        }
    ]
}

오류 응답

400 — 유효성 검사 오류

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

402 — 크레딧 부족

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

500 — 내부 서버 오류

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

모범 사례

활용 사례

크롤 계획: 전체 크롤 전에 Map으로 모든 URL 발견
콘텐츠 인덱싱: 사이트 페이지 전체 목록 구축
사이트 감사: SEO·접근성 감사를 위해 모든 페이지 찾기
링크 분석: 내부 링크 구조 분석

성능 팁

사이트맵이 불필요하면 ignore_sitemap: true로 더 빠르게
불필요한 URL 처리를 피하려면 적절한 limit 설정
하위 도메인 간 발견이 필요 없으면 include_subdomains: false(기본값) 유지

Crawl과 함께 쓰기

Map은 크롤 작업 계획에 적합합니다.

// 1단계: Map으로 URL 발견
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();

// 2단계: 발견한 URL로 크롤 계획
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,
    }),
});

크레딧

작업	크레딧
Map 작업	1

합계: 요청당 1 크레딧.

자주 묻는 질문

Map과 Crawl의 차이는?

Map은 페이지 콘텐츠를 가져오지 않고 URL만 발견합니다. 빠르고 가볍습니다. Crawl은 각 페이지의 실제 콘텐츠를 가져와 처리합니다. URL 발견·계획에는 Map, 콘텐츠 추출에는 Crawl을 사용하세요.

결과에 URL이 빠져 있는 이유는?

다른 도메인/하위 도메인에 있음(include_subdomains: true 시도)
사이트맵이 없음
JavaScript로 동적 생성된 URL
limit을 초과함

검색 엔진 발견은 어떻게 동작하나요?

Map API는 site:domain.com으로 검색해 색인된 페이지를 찾습니다. 사이트맵에 없거나 메인 페이지에서 링크되지 않은 URL을 찾는 데 도움이 됩니다.

Map은 리다이렉트를 따라가나요?

사이트맵과 페이지 링크에 나타난 URL 그대로 추출합니다. 리다이렉트를 따라 추가 URL을 발견하지는 않습니다.

속도 제한이 있나요?

없습니다. API는 고동시성을 기본 지원하며 여러 요청을 동시에 보내도 됩니다.

목차