# Guazi API — scrape China's largest used-car marketplace guazi.com (瓜子二手车): search ~127k live listings by city, brand, series and price band, then pull full car detail — price in CNY, original guide price, registration date, odometer, trim, engine, gearbox, emission standard, colour, city the car is actually in, dealer-vs-private seller type, insurance-claim and ownership-transfer counts, guazi's own 200-point inspection grade, and every listing photo. Plus the full brand, city and price-band catalogues and a 127k-id bulk feed. No API key, no login, no captcha.

> Search live guazi listings. `city` is the market (a guazi city slug like `bj`, `sh`, `sz` — or the Chinese city name), optionally narrowed by `brand` (e.g. `benz`, `bmw`, `byd`, `tesila`), `series` (e.g. `benz-e`, `bmw-5`, `model-3-60`) and `price_band` (`price0`…`price15`, the bands guazi itself publishes — see the `price_bands` action for their CNY ranges). 40 cars per page, pages 1–20 (guazi serves no page 21 for any facet, so one facet URL reaches at most 800 cars — narrow by brand/series/price_band to go deeper). ⚠️ `city` is a MARKET, not a location filter: guazi sells nationwide into each city, so rows legitimately carry other cities. Each row's own `city` is where that car physically is.
> ReefAPI engine `guazi` · 10 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/guazi/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/guazi/v1/search — 1 credit
Search live guazi listings. `city` is the market (a guazi city slug like `bj`, `sh`, `sz` — or the Chinese city name), optionally narrowed by `brand` (e.g. `benz`, `bmw`, `byd`, `tesila`), `series` (e.g. `benz-e`, `bmw-5`, `model-3-60`) and `price_band` (`price0`…`price15`, the bands guazi itself publishes — see the `price_bands` action for their CNY ranges). 40 cars per page, pages 1–20 (guazi serves no page 21 for any facet, so one facet URL reaches at most 800 cars — narrow by brand/series/price_band to go deeper). ⚠️ `city` is a MARKET, not a location filter: guazi sells nationwide into each city, so rows legitimately carry other cities. Each row's own `city` is where that car physically is.

**Parameters:**
- `city` (string, optional, default "bj") — Guazi city slug (`bj` 北京, `sh` 上海, `sz` 深圳, `gz` 广州, `cd` 成都, `cq` 重庆, `hz` 杭州, `nj` 南京, `wh` 武汉, `xa` 西安 … 320 in all) or the Chinese city name. Full list from the `cities` action.
- `brand` (string, optional) — Guazi brand slug — `benz` 奔驰, `bmw` 宝马, `audi` 奥迪, `dazhong` 大众, `toyota` 丰田, `honda` 本田, `byd` 比亚迪, `tesila` 特斯拉 … Full list from the `brands` action (use its `value` field).
- `series` (string, optional) — Guazi series slug, e.g. `benz-e` 奔驰E级, `bmw-5` 宝马5系, `audi-a6l` 奥迪A6L, `model-3-60` Model 3. Requires `brand`. Full list from the `series` action.
- `price_band` (enum, optional) — One of guazi's own 16 price bands (万 = 10,000 CNY). These are the ONLY price filters guazi's crawlable surface honours; an arbitrary min/max is not supported and is not faked here. [one of: price0, price1, price2, price3, price4, price5, price6, price7, price8, price9, price10, price11, price12, price13, price14, price15]
- `page` (integer, optional, default 1) — Page, 1–20. 40 cars per page. Guazi returns zero rows beyond page 20 for every facet.

**Returns:** cars[]{id, clue_id, title, year, city, mileage_km, mileage_display, price_cny, price_display, discount_cny, new_car_price_cny, inspected, tags[], thumbnail, url} + meta{total_results, result_pool_total, page, total_pages, max_page}

**Example request body:**
```json
{
  "city": "bj"
}
```

### POST https://api.reefapi.com/guazi/v1/detail — 1 credit
Everything guazi publishes about one car by `id` (a `c…` listing id from `search` or `listing_ids`): price in CNY and the original new-car guide price, registration month, odometer, brand/series/trim, manufacturer, engine, gearbox, emission standard, drive layout, colour, body class, the city the car is actually in, whether the seller is a dealer (商家) or a private owner (个人), the ownership-transfer count and insurance-claim count, guazi's own inspection grade + whether an official 200-point report exists, and every listing photo grouped by category. ⚠️ `vin` is always null: guazi publishes no VIN or chassis number for any car. When guazi publishes only its short record for a listing, the response carries the core fields (price, mileage, registration, condition, city) without photos, seller type or colour, and says so: `field_set` is `core` instead of `full` and `partial_fields` is set.

**Parameters:**
- `id` (string, required) — Guazi listing id — the `c…` token in a /car-detail/<id>.html URL, or a search row's `id`. The bare numeric form is also accepted.

**Returns:** car{id, clue_id, car_id, title, brand, brand_slug, series, series_slug, model_trim, manufacturer, year, first_registration, car_age, mileage_km, price_cny, price_display, new_car_price_cny, city, city_slug, market_city, seller_type, seller_type_raw, transfer_count, insurance_claim_count, condition_grade, condition_desc, appearance_score, inspection{official_report, report_level}, engine, transmission, emission_standard, drive_mode, color, body_class, energy_type, horsepower, displacement_l, is_parallel_import, is_new_car, is_defect_car, official_certification, store_url, spec_rows[], photo_count, photos[], photo_groups[], video_count, vin (always null — guazi does not publish it), url, field_set}

**Example request body:**
```json
{
  "id": "c173358342181138"
}
```

### POST https://api.reefapi.com/guazi/v1/brands — 1 credit
Every car brand guazi carries, with its guazi slug (`value`) for `search`'s `brand` filter, Chinese name and logo. Pass `letter` (A–Z, by the brand's pinyin initial) for one cheap page; omit it to sweep all 26 letters in one call. Read live, never from a hardcoded list.

**Parameters:**
- `letter` (string, optional) — Pinyin initial A–Z. Omit for all 26.

**Returns:** brands[]{id, name, slug, logo, letter} + meta{letters_fetched, letters_missing[]}

**Example request body:**
```json
{
  "letter": "B"
}
```

### POST https://api.reefapi.com/guazi/v1/series — 1 credit
Every series (车系) guazi lists for one brand, with the slug for `search`'s `series` filter — e.g. brand `benz` → 奔驰C级 `benz-c`, 奔驰E级 `benz-e`, …. Read live, so a newly listed series appears the day guazi lists it.

**Parameters:**
- `brand` (string, required) — Guazi brand slug, from the `brands` action.
- `city` (string, optional, default "bj") — City whose brand page to read (the series list is national; this only picks the page). Default `bj`.

**Returns:** brand{slug, name} + series[]{id, name, slug}

**Example request body:**
```json
{
  "brand": "benz"
}
```

### POST https://api.reefapi.com/guazi/v1/cities — 1 credit
All 300+ cities guazi operates in, each with the slug `search`'s `city` takes, the Chinese name, the pinyin and guazi's own city id — plus which cities guazi itself marks as hot. Read live.

**Parameters:** none

**Returns:** cities[]{slug, name, pinyin, city_id} + hot_cities[]{slug, name}

### POST https://api.reefapi.com/guazi/v1/price_bands — 1 credit
Guazi's 16 price bands with their real CNY ranges and the slug `search`'s `price_band` takes. Read live, so the ranges are guazi's current ones rather than a copy.

**Parameters:**
- `city` (string, optional, default "bj") — City page to read the bands from. Default `bj`.

**Returns:** price_bands[]{slug, label, min_cny, max_cny}

**Example request body:**
```json
{
  "city": "bj"
}
```

### POST https://api.reefapi.com/guazi/v1/listing_ids — 1 credit
Bulk id feed: up to 10,000 live listing ids per page, each with the date guazi last updated it. 13 pages cover the whole live inventory (~127,000 cars). Built for backfills and change detection: pull ids here, then `detail` only the ones that changed.

**Parameters:**
- `page` (integer, optional, default 1) — Page 1–13. ~10,000 ids each; the last page is shorter.

**Returns:** ids[]{id, url, lastmod} + meta{page, total_pages, page_size}

**Example request body:**
```json
{
  "page": 1
}
```

### POST https://api.reefapi.com/guazi/v1/export_search — 3 credits
Search guazi's China used-car EXPORT & auction marketplace — a different inventory from `search`: ~180,000 cars listed for overseas buyers with English titles, FOB prices in US dollars, A–D condition grades, accident/water/fire damage flags, dealer-vs-private seller type and live auctions. ⚠️ On an auction row guazi publishes the CURRENT BID, not an asking price, so that number comes back as `current_bid_usd` with `price_usd` null and `price_kind` = `auction_bid` — a fixed-price row is the other way round. Narrow by `brand` (e.g. `audi`, `bmw`, `toyota`), `series` (e.g. `q8`, `x1`, `camry`) or `body_type` (sedan, suv, mini-van, hatchback, wagon, pick-up, van, truck). Returns the 20 cars guazi puts on that facet's first page plus the facet's own live total. ⚠️ Only 20 cars per facet are reachable: guazi serves no second page of this marketplace to anyone who is not running its JavaScript, so narrow by brand → series instead of paging. Use `export_brands` for the brand list and `export_detail` with a returned `id` for the full record.

**Parameters:**
- `brand` (string, optional) — Export-site brand slug — `audi`, `bmw`, `byd`, `toyota`, `honda`, `nissan`, `volkswagen`, `mercedes-benz`, `hyundai`, `geely-auto` … Full list from `export_brands`.
- `series` (string, optional) — Export-site series slug under that brand, e.g. `q8`, `a4l`, `x1`, `3-series`, `camry`, `c-class`. Requires `brand`.
- `body_type` (enum, optional) — Body style. Cannot be combined with brand/series — guazi publishes them as separate facets. [one of: sedan, suv, mini-van, hatchback, wagon, pick-up, van, truck]

**Returns:** cars[]{id, car_id, title, url, model_year, manufactured, first_registration, mileage_km, fuel_type, engine, transmission, is_electric, battery_capacity_kwh, ev_range_km, price_usd, current_bid_usd, price_kind, list_price_usd, discount_usd, exchange_rate_cny_per_usd, brand, brand_id, series_id, condition_grade, seller_type, inspected, open_to_offers, newly_listed, auction{type, name, preview_ends_at, countdown_ms}, labels[], thumbnail, has_video} + meta{total_results, rows_per_page}

**Example request body:**
```json
{
  "brand": "audi"
}
```

### POST https://api.reefapi.com/guazi/v1/export_detail — 3 credits
Everything guazi publishes about one car on its export marketplace: the masked VIN (first 3 + last 4 characters, which is what guazi itself shows), the A–D condition grade, explicit accident / water-damage / fire-damage flags, whether an official Guazi inspection report exists, the FOB price in USD with guazi's own CNY exchange rate, model year, manufacture and first-registration dates, odometer, engine, horsepower, gearbox, drive train, body style, seats, doors, colour, exterior dimensions, which side the steering wheel is on, the Chinese city the car is in, the full options/config sheet and every photo. Takes the `id` from `export_search` (a listing slug such as `audi-q8-2019-30l-blue-142800km-at-4wd-5-seats-lz3kf79f3f.html`); a full en.guazi.com product URL is accepted too.

**Parameters:**
- `id` (string, required) — A listing slug from `export_search`'s `id`, or the full product URL. The short item number alone (e.g. `lz3kf79f3f`) is NOT enough — guazi 404s it, the full slug is required.

**Returns:** car{id, car_id, slug, title, url, vin_masked, condition_grade, damage{accident, water, fire}, official_report, price_usd, current_bid_usd, price_kind, discount_usd, exchange_rate_cny_per_usd, brand, model_year, manufactured, first_registration, mileage_km, fuel_type, engine, horsepower_ps, transmission, drive_train, body_style, seats, doors, exterior_color, dimensions_mm, steering, location, spec_rows[], config_groups[], photo_count, photos[], thumbnail, business_type, auction{type}}

**Example request body:**
```json
{
  "id": "c173358342181138"
}
```

### POST https://api.reefapi.com/guazi/v1/export_brands — 2 credits
Every brand guazi carries on its export marketplace, with the slug `export_search`'s `brand` takes, the English name, guazi's brand id and the logo. Read live.

**Parameters:** none

**Returns:** brands[]{id, name, slug, logo} + body_types[]

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=guazi
- Human docs page: https://reefapi.com/docs/guazi
- Overview page: https://reefapi.com/guazi-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt