# Chotot Scraper - Vietnam Marketplace Listings (`hgservices/chotot-scraper`) Actor

Chotot scraper to extract listings and classified ads from Chotot.com, Vietnam's largest marketplace. Scrape products by keyword, category, region, and price. Get full listing data including images, seller info, and GPS coordinates. Fast, low-cost, export to JSON, CSV, or Excel

- **URL**: https://apify.com/hgservices/chotot-scraper.md
- **Developed by:** [Harish Garg](https://apify.com/hgservices) (community)
- **Categories:** E-commerce, Lead generation, AI
- **Stats:** 1 total users, 0 monthly users, 80.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 ad records

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What does Chotot Scraper do?

**Chotot Scraper** extracts marketplace ad listings from [Chotot.com](https://www.chotot.com), **Vietnam's largest online classifieds site**. Give it a keyword, a category, a region, or a price range, and it returns **full listing data** — title, full description, price, images, GPS coordinates, seller details, and category-specific attributes — as clean, structured JSON.

It is **fast and low-cost to run**. On the Apify platform you also get API access, scheduling, integrations (Google Sheets, Make, Zapier, webhooks), automatic proxy rotation, and run monitoring.

It covers the **10 general marketplace categories** (electronics, home & furniture, fashion, hobbies, pets, appliances, mom & baby, office & agriculture, services, and food). Property, vehicles, and jobs are served by dedicated companion Actors (see [Companion Actors](#companion-actors)).

### Why use Chotot Scraper?

- **Market research** — track prices, inventory, and demand across Vietnamese categories and provinces.
- **Lead generation** — collect seller names, IDs, and locations for C2C outreach.
- **Price intelligence** — monitor how prices for a product move over time and by region.
- **Reselling & arbitrage** — spot underpriced items the moment they are listed with scheduled runs.
- **Data & ML** — build datasets of Vietnamese product listings with images and full descriptions.

### How to use Chotot Scraper

1. Open the **Input** tab.
2. Type a **Search keyword** (e.g. `iphone`) and/or pick one or more **Categories**.
3. Optionally narrow by **Region**, **price range**, or **ad type**.
4. Set **Max items** to control run size (start small to preview).
5. Click **Start** and watch results fill the **Output** tab.
6. Export the dataset as **JSON, CSV, Excel, or HTML**, or pull it via the Apify API.

#### Input examples

**Keyword search across one category**

```json
{ "search": "iphone 15", "categoryIds": ["5000"], "maxItems": 500 }
```

**Category + region sweep**

```json
{ "categoryIds": ["3000", "14000"], "regionId": "13000", "adType": "sell", "maxItems": 2000 }
```

**Newest ads in one category**

```json
{ "categoryIds": ["5000"], "maxItems": 100 }
```

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `search` | string | — | Full-text keyword. Combinable with every filter. |
| `categoryIds` | multi-select | all 10 general categories | The general categories to scrape (pick one or more from the dropdown). |
| `adType` | enum | `all` | `all`, `sell`, `buy`, `rent_out`, or `want_rent`. |
| `regionId` | enum | (any) | One of the 63 provinces (e.g. `13000` = Ho Chi Minh City, `12000` = Hanoi). |
| `maxItems` | integer | 50 | Number of ads to fetch **per category**. Total ≈ `maxItems` × number of categories. |
| `enrichDetails` | boolean | false | Add human-labeled category attributes (brand, condition, warranty…). Costs one extra request per ad. |

#### Ordering

The Actor returns the **newest ads first**, up to `maxItems` per category.

### Output

Each dataset item is one ad. Simplified example:

```json
{
  "adId": 177860964,
  "listId": 133911444,
  "url": "https://www.chotot.com/133911444.htm",
  "title": "iPhone 8",
  "price": 1550000,
  "priceString": "1.550.000 đ",
  "categoryId": 5010,
  "categoryName": "Điện thoại",
  "adType": "s",
  "regionName": "Bình Dương",
  "areaName": "Thành phố Thuận An",
  "latitude": 10.957153,
  "longitude": 106.71757,
  "images": ["https://cdn.chotot.com/.../plain/....jpg"],
  "numberOfImages": 4,
  "listedAt": "2026-08-02T22:24:53.000Z",
  "seller": { "id": 26144388, "oid": "17e5f73e...", "name": "Gia Huy", "avatar": "https://cdn.chotot.com/uac2/26144388" },
  "categoryFields": { "mobile_brand": 1, "elt_condition": 2 }
}
```

You can download the dataset in various formats such as **JSON, HTML, CSV, or Excel**.

#### Data fields

| Field | Description |
|---|---|
| `adId`, `listId` | The two Chotot identifiers. `listId` builds the public listing URL. |
| `url` | Canonical public listing URL. |
| `title`, `description` | Ad subject and full body text. |
| `price`, `priceString` | Numeric price (VND) and the display string. |
| `categoryId`, `categoryName` | Subcategory-level classification. |
| `adType` | `s` sell, `k` buy, `u` rent out, `h` want to rent. |
| `regionId/Name`, `areaId/Name`, `wardId/Name` | Province, district, and ward. |
| `latitude`, `longitude` | GPS coordinates (present on most ads). |
| `images`, `numberOfImages` | Full-size CDN image URLs. |
| `videos` | Video attachments, if any. |
| `listedAt`, `relativeDate` | ISO 8601 timestamp and the raw Vietnamese relative date. |
| `seller` | `id`, `oid`, `name`, `avatar`, and `liveAds` count. |
| `state`, `status` | Moderation state and activity status. |
| `categoryFields` | Category-specific attributes (e.g. `rooms`, `mobile_brand`, `elt_condition`). |
| `attributes` | Human-readable category-specific specs as a `{ key: value }` object (e.g. `mobile_brand: "Apple"`, `mobile_capacity: "256 GB"`, `address: "…"`). Only present when `enrichDetails` is on. |

### Pricing and cost estimation

This Actor is billed **pay-per-event** with **no start-up fee** — you pay only for what it produces:

- **Ad record** — charged once for every ad returned. This is the main cost.
- **Detail enrichment** — charged additionally, once per ad, only when you turn on **"Add on: Enrich with extra ad details"**. A plain run never incurs this.

So a basic run costs `ad-record × items`, and an enriched run costs `(ad-record + detail-enrichment) × items`. You can cap any run's spend with the **maximum cost** setting in the Console — the Actor stops once the limit is reached.

**Max items** applies per category, so the number of ads ≈ **Max items × number of categories**. Lower it, or select fewer categories, to keep any run small.

### Tips and advanced options

- **Schedule runs** to keep a fresh snapshot of the newest ads per category.
- **Enable `enrichDetails`** only when you need labeled attributes — it adds one request per ad.
- **Raise `maxItems`** to pull more ads per category; **lower it or pick fewer categories** to keep runs small.

### Companion Actors

The same Chotot backend powers several verticals, split into focused Actors:

- **Nhatot Scraper** — real estate / property (category `1000`).
- **Xe Chotot Scraper** — vehicles (category `2000`).
- **Vieclamtot Scraper** — job listings (category `13010`).
- **Chotot Phone Enricher** — reveal seller phone numbers from `listId`s (marketplace only).
- **Chotot Ad Detail Scraper** — batch `listId`/`adId` → full detail with labeled `parameters`.

### FAQ, disclaimers, and support

**Is scraping Chotot legal?** This Actor collects only publicly available listing data and does not log in or bypass access controls. You are responsible for using the data in compliance with Chotot's Terms of Service and applicable laws (including personal-data rules). Do not use scraped personal data for spam or unlawful purposes.

**Are phone numbers included?** No. Phone reveal is handled by the separate Chotot Phone Enricher Actor.

**Why do I get few results for property, vehicles, or jobs?** Those categories are served by the companion Actors listed above; this Actor targets the 10 general marketplace categories.

**Known limitations.** Results are returned newest-first, so the Actor returns the most recent ads per category up to your `maxItems`.

**Support.** Found a bug or need a custom field? Open an issue on the Actor's **Issues** tab. Custom scraping solutions are available on request.

# Actor input Schema

## `search` (type: `string`):

Full-text keyword to search for. Combinable with every filter below. Leave empty to scrape whole categories.

## `categoryIds` (type: `array`):

Top-level marketplace categories to scrape. Defaults to all 10 general categories. Property, vehicles and jobs are handled by companion Actors.

## `adType` (type: `string`):

Which kind of ad to return. `all` (the default) returns every type. `sell` is by far the most common single type. Availability varies per category.

## `regionId` (type: `string`):

Limit results to a single province. Leave blank to scrape nationwide.

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

Number of ads to fetch for EACH selected category. Total output is at most this number times the number of categories (e.g. 50 × 10 categories = up to 500 items).

## `enrichDetails` (type: `boolean`):

Add an `attributes` object to every ad with human-readable, category-specific specs (brand, model, capacity, condition, warranty, full address, etc.). Slows the run and increases the cost.

## Actor input object example

```json
{
  "search": "iphone 15",
  "categoryIds": [
    "5000",
    "14000",
    "3000",
    "8000",
    "4000",
    "12000",
    "9000",
    "11000",
    "6000",
    "7000"
  ],
  "adType": "all",
  "maxItems": 50,
  "enrichDetails": false
}
```

# 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 = {
    "categoryIds": [
        "5000",
        "14000",
        "3000",
        "8000",
        "4000",
        "12000",
        "9000",
        "11000",
        "6000",
        "7000"
    ],
    "adType": "all"
};

// Run the Actor and wait for it to finish
const run = await client.actor("hgservices/chotot-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 = {
    "categoryIds": [
        "5000",
        "14000",
        "3000",
        "8000",
        "4000",
        "12000",
        "9000",
        "11000",
        "6000",
        "7000",
    ],
    "adType": "all",
}

# Run the Actor and wait for it to finish
run = client.actor("hgservices/chotot-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "categoryIds": [
    "5000",
    "14000",
    "3000",
    "8000",
    "4000",
    "12000",
    "9000",
    "11000",
    "6000",
    "7000"
  ],
  "adType": "all"
}' |
apify call hgservices/chotot-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=hgservices/chotot-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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