# Carousell Marketplace Listing Search (Hong Kong) (`nimbryxo-studio/carousell-marketplace-listing-search-across-8`) Actor

Search Hong Kong Carousell listings by keyword or category, or fetch listing and seller pages: price, condition, photos, seller feedback, location and deal options. No account, user cookies or API key required.

- **URL**: https://apify.com/nimbryxo-studio/carousell-marketplace-listing-search-across-8.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** E-commerce, Automation, Lead generation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## Carousell Marketplace Listing Search (Hong Kong)

Scrape public Carousell Hong Kong marketplace listings by keyword or category, or fetch individual listing and seller pages. Each record includes the listing title, price, condition, photos, seller, location, category breadcrumbs and deal options. Hong Kong is the only market offered. No account, user cookies, API key or proxy setup is required.

### What this actor does

- Searches Carousell Hong Kong by one or more keywords
- Browses a category; parent-only categories expand to their child pages
- Fetches detail pages for `/p/<id>/` listing URLs or bare listing IDs
- Fetches a seller profile (`/u/<username>/`) and the seller's current listings
- Applies Carousell's server-side sort, condition, price and deal-option filters
- Optionally merges full detail data into search, category or seller results
- Deduplicates records across queries and pages
- Omits fields a listing did not provide

### Output per listing

- `listingId` - Carousell listing ID
- `title` - item title
- `price` - numeric price when Carousell provides one
- `priceText` / `priceFormatted` - displayed price text
- `currency` / `currencySymbol` - `HKD` and `HK$`
- `condition` / `conditionCode` - Carousell's layered condition
- `category`, `categoryId`, `breadcrumbs` - category data when present
- `seller`, `sellerId`, `sellerUrl`, `sellerFeedbackCount`, `sellerRating`, `sellerFollowers`, `sellerJoined`, `sellerVerified` - seller signals (feedback/rating/followers are present when Carousell publishes them)
- `location`, `latitude`, `longitude`, `meetups` - location data when published
- `photos`, `imageUrl`, `imageCount` - public image URLs and count
- `listedAt`, `lastModified`, `bumpedAt` - listing timestamps
- `status`, `statusLabel` - raw Carousell status and a readable label
- `dealOptions`, `shipping`, `meetup` - deal methods
- `likes`, `comments`, `offers` - engagement counters when present
- `sourceUrl`, `sourceQuery`, `mode`, `scrapedAt` - provenance and metadata

When detail enrichment is enabled, description, seller profile fields, richer images, coordinates and deal data are merged into the listing record. A seller with no visible listings can still produce a seller-only record.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | select | `search` | `search`, `category`, `listingDetails` or `seller` |
| `queries` | string list | `["iPhone"]` | Keywords for `search` mode |
| `country` | select | `hong_kong` | Verified market: Hong Kong only |
| `category` | select | - | Top-level category for `category` mode; Hong Kong `mobile-phones` collection ID is `462` |
| `sellerUsernames` | string list | `[]` | Usernames for `seller` mode |
| `listingUrls` | URL list | `[]` | `/p/` URLs or listing IDs for `listingDetails` mode |
| `sortBy` | select | `best_match` | `best_match`, `recent`, `price_low`, `price_high` |
| `condition` | select | `any` | `any`, `brand_new`, `like_new`, `lightly_used`, `well_used`, `heavily_used` |
| `priceMin` | integer | - | Minimum price in HKD |
| `priceMax` | integer | - | Maximum price in HKD |
| `dealOption` | select | `any` | `any`, `mailing`, `meetup` |
| `postedWithinDays` | integer | - | Client-side first-page age filter (1-365) |
| `maxItems` | integer | `20` | Overall record cap (1-500) |
| `includeDetails` | boolean | `false` | Merge detail pages into results |
| `maxDetailItems` | integer | `10` | Detail-request cap in `listingDetails` and enrichment modes (1-50) |

Legacy saved inputs are accepted only for Hong Kong: `query` maps to `queries`, `country`/`countries` must resolve to `hong_kong`, old sort values `relevance`/`price_asc`/`price_desc` map to the new keys, old `condition` values `all`/`new`/`used` map to `any`/`brand_new`/`lightly_used`, and modes `searchByCategory`/`nearbyListings` map to `category`/`search`. Non-Hong Kong market values are rejected with a warning. Legacy `maxPages` is ignored because the rendered page has no reliable server pagination.

#### Example: search Hong Kong listings

```json
{
  "mode": "search",
  "queries": ["iPhone 15", "Nintendo Switch"],
  "country": "hong_kong",
  "sortBy": "recent",
  "condition": "like_new",
  "priceMin": 100,
  "priceMax": 5000,
  "maxItems": 30
}
```

#### Example: browse a category

```json
{
  "mode": "category",
  "category": "mobile-phones",
  "country": "hong_kong",
  "maxItems": 20
}
```

#### Example: fetch listing details

```json
{
  "mode": "listingDetails",
  "listingUrls": [{"url": "https://www.carousell.com.hk/p/1451961900/"}]
}
```

#### Example: seller profile

```json
{
  "mode": "seller",
  "sellerUsernames": ["bdsphone"],
  "country": "hong_kong",
  "maxItems": 20
}
```

### Use cases

- **Marketplace price monitoring** - track asking prices and conditions for a saved list of Hong Kong listings
- **Resale research** - compare phone, electronics, fashion or furniture pricing across sellers
- **Seller intelligence** - collect public seller feedback, follower, join-date and verification signals
- **Listing enrichment** - add current Carousell listing metadata to an existing catalogue
- **Deal research** - discover recent listings, mailing/meet-up options and category trends

### FAQ

**Do I need an account, cookies or an API key?**
No. The actor reads public rendered pages and requires no authentication.

**Why is only Hong Kong supported?**
Indonesia, Taiwan, Singapore, Malaysia, the Philippines, Australia and New Zealand are not offered: they do not return reliable public data from cloud infrastructure. Returning wrong-city data would be worse than clearly limiting the scope.

**Why do image links use a different host?**
The actor returns a publicly reachable copy of each image so links load outside Carousell. Sampled URLs return HTTP 200 image content.

**How many results can I get?**
Carousell renders up to 48 cards for a search or category query and ignores page parameters, so each target page is fetched once. Banner/ad cards with listing ID `0` are discarded. Parent-only categories are expanded to their child pages, and `maxItems` caps the records the actor emits. Seller profiles expose up to 20 listings.

**Does it return sold listings?**
No. Carousell's public search surface does not expose a sold-items filter, and the actor never invents a sold status.

**Are prices always numeric?**
No. Free, Swap, Contact for price and other non-numeric labels are preserved as `priceText`; the actor does not fabricate a numeric price. Conditions include Brand new, Like new, Lightly used, Well used and Heavily used.

**Do I need a proxy?**
No. The actor chooses a working connection automatically. No proxy setup is required.

**Is this affiliated with Carousell?**
No. This is an independent third-party actor using Carousell's public website.

# Actor input Schema

## `mode` (type: `string`):

Search listings, browse one category, fetch listing detail URLs, or pull a seller profile with its listings.

## `queries` (type: `array`):

One or more keywords (mode=search). Each query returns Carousell's first page of up to 48 listings per market.

## `category` (type: `string`):

Top-level category. The actor resolves the correct market-specific collection ID and URL.

## `sellerUsernames` (type: `array`):

Carousell usernames to fetch. Each seller returns profile fields plus the first page of their listings.

## `listingUrls` (type: `array`):

Carousell /p/ listing URLs or bare listing IDs. Bare IDs use Hong Kong. URLs from unsupported markets are skipped.

## `sortBy` (type: `string`):

Server-side sort. Best match is Carousell's default and sends no sort parameter.

## `condition` (type: `string`):

Server-side layered condition filter. Carousell uses codes 3, 4, 7, 5 and 6 for these labels.

## `priceMin` (type: `integer`):

Minimum price in the market's local currency (server-side).

## `priceMax` (type: `integer`):

Maximum price in the market's local currency (server-side).

## `dealOption` (type: `string`):

Server-side mailing/delivery or meet-up filter.

## `postedWithinDays` (type: `integer`):

Client-side filter over the first page. Listings without a visible creation timestamp are excluded when this is set.

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

Overall record cap. Carousell returns at most 48 listings per query, so larger values cannot exceed that first-page limit.

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

Fetch and merge full detail pages for search, category or seller results. Adds one request per listing.

## `maxDetailItems` (type: `integer`):

Cap on detail-page requests when includeDetails is enabled (or in listingDetails mode).

## `country` (type: `string`):

Verified market: hong_kong only. Other Carousell markets are blocked or unreliable from Apify cloud and are not offered.

## Actor input object example

```json
{
  "mode": "search",
  "queries": [
    "iPhone"
  ],
  "sellerUsernames": [],
  "listingUrls": [],
  "sortBy": "best_match",
  "condition": "any",
  "dealOption": "any",
  "maxItems": 3,
  "includeDetails": false,
  "maxDetailItems": 1,
  "country": "hong_kong"
}
```

# Actor output Schema

## `listings` (type: `string`):

Dataset of scraped Carousell listings and seller records.

# 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 = {
    "mode": "search",
    "queries": [
        "iPhone"
    ],
    "sellerUsernames": [],
    "listingUrls": [],
    "sortBy": "best_match",
    "condition": "any",
    "dealOption": "any",
    "maxItems": 3,
    "includeDetails": false,
    "maxDetailItems": 1,
    "country": "hong_kong"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/carousell-marketplace-listing-search-across-8").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 = {
    "mode": "search",
    "queries": ["iPhone"],
    "sellerUsernames": [],
    "listingUrls": [],
    "sortBy": "best_match",
    "condition": "any",
    "dealOption": "any",
    "maxItems": 3,
    "includeDetails": False,
    "maxDetailItems": 1,
    "country": "hong_kong",
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/carousell-marketplace-listing-search-across-8").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 '{
  "mode": "search",
  "queries": [
    "iPhone"
  ],
  "sellerUsernames": [],
  "listingUrls": [],
  "sortBy": "best_match",
  "condition": "any",
  "dealOption": "any",
  "maxItems": 3,
  "includeDetails": false,
  "maxDetailItems": 1,
  "country": "hong_kong"
}' |
apify call nimbryxo-studio/carousell-marketplace-listing-search-across-8 --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/carousell-marketplace-listing-search-across-8"
        }
    }
}
```

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/5XzdMbLcuFLBo5DBV/builds/lDzj3anWIiDl946uE/openapi.json
