结构化工具2 credits

scrape_structured

使用自定义 CSS 选择器从任意网页提取结构化数据。非常适合电商商品抓取、新闻聚合以及任何自定义数据提取需求。

使用场景

电商商品抓取

从在线商店提取商品标题、价格、描述和图片

新闻文章提取

从新闻站点提取标题、作者、日期和正文

自定义数据转换

将任意 HTML 结构映射到你期望的 JSON schema

房产房源

从房源站点提取房产详情、价格和图片

Endpoint

POST/api/v1/tools/scrape_structured

Auth Required

Free 计划 1 req/s

2 credits

Parameters

Name	Type	Required	Default	Description
url	string	Optional	-	要抓取并从中提取数据的页面。`url` 与 `html` 二者必填其一。 Example: https://example.com/product
html	string	Optional	-	直接解析的原始 HTML，替代抓取。请配合 `base_url` 使用，以解析相对属性值。 Example: <html>...</html>
selectors	object	Required	-	把您自定义的字段名映射到 CSS 选择器。至少需要一条——字段名由您决定，并会原样出现在结果中。 Example: {"title": "h1.product-title", "price": ".price", "description": ".product-desc"}
base_url	string	Optional	-	用于解析所提取属性中相对 URL 的基地址。 Example: https://example.com
multiple	boolean	Optional	false	为 true 时提取一组重复条目，而不是单条记录。这会改变响应结构，详见下文。 Example: true
clean_text	boolean	Optional	true	折叠空白字符并去除所提取文本的首尾空格。 Example: true
include_attributes	array	Optional	-	除文本外，还从每个匹配元素上捕获这些 HTML 属性。 Example: ["href", "src", "alt"]
max_items	number	Optional	100	`multiple` 为 true 时返回的最大条目数，1-1000。 Example: 100
respect_robots	boolean	Optional	true	遵守目标站点的 robots.txt。保持 `true` 时，robots.txt 对 `CrawlForge` 禁止的路径会在抓取之前以 403 拒绝，且不扣除 credits。仅在你与目标站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`，并且该覆盖会记录到你的 API key 上。 Example: true

CSS 选择器：

可使用任何有效的 CSS 选择器语法。常见写法：

.className - 按 class 选择
#id - 按 ID 选择
tag.class - 组合标签和 class
.parent > .child - 直接子元素
[data-id="value"] - 属性选择器

请求示例

cURL - 电商商品

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/scrape_structured \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/123",
    "selectors": {
      "title": "h1.product-title",
      "price": ".price-value",
      "currency": ".price-currency",
      "description": ".product-description",
      "image": "img.main-image",
      "rating": ".rating-value",
      "availability": ".stock-status"
    }
  }'

TypeScript - 新闻文章

scrapeStructured.tsTypescript

// npm install crawlforge-sdk
import { CrawlForge } from 'crawlforge-sdk';

const client = new CrawlForge({ apiKey: process.env.CRAWLFORGE_API_KEY });

const result = await client.scrapeStructured({
  url: 'https://example.com/news/article-123',
  selectors: {
    headline: 'h1.article-title',
    author: '.author-name',
    publishDate: 'time.publish-date',
    category: '.category-tag',
    content: '.article-body',
    image: '.article-image img'
  }
});

// result.data is untyped in crawlforge-sdk 0.1 — its shape is the Response Example below.
const article = result.data as { headline: string; author: string; publishDate: string };
console.log('Article:', article.headline);
console.log('By:', article.author);
console.log('Published:', article.publishDate);

Python - 房产房源

scrape_structured.pyPython

# pip install crawlforge
from crawlforge import CrawlForge

client = CrawlForge()  # reads CRAWLFORGE_API_KEY

result = client.scrape_structured(
    url='https://example.com/property/456',
    selectors={
        'address': '.property-address',
        'price': '.listing-price',
        'bedrooms': '.bed-count',
        'bathrooms': '.bath-count',
        'sqft': '.square-feet',
        'description': '.property-description',
        'images': '.gallery img'
    },
)

# result.data is a plain dict — its shape is the Response Example below.
property_data = result.data
print(f"Property: {property_data['address']}")
print(f"Price: {property_data['price']}")
print(f"Beds: {property_data['bedrooms']}")
print(f"Baths: {property_data['bathrooms']}")

响应示例

200 OK320ms

{
  "success": true,
  "data": {
    "title": "Premium Wireless Headphones",
    "price": "299.99",
    "currency": "USD",
    "description": "High-quality wireless headphones with active noise cancellation and 30-hour battery life.",
    "image": "https://example.com/images/headphones.jpg",
    "rating": "4.7",
    "availability": "In Stock"
  },
  "credits_used": 2,
  "credits_remaining": 998,
  "processing_time": 320
}

Field Descriptions

data.title从 h1.product-title 选择器提取

data.price从 .price-value 选择器提取

data.description从 .product-description 选择器提取

credits_used本次请求扣除的 credits（每次抓取 2 个）

错误处理

被 robots.txt 拦截（403 Forbidden）

目标站点的 robots.txt 对 CrawlForge 禁止了该路径。若你与目标站点另有约定，可设置 respect_robots: false 予以覆盖——该覆盖会记录到你的 API key 上。该覆盖不适用于列入 CrawlForge 永久排除名单的主机——无论 respect_robots 取何值，这类主机一律被拒绝。

credit 费用