# Chợ Tốt API scraper — Vietnam's largest classifieds marketplace: keyword/category search across goods, vehicles and property with province, district, price, seller-type and sale-vs-rent filters, full listing detail with the vertical's own attributes, plus live category and region resolvers — vi-VN, prices in đồng, no API key required

> Search Chợ Tốt listings by keyword and/or category, narrowed by province, district, ward, price range, sale-vs-rent and seller type, sorted by date, price or relevance. Works across every vertical — second-hand goods, vehicles and property — and returns up to 50 rows a page with the price both as an integer in đồng and as the string the site prints, plus that vertical's own attribute rows.
> ReefAPI engine `chotot` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/chotot/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.
- **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). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/chotot/v1/search — 1 credit
Search Chợ Tốt listings by keyword and/or category, narrowed by province, district, ward, price range, sale-vs-rent and seller type, sorted by date, price or relevance. Works across every vertical — second-hand goods, vehicles and property — and returns up to 50 rows a page with the price both as an integer in đồng and as the string the site prints, plus that vertical's own attribute rows.

**Parameters:**
- `q` (string, optional) — Free-text keyword, Vietnamese or English ('iphone', 'xe máy honda', 'căn hộ quận 7'). Optional: leave it out and pass `category` to browse a whole section. At least one of `q` or `category` is required.
- `category` (integer, optional) — Chợ Tốt category id — a top-level group (1000 property, 2000 vehicles, 5000 electronics…) or a leaf (5010 mobile phones, 1020 houses, 2010 cars, 2020 motorbikes). Call the `categories` action for the full live tree.
- `region` (integer, optional) — Province/city id (13000 = TP Hồ Chí Minh, 12000 = Hà Nội). The `regions` action lists all 63 with their districts.
- `area` (integer, optional) — District id inside the chosen region (13096 = Quận 1). Take it from the `regions` action; pass `region` with it.
- `ward` (integer, optional) — Ward id — the narrowest level below a district, when you have one from a listing's own ward.
- `price_min` (integer, optional) — Lowest price in Vietnamese đồng (1000000 = 1.000.000 đ ≈ 1 triệu). Property prices run into the tỷ (10^9).
- `price_max` (integer, optional) — Highest price in Vietnamese đồng.
- `ad_type` (enum, optional) — Sale listings or rental listings. Only meaningful in categories that have both (property, some services); each returned row echoes its own `ad_type`. [one of: sell, rent]
- `seller_type` (enum, optional) — Restrict to private individuals or to professional sellers/shops. [one of: private, pro]
- `sort` (enum, optional) — Result ordering. Defaults to relevance when `q` is given, newest otherwise — exactly like the site. [one of: newest, relevance, price_asc, price_desc]
- `limit` (integer, optional, default 20) — Rows per page, 1-50. Chợ Tốt itself refuses more than 50.
- `page` (integer, optional, default 1) — 1-based page number. Page forward with meta.next_page. Chợ Tốt is a live feed: under relevance ordering consecutive pages repeat about one row in twenty, and more the longer you wait between calls. Sort by `newest` when you are walking every page and want them disjoint.
- `offset` (integer, optional) — Row offset, if you would rather skip a precise number of rows than count pages. Overrides `page` when given.

**Returns:** listings[]{ad_id, list_id, url, title, description, price, price_string, price_valid, currency, ad_type, category_id, category_name, region_id, region_name, area_id, area_name, ward_name, posted_at, posted_relative, image, images[], image_count, video_count, is_promoted, seller{account_id, name, shop_id, is_shop_verified, is_official_store, rating, rating_count, avatar}, phone (as published; Chợ Tốt masks its tail), phone_hidden, latitude, longitude, attributes[]{id, label, value}} + meta{total, total_is_capped, page, limit, offset, has_more, next_page, filters_applied[]}

**Example request body:**
```json
{
  "q": "iphone",
  "category": 5010
}
```

### POST https://api.reefapi.com/chotot/v1/detail — 1 credit
One listing in full by `ad_id` (or by its chotot.com address): title, body text, price in đồng plus the printed price string, category, province/district/ward, posting time, the whole image gallery, the public seller profile, and the complete attribute set for that vertical — capacity and warranty for a phone, rooms and direction for a house, year, mileage, fuel and gearbox for a car.

**Parameters:**
- `ad_id` (integer, optional) — Chợ Tốt ad id — the `ad_id` of a search result. This is NOT the number in the listing's web address; pass that one as `url` instead.
- `url` (string, optional) — Full chotot.com listing address. The number in the address is the `list_id`, which the engine resolves to the `ad_id` for you (one extra lookup). Use `ad_id` directly when you already have it.

**Returns:** listing{ad_id, list_id, url, title, description, price, price_string, price_valid, currency, ad_type, category_id, category_name, region_id, region_name, area_id, area_name, ward_name, posted_at, image, images[], seller{...}, phone, phone_hidden, latitude, longitude, attributes[]{id, label, value} (address rows included)}

**Example request body:**
```json
{
  "url": "https://www.chotot.com/mua-ban-dien-thoai-quan-1-tp-ho-chi-minh/134990763.htm"
}
```

### POST https://api.reefapi.com/chotot/v1/categories — 1 credit
The live Chợ Tốt category tree — 14 top-level groups (property, vehicles, electronics, home & living, jobs, pets, services…) with their leaf categories and the ad types each one supports. Use it to get the `category` id that `search` needs.

**Parameters:** none

**Returns:** categories[]{category_id, name, subcategories[]{category_id, name, slug, ad_types[]}} + meta{total}

### POST https://api.reefapi.com/chotot/v1/regions — 1 credit
The live Vietnamese province/city list (63 entries) with every district inside each one. Use it to get the `region` and `area` ids that `search` filters on.

**Parameters:**
- `region` (integer, optional) — Return only this province/city and its districts. Omit for all 63.

**Returns:** regions[]{region_id, name, areas[]{area_id, name}} + meta{total}

**Example request body:**
```json
{
  "region": 13000
}
```

## 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=chotot
- Human docs page: https://reefapi.com/docs/chotot
- Overview page: https://reefapi.com/chotot-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
