Search

소개

AnyCrawl Search API는 여러 검색 엔진의 결과를 프로그래밍 방식으로 가져옵니다. 대규모 언어 모델(LLM)을 위해 설계되었으며 AI 처리·분석에 맞는 깨끗한 구조화 데이터를 반환합니다.

API는 즉시 동기적으로 데이터를 반환합니다 — 폴링이나 웹훅이 필요 없습니다. 여러 검색 엔진과 다중 페이지 결과를 한 요청으로 가져와 포괄적으로 수집할 수 있습니다.

핵심 기능

다중 엔진: 현재 Google 검색 지원, 추가 엔진 예정
LLM 최적화: AI 처리에 적합한 구조화 JSON
다국어: 언어·지역별 검색
다중 페이지: 한 요청으로 여러 페이지의 검색 결과
고성능: 비동기 처리와 네이티브 고동시성
즉시 응답: 동기 API — 폴링 없이 바로 결과
풍부한 결과: 검색 결과와 검색 제안 모두 반환

API 엔드포인트

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

사용 예

기본 검색(기본 Google 엔진)

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "OpenAI ChatGPT"
  }'

다중 페이지 검색

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "machine learning tutorials",
    "pages": 3,
    "limit": 10
  }'

언어·지역 지정 검색

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "AnyCrawl",
    "lang": "zh",
    "pages": 2
  }'

페이지네이션 검색

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "web scraping tools",
    "offset": 20,
    "limit": 10
  }'

세이프서치

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "educational content",
    "safe_search": 0
  }'

요청 파라미터

파라미터	타입	필수	기본값	설명
`query`	string	예	-	실행할 검색어 문자열
`template_id`	string	아니오	-	이번 검색에 사용할 템플릿 ID
`variables`	object	아니오	-	템플릿 변수(`template_id`가 있을 때만)
`engine`	enum	아니오	`google`	검색 엔진. 현재 지원: `google`
`limit`	number	아니오	10	페이지당 최대 결과 수
`offset`	number	아니오	0	건너뛸 결과 수(페이지네이션)
`pages`	number	아니오	1	가져올 검색 결과 페이지 수(최소 1, 최대 20)
`lang`	string	아니오	`en`	검색 결과 언어 로캘(예: 'en', 'zh', 'es', 'fr')
`country`	string	아니오	-	검색 결과 국가 로캘(예: 'US', 'GB', 'CN')
`timeRange`	enum	아니오	-	기간 필터: `day`, `week`, `month`, `year`
`sources`	enum	아니오	-	검색 소스: `web`, `images`, `news`(SearXNG)
`safe_search`	number \| null	아니오	null	Google 세이프서치: `0`(끔), `1`(보통), `2`(엄격), null(기본). Google에만 적용.

선택: 결과 URL용 `scrape_options`

지정하면 각 검색 결과 URL을 주어진 옵션으로 스크래핑합니다(최상위 url 제외하고 /v1/scrape과 동일). 브라우저 전용 옵션은 브라우저가 아닌 스크래핑에서는 무시됩니다.

| Field | Type | Default | Notes | | ------------------- | ------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | engine | enum | - | 결과 URL 스크래프 엔진: auto, cheerio, playwright, puppeteer | | formats | array of enum | ["markdown"] | 출력 형식: markdown, html, text, screenshot, screenshot@fullPage, rawHtml, json, summary, links | | timeout | number | 60000 | 요청당 타임아웃(ms) | | wait_for | number | - | 추출 전 지연(ms), 브라우저만, wait_for_selector보다 낮은 우선순위 | | wait_until | enum | - | 브라우저 탐색 대기: load, domcontentloaded, networkidle, commit | | wait_for_selector | string, object, or array | - | 브라우저에서만. CSS 문자열, 객체, 또는 혼합 배열. 순차 대기. wait_for보다 우선. | | include_tags | array of string | - | CSS 선택자에 맞는 요소만 포함 | | exclude_tags | array of string | - | CSS 선택자에 맞는 요소 제외 | | only_main_content | boolean | true | 본문만 추출(include_tags 우선) | | proxy | string (URI) | - | 선택 프록시 URL | | json_options | object | - | 구조화 JSON 추출 옵션 | | extract_source | enum | markdown | JSON 추출 소스: markdown(기본) 또는 html | | ocr_options | boolean | false | 마크다운 이미지 OCR만. 마크다운 생성에만 영향. | | max_age | number | - | 캐시 최대 수명(ms). 0이면 캐시 읽기 생략 | | store_in_cache | boolean | true | 결과별 스크래핑에 페이지 캐시 쓰기 여부 |

지원 검색 엔진

`google`(기본)

용도: 포괄적인 일반 웹 검색
장점: 가장 포괄적인 결과, 다국어·다지역 지원
기능: 검색 결과와 검색 제안 모두 반환. 세이프서치(끔/보통/엄격)
권장: 일반 검색, 리서치, 콘텐츠 발견
세이프서치: safe_search 0(끔), 1(보통), 2(엄격), null(기본)

{
    "success": true,
    "data": [
        {
            "title": "AlsoAsked: People Also Ask keyword research tool",
            "url": "https://alsoasked.com/",
            "description": "Find the questions people also ask. Enter a question, brand or search query. e.g. 'keyword research'.",
            "source": "Google Search Result"
        },
        {
            "title": "OpenAI ChatGPT Features and Benefits",
            "url": "https://openai.com/chatgpt",
            "description": "ChatGPT is an AI assistant that can help with writing, research, and problem-solving.",
            "source": "Google Search Result"
        },
        {
            "title": "Keyword tool",
            "source": "Google Suggestions"
        }
    ]
}

검색 결과 유형

API는 두 가지 유형을 반환합니다.

검색 결과: 제목, URL, 설명, 소스가 있는 완전한 항목
검색 제안: 검색 엔진의 관련 쿼리 제안

오류 응답

400 - 유효성 검사 오류

{
    "success": false,
    "error": "Validation error",
    "details": {
        "issues": [
            {
                "field": "engine",
                "message": "Invalid enum value. Expected 'google', received 'invalid'",
                "code": "invalid_enum_value"
            }
        ],
        "messages": ["Invalid enum value. Expected 'google', received 'invalid'"]
    }
}

401 - 인증 오류

{
    "success": false,
    "error": "Invalid API key"
}

402 - 결제 필요

{
    "success": false,
    "error": "Insufficient credits. Please upgrade your plan or purchase more credits."
}

모범 사례

검색 엔진 선택

일반 웹 검색 → google(현재 유일 지원 엔진)
다국어 검색 → 적절한 lang 지정
포괄적 조사 → pages로 더 많은 결과

성능 최적화

배치 요청: 여러 번 호출 대신 pages로 한 번에 여러 페이지
언어 타겟팅: 지역·로캘 결과를 위해 언어 지정
쿼리 최적화: 구체적인 키워드·구문 사용

오류 처리

try {
    const response = await fetch("/v1/search", {
        method: "POST",
        headers: {
            Authorization: "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            query: "artificial intelligence",
            pages: 2,
        }),
    });

    const result = await response.json();

    if (result.success) {
        console.log("Found results:", result.data.length);

        const searchResults = result.data.filter((item) => item.url);
        const suggestions = result.data.filter((item) => !item.url);

        console.log("Search Results:", searchResults.length);
        console.log("Suggestions:", suggestions.length);
    } else {
        console.error("Search failed:", result.error);
    }
} catch (error) {
    console.error("Request failed:", error);
}

높은 동시성 사용

API는 원래부터 높은 동시성을 지원합니다. 여러 검색 요청을 동시에 보내도 속도 제한 걱정이 없습니다.

// 동시 검색 예
const queries = ["machine learning", "artificial intelligence", "data science"];

const searchPromises = queries.map((query) =>
    fetch("/v1/search", {
        method: "POST",
        headers: {
            Authorization: "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ query, engine: "google", pages: 2 }),
    }).then((res) => res.json())
);

const results = await Promise.all(searchPromises);
console.log(`Completed ${results.length} searches simultaneously`);