문서

문서

ActiCrawl을 사용하여 웹 스크래핑 워크플로를 자동화하는 방법을 알아보세요

소개 빠른 시작 플레이그라운드 설치 아키텍처 웹 크롤링 데이터 추출 API 엔드포인트 인증 예제

API 엔드포인트

ActiCrawl은 웹 스크래핑과 데이터 추출을 위한 RESTful API를 제공합니다. 모든 API 요청은 인증을 위한 API 키와 함께 기본 URL로 전송되어야 합니다.

기본 URL

text 
https://api.acticrawl.com/v1

사용 가능한 엔드포인트

1. 단일 URL 스크래핑

단일 웹 페이지에서 콘텐츠를 추출합니다.

http 
POST /scrape

요청 본문

json 
{
  "url": "https://example.com",
  "formats": ["markdown", "html", "screenshot"],
  "options": {
    "onlyMainContent": true,
    "includeHtml": false,
    "waitFor": 3000,
    "timeout": 30000,
    "usePremiumProxy": false,
    "excludeTags": ["nav", ".ads", "#footer"],
    "onlyIncludeTags": [],
    "headers": {
      "User-Agent": "Mozilla/5.0..."
    }
  }
}

매개변수

매개변수 타입 필수 설명
url string 예 스크래핑할 URL
formats array 아니오 출력 형식: markdown, html, cleanHtml, screenshot, pdf, json
options object 아니오 추가 스크래핑 옵션

옵션 객체

옵션 타입 기본값 설명
onlyMainContent boolean false 네비게이션, 광고 등을 제거하고 메인 콘텐츠만 추출
includeHtml boolean false 응답에 원본 HTML 포함
waitFor integer 0 JavaScript 렌더링을 위한 대기 시간(밀리초)
timeout integer 30000 페이지 로드를 위한 최대 대기 시간(밀리초)
usePremiumProxy boolean false 프리미엄 프록시 네트워크 사용
excludeTags array [] 제외할 CSS 선택자 또는 태그
onlyIncludeTags array [] 이 CSS 선택자 또는 태그만 포함
headers object {} 요청과 함께 전송할 사용자 정의 HTTP 헤더

응답

json 
{
  "success": true,
  "data": {
    "markdown": "# 페이지 제목\n\n콘텐츠...",
    "html": "<html>...</html>",
    "cleanHtml": "<div>...</div>",
    "screenshot": "base64_인코딩된_이미지",
    "metadata": {
      "title": "페이지 제목",
      "description": "페이지 설명",
      "language": "ko",
      "author": "작성자",
      "publishedTime": "2024-01-01T00:00:00Z",
      "modifiedTime": "2024-01-02T00:00:00Z",
      "keywords": ["키워드1", "키워드2"],
      "ogImage": "https://example.com/image.jpg"
    }
  },
  "credits_used": 1
}

2. 여러 페이지 크롤링

지정된 깊이까지 링크를 따라가며 웹사이트를 크롤링합니다.

http 
POST /crawl

요청 본문

json 
{
  "url": "https://example.com",
  "match": "https://example.com/**",
  "selector": "a[href]",
  "limit": 10,
  "depth": 2,
  "formats": ["markdown"],
  "options": {
    "onlyMainContent": true
  }
}

매개변수

매개변수 타입 필수 설명
url string 예 크롤링 시작 URL
match string 아니오 일치시킬 URL 패턴 (glob 형식)
selector string 아니오 따라갈 링크의 CSS 선택자
limit integer 아니오 크롤링할 최대 페이지 수 (기본값: 10)
depth integer 아니오 최대 크롤링 깊이 (기본값: 2)
formats array 아니오 각 페이지의 출력 형식
options object 아니오 스크래핑 옵션 (단일 URL과 동일)

응답

json 
{
  "success": true,
  "data": [
    {
      "url": "https://example.com",
      "markdown": "# 홈페이지...",
      "metadata": {...}
    },
    {
      "url": "https://example.com/about",
      "markdown": "# 회사 소개...",
      "metadata": {...}
    }
  ],
  "credits_used": 2,
  "pages_crawled": 2
}

3. 웹사이트 구조 매핑

웹사이트의 사이트맵을 생성합니다.

http 
POST /map

요청 본문

json 
{
  "url": "https://example.com",
  "match": "https://example.com/**",
  "selector": "a[href]",
  "limit": 100,
  "depth": 3
}

응답

json 
{
  "success": true,
  "data": {
    "urls": [
      "https://example.com",
      "https://example.com/about",
      "https://example.com/contact",
      "https://example.com/blog",
      "https://example.com/blog/post-1"
    ],
    "structure": {
      "https://example.com": {
        "title": "홈",
        "links": [
          "https://example.com/about",
          "https://example.com/contact",
          "https://example.com/blog"
        ]
      }
    }
  },
  "credits_used": 1,
  "pages_analyzed": 5
}

4. 웹사이트 콘텐츠 검색

웹사이트 내에서 특정 콘텐츠를 검색합니다.

http 
POST /search

요청 본문

json 
{
  "url": "https://example.com",
  "query": "머신러닝",
  "match": "https://example.com/blog/**",
  "limit": 20,
  "depth": 2
}

매개변수

매개변수 타입 필수 설명
url string 예 검색 시작 URL
query string 예 검색 쿼리
match string 아니오 검색할 URL 패턴
limit integer 아니오 검색할 최대 페이지 수 (기본값: 20)
depth integer 아니오 최대 검색 깊이 (기본값: 2)

응답

json 
{
  "success": true,
  "data": {
    "results": [
      {
        "url": "https://example.com/blog/ml-intro",
        "title": "머신러닝 입문",
        "excerpt": "...머신러닝은 인공지능의 하위 분야로...",
        "relevance_score": 0.95
      }
    ],
    "total_results": 3
  },
  "credits_used": 5,
  "pages_searched": 5
}

5. 계정 정보 조회

계정 정보와 사용 통계를 조회합니다.

http 
GET /account

응답

json 
{
  "success": true,
  "data": {
    "email": "user@example.com",
    "plan": "Professional",
    "credits": {
      "used": 1250,
      "limit": 10000,
      "reset_date": "2024-02-01T00:00:00Z"
    },
    "rate_limits": {
      "requests_per_minute": 60,
      "concurrent_requests": 10
    }
  }
}

오류 응답

모든 엔드포인트는 일관된 오류 응답을 반환합니다:

json 
{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "제공된 URL이 유효하지 않습니다",
    "details": "URL은 프로토콜(http:// 또는 https://)을 포함해야 합니다"
  }
}

일반적인 오류 코드

코드 설명
INVALID_API_KEY API 키가 누락되었거나 유효하지 않음
RATE_LIMIT_EXCEEDED 너무 많은 요청
INVALID_URL URL이 잘못되었거나 접근할 수 없음
TIMEOUT 요청 시간 초과
INVALID_PARAMETERS 요청 매개변수가 유효하지 않음
INSUFFICIENT_CREDITS 계정에 크레딧이 부족함
INTERNAL_ERROR 서버 오류 발생

속도 제한

플랜별 속도 제한:

플랜 분당 요청 수 동시 요청 수
Free 10 1
Starter 30 5
Professional 60 10
Business 120 20
Enterprise 무제한 무제한

속도 제한 정보는 응답 헤더에 포함됩니다:

text 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

웹훅

장시간 실행되는 작업의 경우 웹훅 URL을 제공할 수 있습니다:

json 
{
  "url": "https://example.com",
  "webhook_url": "https://your-app.com/webhook",
  "formats": ["markdown"]
}

작업이 완료되면 웹훅은 POST 요청을 받습니다:

json 
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "success": true,
    "data": {...}
  }
}