# 21-sun Machinery Catalog Scraper 铁臂商城 – China Specs & Models (`rastriq/21-sun-machinery-catalog-scraper`) Actor

Scrape the new construction-machinery catalog of 21-sun.com (铁臂商城 / 中国工程机械商贸网): ~31,000 models with brand, category, images and full specs. Inquiry-only site: no prices. 铁臂商城数据采集。

- **URL**: https://apify.com/rastriq/21-sun-machinery-catalog-scraper.md
- **Developed by:** [Rastriq — Structured data from the world](https://apify.com/rastriq) (community)
- **Categories:** E-commerce, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.75 / 1,000 listing results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 21-sun.com New Machinery Catalog Scraper

Extract the **new construction-machinery catalog** of **21-sun.com (铁臂商城 / Tiebi Shangcheng)**, China's reference portal for heavy equipment: ~31,000 current models of excavators, loaders, cranes, bulldozers, pumps, rollers, forklifts and more, with brand, category, images and full technical specifications.

Built by [Rastriq](https://rastriq.es). Pure HTTP (no browser): fast, cheap and light on the source site.

> **Important — what this actor does NOT return**
>
> - **No prices.** 21-sun.com is an inquiry-only catalog ("立即询价"); it publishes no list or reference prices. `priceCny` is always `null` and every item carries the `price_on_request` quality flag.
> - **No used-equipment listings.** The used marketplace (`used.21-sun.com`) currently answers HTTP 404 on every path, so it is not offered.

### 🇨🇳 中文说明

**铁臂商城（21-sun.com，中国工程机械商贸网）新机产品库数据采集工具**：无需浏览器、无需登录，批量抓取挖掘机、装载机、起重机、推土机、泵车、压路机、叉车等约 3.1 万个机型。

- **可采集字段：** 机型名称、品牌、型号、类别、产品图片、主要参数（如整机重量、发动机功率）；开启“详情”后另含完整技术参数（约 20–67 项）、更新时间，以及授权经销商（企业名称与地区）。
- **注意：** 铁臂商城为询价制，不公布价格（`priceCny` 始终为空并标记 `price_on_request`）；原二手频道已下线，不在采集范围内。
- **使用方法：** 选择设备类别（如 挖掘机、装载机、起重机）和品牌（如 三一、徐工、卡特彼勒），可选关键词，设置最大条数后点击 **Start**。
- **适用人群：** 工程机械经销商、进出口贸易商、厂商竞品与产品规划团队、行业研究机构。
- **导出格式：** JSON、CSV、Excel 或通过 API 获取，字段结构与 Rastriq 其他中国工业设备采集器统一。
- **合规说明：** 遵守网站 robots.txt；仅采集公开的企业与设备信息，不采集联系人姓名、手机号码、微信/QQ 等个人信息。
- **计费：** 按结果计费：列表数据每 1,000 条 $1.00，含详情每 1,000 条 $3.00（每条只计费一次），每次运行另收 $0.005；更高等级的 Apify 套餐自动享受折扣。平台算力已包含；如自备代理（例如住宅代理），代理流量费用由您的代理服务商收取，不含在本工具价格内。

### What you get

- Complete model catalog by category, brand and sale status (on sale / discontinued)
- Normalized brand, model code, category path and main image
- Key specs straight from the listing (2 values per model), or the **full spec sheet** (20-60 lines: engine, weights, dimensions, hydraulics...) with `includeDetails`
- Parsed numeric helpers: `ext_operatingWeightKg`, `ext_enginePowerKw`
- Model update date, image gallery and authorized dealers (company name / region / address) as options

### Who is it for

Market analysts, OEM and dealer competitive-intelligence teams, spec-comparison tools, leasing / valuation models that need a clean Chinese-market model & spec database, and data teams enriching their machinery taxonomy.

### Input

| Field | Description |
|---|---|
| `section` | `new_catalog` (the only live section) |
| `categories` | Dropdown with the site's full category tree (19 groups, 129 subcategories; codes such as `101001`, `101002`, `102`). Picking a group (“Excavators (all)”) downloads all its subcategories, each crawled as its own listing. Empty = whole catalog |
| `brands` | Dropdown with the 513 brands of the site (“SANY · 三一”); you can also type Chinese names, aliases (`sany`, `xcmg`, `komatsu`, `caterpillar`...) or site brand ids |
| `keyword` | Case-insensitive filter on title/brand, applied while paging |
| `saleStatus` | `on_sale` (default), `discontinued`, `all` |
| `maxItems` | Default 100, `0` = unlimited |
| `includeDetails` | Fetch each model page (+1 request/model) |
| `includeFullSpecs` | With details: also fetch the parameter page (+1 request/model), default on |
| `includeSellerContact` | With details: add `ext_dealers` (company data only, no phones) |
| `maxConcurrency` / `requestDelayMs` | Default 3 / 500 ms (be polite) |
| `proxyUrl` | Optional, e.g. `http://user:pass@gate.decodo.com:7000` |

Example:

```json
{ "categories": ["101001"], "brands": ["sany", "xcmg"], "maxItems": 50, "includeDetails": true }
```

### Output

| Field | Type | Notes |
|---|---|---|
| `source`, `sourceSection` | string | `21-sun.com`, `new_catalog` |
| `listingId`, `url` | string | Site model id and page |
| `title`, `brand`, `model` | string | Chinese title; brand; model code parsed from the title |
| `category`, `categoryPath` | string / list | Category (and sub-category with details) |
| `condition` | string | always `new` |
| `priceCny`, `priceText`, `priceType` | null / null / `on_request` | Site publishes no prices |
| `year`, `hours`, `location`, `seller` | empty | Not applicable to a new-model catalog |
| `images` | list | Absolute https URLs |
| `specs` | object | Spec name -> value, Chinese keys as published |
| `updatedAt` | string | Model page update date (with details) |
| `qualityFlags` | list | `price_on_request`, `category_missing`, `model_unparsed`, `specs_missing`, `no_image`, `detail_fetch_failed` |
| `ext_categoryCode`, `ext_categoryEn`, `ext_saleStatus`, `ext_operatingWeightKg`, `ext_enginePowerKw`, `ext_onPromotion`, `ext_dealers` | various | Site-specific extras |
| `scrapedAt` | string | UTC ISO 8601 |

Sample item (`includeDetails=true`):

```json
{
  "source": "21-sun.com",
  "sourceSection": "new_catalog",
  "listingId": "20379",
  "url": "https://product.21-sun.com/proDetail/20379.shtm",
  "title": "厦工XG955K轮式装载机",
  "category": "轮式装载机",
  "categoryPath": [
    "装载机",
    "轮式装载机"
  ],
  "brand": "厦工",
  "model": "XG955K",
  "year": null,
  "hours": null,
  "condition": "new",
  "priceCny": null,
  "priceText": null,
  "priceType": "on_request",
  "location": {
    "province": null,
    "city": null,
    "raw": null
  },
  "seller": {
    "name": null,
    "type": null,
    "shopUrl": null
  },
  "images": [
    "https://product.21-sun.com/uploadfiles/image/2025/06/20250624144127_366.jpg"
  ],
  "specs": {
    "斗容": "2.2-4.5m3",
    "额定载重量": "5000kg",
    "工作重量": "17200kg",
    "额定功率": "162kw",
    "挖掘力": "180kN",
    "最大牵引力": "165kN"
  },
  "postedAt": null,
  "updatedAt": "2025-12-29",
  "qualityFlags": [
    "price_on_request"
  ],
  "scrapedAt": "2026-10-20T22:55:51+00:00",
  "ext_categoryCode": "101002007",
  "ext_categoryEn": "Wheel loaders",
  "ext_saleStatus": "on_sale",
  "ext_operatingWeightKg": 17200,
  "ext_enginePowerKw": 162.0,
  "ext_onPromotion": false,
  "ext_detailFetched": true
}
```

### Cost and speed

Pay-per-event pricing — you pay only for items that land in your dataset, never for retries or failed pages. Higher Apify plans get automatic volume discounts:

| Event (per 1,000 results) | Free | Bronze | Silver | Gold | Platinum | Diamond |
|---|---|---|---|---|---|---|
| **Listing result** (Include model details off) | $1.00 | $0.90 | $0.85 | $0.75 | $0.65 | $0.60 |
| **Detailed result** (Include model details on) | $3.00 | $2.70 | $2.55 | $2.25 | $1.95 | $1.80 |

Plus **$0.005 per run** (Actor start). Each item is charged **either** as a listing result **or** as a detailed result — never both; if a detail page cannot be fetched, that item is charged at the listing price.

*Example:* 1,000 items with details on the Free plan ≈ **$3.00**; 10,000 listing-only items ≈ **$10.00**.

Platform compute is included in the price. **Proxy:** not needed by default. If you add your own proxy (for example a residential proxy) in *Proxy URL*, that traffic is billed by your proxy provider and is **not** included in the Actor price. Use *Max items* or the run's *Maximum cost per run* to cap your spend.

| Mode | Requests / item | Speed (3 concurrent, 500 ms delay) |
|---|---|---|
| Listing only | ~0.03 | ~2-13 s per 100 models |
| `includeDetails` (no full specs) | ~1.03 | ~2-3 min per 100 models |
| `includeDetails` + full specs | ~2.03 | ~3-4 min per 100 models |

The whole catalog (~31,000 models) is ~970 listing pages. Raise `maxConcurrency` (max 10) for details runs.

### Limits

- No prices and no used listings (see above).
- Picking a group crawls its subcategories, not the group page. A few models are classified only at group level on the site and are then not returned (aerial work equipment ~7 %, piling machinery ~6 %, graders/scrapers, port machinery); leave `categories` empty to get the whole catalog. Subcategories can overlap (commercial vehicles); models are deduplicated.
- `category` is empty for whole-catalog runs unless `includeDetails` is on; select categories to fill it.
- `keyword` is a client-side filter (the site has no usable search endpoint), so combine it with a category/brand.
- Specs are in Chinese as published; spec keys vary by model.
- The site may throttle or block heavy parallel scraping from some regions; the actor retries with backoff and logs blocks.

### FAQ

**Can I get prices?** Not from this site: it only offers dealer quotes after an inquiry.
**Why only 2 specs per model without details?** That's all the listing shows; enable `includeDetails` for the full sheet.
**Is personal data collected?** No. Only product data and, optionally, authorized-dealer company name, region and address.
**Is scraping allowed?** The actor only requests public catalog pages that are not disallowed by the site's robots.txt, at a low request rate. You are responsible for complying with applicable laws and the site's terms.

# Actor input Schema

## `section` (type: `string`):

Catalog section to scrape. Only <b>new_catalog</b> (new machines, ~31,000 models) is available: the used marketplace <code>used.21-sun.com</code> currently answers 404 on every path.

## `categories` (type: `array`):

Equipment categories of the 21-sun catalog (type to filter, English or Chinese). <b>Leave empty to scrape the whole catalog</b> (in that case <code>category</code> is only filled when <code>includeDetails</code> is on). <b>Choosing a parent such as “Excavators (all)” downloads all its subcategories</b>: each one is crawled separately, so the per-category page cap never applies. Categories are deduplicated.

## `brands` (type: `array`):

Filter by brand (optional; empty = all brands). Pick from the 513 brands listed by the site (type to filter, English or Chinese) or type your own: Chinese names (<code>三一</code>), aliases (<code>sany</code>, <code>komatsu</code>, <code>caterpillar</code>…) or the numeric site id (e.g. <code>133</code>) are all accepted.

## `keyword` (type: `string`):

Case-insensitive text filter applied to the model title and brand (e.g. <code>SY75</code>, <code>小型</code>). The site has no usable search endpoint, so this is applied while paging the listing: narrow it with category/brand to keep it fast.

## `saleStatus` (type: `string`):

<b>on_sale</b> = current models, <b>discontinued</b> = models no longer produced, <b>all</b> = both (<code>ext_saleStatus</code> is then null).

## `maxItems` (type: `integer`):

Maximum number of models to return. Use a small value (5-10) for a first test. <code>0</code> = no limit.

## `includeDetails` (type: `boolean`):

Fetch each model's page: update date, sub-category, image gallery and technical specs (~13 values). <b>Slower</b>: +1 request per model.

## `includeFullSpecs` (type: `boolean`):

Only used when <b>Include model details</b> is on. Also fetches the parameter page (20-60 spec lines: engine, dimensions, hydraulics…). +1 request per model.

## `includeSellerContact` (type: `boolean`):

Only with <b>Include model details</b>. Adds <code>ext_dealers</code>: company name, sales region and company address of the authorized dealers listed on the model page. No phone numbers or personal data are collected.

## `maxConcurrency` (type: `integer`):

Parallel requests (1-10).

## `requestDelayMs` (type: `integer`):

Base delay before each request, with ±50% random jitter.

## `proxyUrl` (type: `string`):

Custom proxy, e.g. <code>http://user:pass@gate.decodo.com:7000</code>. Leave empty to connect directly. <b>Proxy traffic is billed by your own proxy provider</b> and is not included in this Actor's price.

## `debugMode` (type: `boolean`):

Verbose logging of every request.

## Actor input object example

```json
{
  "section": "new_catalog",
  "categories": [
    "101001"
  ],
  "brands": [],
  "saleStatus": "on_sale",
  "maxItems": 10,
  "includeDetails": false,
  "includeFullSpecs": true,
  "includeSellerContact": false,
  "maxConcurrency": 3,
  "requestDelayMs": 500,
  "debugMode": false
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset with all scraped models in the normalized Rastriq machinery schema.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "categories": [
        "101001"
    ],
    "brands": [],
    "keyword": "",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("rastriq/21-sun-machinery-catalog-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "categories": ["101001"],
    "brands": [],
    "keyword": "",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("rastriq/21-sun-machinery-catalog-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "categories": [
    "101001"
  ],
  "brands": [],
  "keyword": "",
  "maxItems": 10
}' |
apify call rastriq/21-sun-machinery-catalog-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rastriq/21-sun-machinery-catalog-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/QR1A4kRw1bGLVGDeh/builds/avrcuAVbw9seSpRVq/openapi.json