템플릿

변수와 사용자 정의 로직이 있는 재사용 가능한 스크래핑·크롤·검색 레시피

소개

템플릿은 스크래핑, 크롤, 검색을 위한 재사용 가능한 설정입니다. 매 API 호출마다 같은 옵션을 반복하지 않고, 한 번 정의한 템플릿(또는 AnyCrawl 템플릿 스토어에서 가져온 템플릿)을 template_id로 참조합니다.

이점:

단순함: template_id와 최소 입력만으로 API 호출
일관성: 팀·프로젝트 전반에서 동작 표준화
안전성: 허용 도메인을 제한하고 필요한 변수만 노출 가능
확장성: 고급 변환을 위한 선택적 사용자 정의 핸들러

지원 타입:

scrape: /v1/scrape로 단일 페이지 추출
crawl: /v1/crawl로 다중 페이지 크롤
search: /v1/search로 검색 엔진 결과

템플릿 마켓플레이스

anycrawl.dev/template 에서 바로 쓸 수 있는 템플릿을 둘러보세요.

사용 방법:

마켓에서 필요한 템플릿 찾기
상세 페이지에서 template_id 복사
해당 template_id와 필요한 입력으로 API 호출

예:

curl -X POST "https://api.anycrawl.dev/v1/scrape" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "content-extractor",
    "url": "https://example.com"
  }'

API 호출에서 템플릿 사용

요청 파라미터

template_id를 사용할 때는 아래 최소 필드만 허용됩니다.

엔드포인트	필수 필드	선택 필드
`/v1/scrape`	`template_id`	`url`, `variables`
`/v1/crawl`	`template_id`	`url`, `variables`
`/v1/search`	`template_id`	`query`, `variables`

중요:

템플릿에 미리 정의되어 있으면 url 또는 query가 선택일 수 있습니다. 템플릿 설명을 확인하세요.
variables는 템플릿이 기대하는 동적 입력을 전달합니다(아래 변수 절 참고).
engine, formats, timeout 등 다른 필드는 템플릿에서 오며 덮어쓸 수 없습니다.
허용되지 않은 필드를 보내면 400 유효성 검사 오류가 반환됩니다.

템플릿으로 스크래핑

curl -X POST "https://api.anycrawl.dev/v1/scrape" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-scrape-template",
    "url": "https://example.com",
    "variables": { "category": "tech" }
  }'

템플릿으로 크롤

curl -X POST "https://api.anycrawl.dev/v1/crawl" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-crawl-template",
    "url": "https://docs.example.com",
    "variables": { "maxPages": 50 }
  }'

템플릿으로 검색

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-search-template",
    "query": "machine learning tutorials",
    "variables": { "lang": "en" }
  }'

변수

템플릿은 호출 시점에 동적 입력을 받기 위해 변수를 선언할 수 있습니다.

각 변수는 type: string, number, boolean, url
required이거나 defaultValue가 있는 선택 변수
템플릿 설명에서 기대 변수 확인

변수가 포함된 요청 예:

{
    "template_id": "blog-scraper",
    "url": "https://example.com/blog/post-123",
    "variables": {
        "author": "john-doe",
        "includeComments": true,
        "maxComments": 50
    }
}

필수 변수를 빼먹거나 타입이 맞지 않으면 400 유효성 검사 오류가 납니다.

응답 형식

템플릿 응답은 일반 API와 동일한 형식을 따릅니다.

{
    "success": true,
    "data": {
        "url": "https://example.com",
        "markdown": "# Page Title\n\nContent...",
        "metadata": { ... },
        // 사용자 정의 핸들러가 있으면 추가 필드
        "extractedData": { ... }
    }
}

사용자 정의 핸들러가 있으면 응답에 추가 필드가 붙을 수 있습니다.

오류 처리

템플릿 사용 시 흔한 오류:

오류	HTTP 상태	설명
Template not found	404	`template_id`가 없거나 접근 권한이 없음
Validation error	400	필수 변수 누락 또는 타입 오류
Domain restriction violation	403	템플릿 도메인 정책에 URL이 허용되지 않음
Invalid fields	400	템플릿 사용 시 허용되지 않은 최상위 필드

오류 응답 예:

{
    "success": false,
    "error": "Validation error",
    "message": "When using template_id, only template_id, url, variables are allowed. Invalid fields: engine, formats",
    "data": {
        "type": "validation_error",
        "issues": [
            {
                "field": "engine",
                "message": "Field 'engine' is not allowed when using template_id",
                "code": "invalid_field"
            }
        ],
        "status": "failed"
    }
}

모범 사례

API 호출자

필수 변수와 허용 도메인/키워드는 항상 템플릿 설명에서 확인
가능하면 마켓 템플릿으로 시간 절약
404 처리(삭제·보관된 템플릿일 수 있음)
템플릿 설정(engine, formats 등) 덮어쓰기 시도 금지 — 실패합니다

템플릿 작성자

한 가지 용도에 집중
변수는 설명과 함께 명확히 문서화
오남용 방지를 위해 도메인 제한 사용
복잡도에 맞는 가격 설정
공개 전 충분히 테스트

템플릿 만들기(고급)

직접 템플릿을 만들 때 구성할 수 있는 항목입니다.

도메인 제한

템플릿을 쓸 수 있는 위치를 제한합니다.

{
    "allowedDomains": {
        "type": "glob",
        "patterns": ["*.example.com", "docs.mysite.com"]
    }
}

type: "exact"(정확 일치) 또는 "glob"(패턴)
patterns: 허용 도메인 또는 패턴 배열

키워드 제한(검색 템플릿)

검색 템플릿에 사용할 수 있는 쿼리를 제한합니다.

{
    "allowedKeywords": {
        "type": "glob",
        "patterns": ["*tutorial*", "*documentation*"]
    }
}

allowedKeywords는 쿼리 실행 전에 검증됩니다.
type: "exact" 또는 "glob"
patterns: 허용 키워드 값/패턴
쿼리 검증은 queryTransform 적용 전에 수행됩니다.

가격

호출당 크레딧 비용을 설정합니다.

{
    "pricing": {
        "perCall": 10,
        "currency": "credits"
    }
}

사용자 정의 핸들러

JavaScript/TypeScript로 다음을 작성할 수 있습니다.

requestHandler: 스크래핑 결과 후처리 및 사용자 필드 추가
failedRequestHandler: 사용자 정의 재시도 로직으로 실패 처리
queryTransform(검색만): 검색 전 쿼리 변환
urlTransform(스크래핑/크롤만): 처리 전 URL 변환

두 변환 모두 다음을 지원합니다.

플레이스홀더가 있는 템플릿 모드(쿼리: {{query}}, URL: {{url}})
prefix와 suffix가 있는 append 모드
모드 적용 전 부분 문자열을 뽑는 선택적 regexExtract

TikTok 프로필용 정규식 추출 예:

{
    "customHandlers": {
        "urlTransform": {
            "enabled": true,
            "mode": "append",
            "prefix": "",
            "suffix": "",
            "regexExtract": {
                "pattern": "^(https?:\\/\\/www\\.tiktok\\.com\\/@[^\\/?#]+)",
                "flags": "i",
                "group": 1
            }
        }
    }
}

다음 입력에서 https://www.tiktok.com/@piperrockelle을 추출합니다.

https://www.tiktok.com/@piperrockelle?abb=ccc
https://www.tiktok.com/@piperrockelle

requestHandler 예:

// 페이지 컨텍스트에서 구조화 데이터 추출
const title = context.data.title;
const content = context.data.markdown;

return {
    extractedTitle: title,
    wordCount: content.split(/\s+/).length,
    customMetric: calculateMetric(content),
};