WebExtrator 스마트 추출 API 통합 가이드

POST https://api.acedata.cloud/webextrator/extract WebExtrator 스마트 추출 API는 URL을 유형화된 구조화 결과로 변환합니다 —— 기사, 상품, 레시피, 비디오, 토론, 채용 등, 동시에 정리된 Markdown 및 순수 텍스트를 제공합니다. 원시 HTML이 아닌 “깨끗한 구조화 데이터”가 필요할 때 사용하는 인터페이스입니다. 기본적으로는 세 단계의 파이프라인으로 구성되어 있습니다:

schema.org JSON-LD 매퍼 —— 결정적이며, LLM 비용이 없습니다. Wikipedia / BestBuy / AllRecipes / YouTube / 대부분의 뉴스 / 대부분의 상품 페이지를 커버합니다.
유형화 LLM 추출 —— schema.org가 미치지 못할 때만 트리거됩니다. 페이지 유형에 따라 Schema를 선택하고, Zod로 엄격하게 검증합니다.
Readability + Markdown 보완 —— 항상 실행되며, 앞의 두 단계에서 채워지지 않은 최상위 필드를 보완합니다.

URL 중복 요청은 Redis 결과 캐시에 의해 처리되며, <1 ms에 반환됩니다.

신청 절차

WebExtrator 서비스 페이지를 사용하려면, 먼저 Ace Data Cloud 콘솔에서 API Token을 받아두세요.

로그인 또는 등록이 되어 있지 않으면 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있습니다; 할당량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.

📘 전체 문서: WebExtrator 서비스 페이지 →

인증

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

요청 매개변수

Extract는 모든 Render API 매개변수(url, user_agent, timeout, wait_until, delay, wait_for_selector, block_resources, headers, cookies, callback_url, bypass_cache, cache_ttl_seconds, async)를 수용하며, 두 개의 Extract 전용 필드가 추가됩니다:

필드	유형	필수	기본값	설명
`expected_type`	enum	❌	자동 판단	페이지 유형 힌트: `product` / `article` / `general`. URL / 텍스트 휴리스틱을 건너뛰고 직접 해당 분기로 진행합니다.
`enable_llm`	boolean	❌	`false`	schema.org가 미치지 못할 때 LLM 추출을 허용합니다. Amazon / HN / Greenhouse와 같은 JSON-LD가 없는 페이지에서 열어야 유형화된 결과를 얻을 수 있습니다.

페이지에 schema.org JSON-LD가 포함되어 있을 경우, enable_llm은 무효입니다 —— 결정적 매퍼가 직접 결과를 생성하며, LLM 호출을 낭비하지 않습니다. 당신은 공짜로 유형화된 결과를 얻습니다.

동기 응답

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_at": 1777717800.123,
  "finished_at": 1777717802.535,
  "elapsed": 2.412,
  "data": {
    "kind": "extract",
    "url": "https://en.wikipedia.org/wiki/Diffbot",
    "finalUrl": "https://en.wikipedia.org/wiki/Diffbot",
    "contentType": "article",
    "title": "Diffbot",
    "description": "미국의 기계 학습 및 지식 관리 회사",
    "byline": "위키미디어 프로젝트 기여자",
    "language": "en",
    "siteName": "Wikipedia",
    "publishedAt": "2007-08-08T05:47:27Z",
    "images": ["https://en.wikipedia.org/static/images/icons/enwiki-25.svg"],
    "links": ["https://en.wikipedia.org/wiki/Machine_learning"],
    "markdown": "# Diffbot\n\nDiffbot은 기계 학습 개발자입니다 ...",
    "text": "Diffbot은 기계 학습 알고리즘의 개발자입니다 ...",
    "structured": {
      "schemaOrg": { "primary": { /* 유형화된 엔티티 */ }, "breadcrumbs": [], "all": [] },
      "openGraph": { "title": "...", "description": "...", "image": "...", "type": "..." },
      "jsonLd": [ /* 원본 JSON-LD */ ]
    },
    "rawSignals": {
      "hasJsonLd": true,
      "title": "Diffbot - Wikipedia",
      "metaDescription": null,
      "pageStatus": 200,
      "textLength": 11473
    },
    "elapsedMs": 2412
  }
}

최상위 필드

필드	유형	설명
`kind`	string	고정된 `"extract"`입니다.
`url`	string	제출한 URL입니다.
`finalUrl`	string	리디렉션된 최종 URL입니다.
`contentType`	enum	`product` / `article` / `general`, `expected_type` → schema.org primary → 휴리스틱 순으로 결정됩니다.
`title`	string	Readability `<title>` 또는 렌더링된 `document.title`입니다.
`description`	string?	우선순위: `<meta name="description" />` → `og:description` → schema.org / LLM 추출 → 본문 첫 단락 절단입니다.
`byline`	string?	저자 / 채널 / 회사입니다. 출처 `<meta name="author" />` → schema.org / LLM입니다.
`language`	string?	`<html lang>`입니다.
`siteName`	string?	`og:site_name`입니다.
`publishedAt`	string?	ISO 8601입니다. 우선순위: `article:published_time` → `<time datetime>` → schema.org / LLM입니다.
`images`	string[]	최대 50개의 `<img src />`로, 절대 URL로 변환되고 중복 제거되며 `data:` URI는 버려집니다.
`links`	string[]	최대 100개의 외부 링크로, 조각 / `javascript:` / `mailto:` / `tel:`가 필터링됩니다.
`markdown`	string	Turndown으로 변환된 Markdown입니다.
`text`	string	Mozilla Readability로 추출된 `textContent`입니다.
`structured`	object	전체 구조화된 결과입니다.
`rawSignals`	object	디버깅용 진단 정보입니다.
`cached`	boolean?	캐시에 적중할 경우 `true`입니다.
`cacheStoredAt`	number?	캐시 항목이 처음 기록된 Unix 밀리초 타임스탬프입니다.

`data.structured` 하위 필드

자식 필드	언제 나타나는지	설명
`schemaOrg`	항상	`{ primary, breadcrumbs, all }`。`primary`는 가장 높은 우선순위의 유형화된 엔티티이며, 찾을 수 없을 경우 `null`입니다.
`openGraph`	항상	`{ title, description, image, type }`，`<meta property="og:*" />`에서 가져옵니다.
`jsonLd`	항상	모든 `<script type="application/ld+json">` 블록의 원시 JSON 배열입니다.
`llm`	LLM이 실행되고 성공할 때	`{ kind, data, model, promptCharCount }`，Zod로 검증된 유형화된 결과입니다.
`llmError`	LLM이 실행되었으나 실패할 때	`{ kind, error, model }`，요청이 중단되지 않으며, 휴리스틱 결과는 여전히 반환됩니다.
`amazon`	URL이 `amazon.*`일 때	오래된 amazon 전용 크롤러 결과(점진적으로 폐기될 예정입니다).

schema.org 매핑기 범위

우선순위에 따라 정렬됨 (히트 시 structured.schemaOrg.primary로 사용됨):

schema.org 유형	매핑 종류	출력 필드
`Product`	product	`name, sku, gtin, model, color, brand, url, images, offer.{price,currency,availability,condition,seller}, rating.{value,count}, reviews[], properties[]`
`Recipe`	recipe	`name, description, image, datePublished, author, cookTime, prepTime, totalTime, recipeYield, ingredients[], instructions[], nutrition, rating, keywords, recipeCategory, recipeCuisine`
`VideoObject`	video	`name, description, thumbnailUrl, uploadDate, duration, embedUrl, contentUrl, channel, interactionCount`
`JobPosting`	job	`title, description, datePosted, validThrough, hiringOrganization, jobLocation, baseSalary, employmentType`
`Event`（포함 `*Event`）	event	`name, description, startDate, endDate, location.{name,address}, organizer, offer.{url,price,currency}`
`Article` / `NewsArticle` / `BlogPosting` / `ScholarlyArticle` / `TechArticle` / `Report` / `*NewsArticle`	article	`subtype, headline, description, datePublished, dateModified, author, publisher, image[], url, sameAs[]`
`FAQPage`	faq	`questions[{question, answer}]`
`BreadcrumbList`	（형제에 연결됨）	항상 `structured.schemaOrg.breadcrumbs[]`에 출력되며, primary로 사용되지 않습니다.

매핑기 처리:

@graph 컨테이너 (재귀적으로 전개됨)；
@type 배열 (예: ["Recipe", "NewsArticle"] —— 두 개 모두 인식되며, 우선순위에 따라 승리)；
http://schema.org/ 접두사 변형；
중첩된 Offer 및 AggregateOffer (후자는 lowPrice로 읽음)；
상대 이미지 URL (최종 URL에 따라 절대적으로 해석됨).

LLM 유형화 스키마

enable_llm: true 그리고 schema.org에 primary가 없을 때, 추출기는 URL 휴리스틱 (또는 expected_type 힌트)에 따라 아래 중 하나의 Zod 스키마 검증 모델 출력을 선택합니다:

종류	URL 휴리스틱	필수 필드	선택 필드
`article`	텍스트 ≥400자이며 다른 항목이 미스일 때	`headline`	`description, byline, publishedAt, language, topics[], sections[{heading,summary}]`
`product`	`amazon.* / ebay.* / aliexpress.* / temu.* / walmart.* / bestbuy.*`	`name`	`description, brand, sku, price, currency, availability, rating.{value,count}, bullets[], specifications[{name,value}]`
`discussion`	`news.ycombinator.com / reddit.com / lobste.rs`	`title`	`author, postedAt, points, commentCount, body, url`
`recipe`	`allrecipes / foodnetwork / seriouseats / epicurious / bonappetit / simplyrecipes`	`name`	`description, author, cookTime, prepTime, totalTime, recipeYield, ingredients[], instructions[], nutrition, rating, keywords[]`
`video`	`youtube.com/watch / youtu.be / vimeo.com/<id> / tiktok.com/@/video`	`name`	`description, channel, uploadDate, duration, viewCount, likeCount, thumbnailUrl, transcript`
`job`	`greenhouse.io / lever.co / jobs.* / careers.* / workable.com / bamboohr`	`title`	`description, company, location, remote, employmentType, datePosted, validThrough, salaryMin, salaryMax, salaryCurrency, salaryPeriod, responsibilities[], qualifications[]`

LLM 성공 시 최상위 필드에 “last-resort”로 다시 채워집니다:

article → description / byline / publishedAt / language
product → description
discussion → description（= body의 처음 280자）/ byline（= author）/ publishedAt（= postedAt）
recipe → description / byline（= author）
video → description / byline（= channel）/ publishedAt（= uploadDate）
job → description / byline（= company）/ publishedAt（= datePosted）

다시 채우기는 확정적인 데이터 소스가 해당 필드를 채우지 않았을 때만 발생합니다 — LLM은 항상 마지막 보루입니다.

캐시

동일한 요청은 동일한 Redis 키로 해시됩니다: webextrator:cache:extract:<sha256(canonical-json)>。캐시 키는 무시합니다 async、 bypass_cache、cache_ttl_seconds（이는 작동 스위치이며, 응답에 영향을 미치지 않습니다）。cookies / headers 는 분리된 캐시로 저장됩니다.

필드	효과
`bypass_cache: true`	읽기를 건너뜁니다; 이번 결과는 여전히 캐시에 기록되며, 다음 동일한 요청이 적중할 수 있습니다.
`cache_ttl_seconds: 0`	이번 응답은 캐시되지 않습니다.
`cache_ttl_seconds: N`	이 항목의 TTL을 사용자 정의합니다 (기본 3600초).

캐시 적중 응답은 data.cached: true 및 data.cacheStoredAt: <unix-ms>를 포함합니다.

비동기 모드 및 콜백

async: true로 설정하면 비동기 모드로 전환됩니다 (또한 callback_url을 제공하면 자동으로 전환됩니다). 플랫폼은 즉시 반환합니다 (HTTP 200):

{
  "success": true,
  "task_id": "550e8400-...",
  "trace_id": "6ba7b810-...",
  "started_at": 1777717800.123
}

작업이 완료되면 전체 envelope을 callback_url로 POST합니다 (구성된 경우). 또한 나중에 /webextrator/tasks에서 수동으로 조회할 수 있습니다.

예시

1. Wikipedia 기사 (schema.org 적중, LLM 필요 없음)

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://en.wikipedia.org/wiki/Diffbot",
    "expected_type": "article"
  }'

data.structured.schemaOrg.primary 주요 필드:

{
  "kind": "article",
  "subtype": "Article",
  "headline": "미국의 기계 학습 및 지식 관리 회사",
  "datePublished": "2007-08-08T05:47:27Z",
  "dateModified": "2025-07-10T20:42:45Z",
  "author": { "name": "위키미디어 프로젝트 기여자", "type": "Organization" },
  "publisher": { "name": "위키미디어 재단, Inc." }
}

2. BestBuy 상품 페이지 (schema.org 적중)

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.bestbuy.com/product/apple-airpods-pro-2nd-generation-white/JJ8ZH6TPSW",
    "expected_type": "product"
  }'

schema.org 추출:

{
  "kind": "product",
  "name": "Apple - 리퍼비시 우수 - AirPods Pro (2세대) - 화이트",
  "sku": "10845412",
  "model": "MQD83AM/A",
  "color": "화이트",
  "brand": "Apple",
  "offer": { "price": 159.99, "currency": "USD", "availability": "https://schema.org/InStock", "seller": "Best Buy" },
  "rating": { "value": 4.4, "count": 8 }
}

3. AllRecipes 레시피 페이지 (영양 및 단계 포함)

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.allrecipes.com/recipe/16354/easy-meatloaf/"
  }'

schema.org 추출:

{
  "kind": "recipe",
  "name": "쉬운 미트로프",
  "cookTime": "PT60M",
  "totalTime": "PT75M",
  "recipeYield": "8 / 1 (9x5-inch) 미트로프",
  "ingredients": ["1 1/2 파운드 다진 소고기", "..."],
  "instructions": [{ "text": "오븐을 350°F로 예열하세요 ..." }, "..."],
  "rating": { "value": 4.7, "count": 9348 }
}

4. HN 토론 페이지 (JSON-LD 없음 — LLM 활성화 필요)

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com/item?id=37000000",
    "enable_llm": true
  }'

data.structured.llm.data:

{
  "kind": "discussion",
  "title": "Show HN: 웹 페이지를 추출하는 새로운 방법",
  "author": "alice",
  "points": 173,
  "commentCount": 42,
  "body": "안녕하세요 HN, 우리는 Diffbot의 Analyze API에 대한 자체 호스팅 대안을 만들었습니다 ..."
}

최상위 필드도 다시 채워짐: byline = "alice"、publishedAt = "..."。

5. Amazon 상품 페이지 (Amazon JSON-LD 없음 — LLM 활성화 필요)

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.amazon.com/dp/B0BSHF7WHW",
    "expected_type": "product",
    "enable_llm": true
  }'

data.structured.llm.data (유형화 product):

{
  "kind": "product",
  "name": "Apple 2023 MacBook Pro M2 Pro 14인치",
  "brand": "Apple",
  "price": 1799,
  "currency": "USD",
  "bullets": ["Apple M2 Pro 칩, 10코어 CPU", "..."],
  "specifications": [{ "name": "디스플레이 크기", "value": "14.2 인치" }, "..."]
}

Python (requests)

import os, requests

API_KEY = os.environ["ACEDATA_API_KEY"]

resp = requests.post(
    "https://api.acedata.cloud/webextrator/extract",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://en.wikipedia.org/wiki/Diffbot",
        "expected_type": "article",
    },
    timeout=120,
)
resp.raise_for_status()
data = resp.json()["data"]

primary = (data.get("structured") or {}).get("schemaOrg", {}).get("primary")
print("contentType:", data["contentType"])
print("title:      ", data["title"])
print("byline:     ", data.get("byline"))
print("publishedAt:", data.get("publishedAt"))
if primary and primary["kind"] == "article":
    print("headline:    ", primary["headline"])
    print("dateModified:", primary.get("dateModified"))

Node.js (fetch)

const apiKey = process.env.ACEDATA_API_KEY;

const res = await fetch('https://api.acedata.cloud/webextrator/extract', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://www.allrecipes.com/recipe/16354/easy-meatloaf/',
  }),
});
const { data } = await res.json();
const recipe = data?.structured?.schemaOrg?.primary;
console.log(recipe.name, recipe.cookTime, recipe.ingredients.length, '종류의 재료');

팁 및 주의사항

expected_type를 전달할 수 있으면 전달하세요. 무료 팁으로, 휴리스틱 판단을 건너뛰고, URL 패턴이 내장 목록에 없는 페이지에 특히 유용합니다.
enable_llm: true는 schema.org 적중 페이지에서 무료입니다. LLM은 schema.org에 primary가 없을 때만 호출되므로 기본적으로 켜두는 것이 안전합니다.
디버깅 시 rawSignals.hasJsonLd를 먼저 확인하세요. 만약 true이지만 structured.schemaOrg.primary가 null이라면, 페이지가 우리가 매핑한 적이 없는 @type을 사용한 것입니다 — 이슈를 제기하면 추가하겠습니다.
structured.llmError는 정보성입니다. 요청은 여전히 성공적이며, 휴리스틱 결과도 여전히 반환됩니다. llmError.error를 확인하여 원인을 파악하세요 (타임아웃, JSON 파싱 실패, Zod 검증 실패).
비기사 페이지의 links[]는 관련성 정렬을 하지 않습니다. “최대 100개 + 유효하지 않은 프로토콜 필터링”에 따라 최선을 다해 정리합니다.
캐시 적중도 요금이 부과됩니다. 캐시는 지연 및 브라우저 풀 보호를 위해 존재하며, 비용 절감을 위한 것이 아닙니다.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

프록시

고급

WebExtrator 스마트 추출 API 통합 가이드

신청 절차

인증

요청 매개변수

동기 응답

최상위 필드

`data.structured` 하위 필드

schema.org 매핑기 범위

LLM 유형화 스키마

캐시

비동기 모드 및 콜백

예시

1. Wikipedia 기사 (schema.org 적중, LLM 필요 없음)

2. BestBuy 상품 페이지 (schema.org 적중)

3. AllRecipes 레시피 페이지 (영양 및 단계 포함)

4. HN 토론 페이지 (JSON-LD 없음 — LLM 활성화 필요)

5. Amazon 상품 페이지 (Amazon JSON-LD 없음 — LLM 활성화 필요)

Python (requests)

Node.js (fetch)

팁 및 주의사항

​신청 절차

​인증

​요청 매개변수

​동기 응답

​최상위 필드

​data.structured 하위 필드

​schema.org 매핑기 범위

​LLM 유형화 스키마

​캐시

​비동기 모드 및 콜백

​예시

​1. Wikipedia 기사 (schema.org 적중, LLM 필요 없음)

​2. BestBuy 상품 페이지 (schema.org 적중)

​3. AllRecipes 레시피 페이지 (영양 및 단계 포함)

​4. HN 토론 페이지 (JSON-LD 없음 — LLM 활성화 필요)

​5. Amazon 상품 페이지 (Amazon JSON-LD 없음 — LLM 활성화 필요)

​Python (requests)

​Node.js (fetch)

​팁 및 주의사항

신청 절차

인증

요청 매개변수

동기 응답

최상위 필드

`data.structured` 하위 필드

schema.org 매핑기 범위

LLM 유형화 스키마

캐시

비동기 모드 및 콜백

예시

1. Wikipedia 기사 (schema.org 적중, LLM 필요 없음)

2. BestBuy 상품 페이지 (schema.org 적중)

3. AllRecipes 레시피 페이지 (영양 및 단계 포함)

4. HN 토론 페이지 (JSON-LD 없음 — LLM 활성화 필요)

5. Amazon 상품 페이지 (Amazon JSON-LD 없음 — LLM 활성화 필요)

Python (requests)

Node.js (fetch)

팁 및 주의사항