# World Market Product Scraper (`nimbryxo-studio/world-market-product-scraper`) Actor

Get product data from Cost Plus World Market, a US home decor, furniture, and specialty food retailer. Search by keyword or browse by department for price, brand, item number, category, images, availability, and ratings.

- **URL**: https://apify.com/nimbryxo-studio/world-market-product-scraper.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **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

## World Market Product Scraper

Scrape **World Market** (worldmarket.com), the US home decor, furniture, and specialty international food retailer. Search by keyword, browse a department, or look up specific product pages, and get price, brand, item number, category, description, images, availability, and customer rating for every product. No login, cookies, or paid proxy required.

### What this actor does

- **Three modes:** `search` (keyword), `byCategory` (browse a department), `byProductUrls` (direct lookup)
- **17 browsable sections**: departments such as furniture, decor, kitchen, dining, bath, food & drinks and gifts, plus collections like best sellers, new & trending, sale and free shipping
- **Sort options** (search and department modes): bestselling, new arrivals, rating, price low-to-high, price high-to-low
- **Price range filtering** on each product's scraped `price` (its lowest variant price), in every mode
- **Multi-size / multi-color products:** returns the lowest listed price plus the highest (`priceMax`) when a product has several variants
- **Empty fields are omitted** — every record only contains fields that were actually found

### Output per product

- `title` — product name
- `price` — lowest current price across all variants (USD), when the product page shows one
- `priceMax` — highest variant price, only present when a product has multiple sizes/colors at different prices
- `currency` — currency code from the product page (`USD`)
- `brand`
- `itemNumber` — World Market's internal item/SKU number
- `category` — breadcrumb path (e.g. `Furniture > Living Room Furniture > Sectionals`)
- `description`
- `imageUrls[]` — up to 8 product images
- `productUrl`
- `availability` — `In Stock`, `Out of Stock`, `Limited Availability`, `Preorder`, or `Sold Out`; for multi-variant products it is `In Stock` when any variant is
- `variants[]` — per-variant breakdown (color or size, whichever the product varies by), only present when a product has 2+ selectable variants: each entry has `label`, `sku`, `price`, and `availability`
- `rating` — average customer rating (1–5), only present when the product has reviews
- `reviewCount` — only present when the product has reviews
- `recordType: "product"`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` / `byCategory` / `byProductUrls` |
| `searchQuery` | string | `candle` | Free-text keyword (mode=search) |
| `category` | string | – | Department or collection to browse (mode=byCategory; required there) — see list below |
| `productUrls` | array | – | Direct worldmarket.com product-page URLs (mode=byProductUrls); only the first `maxItems` unique URLs are fetched |
| `sortBy` | string | `bestselling` | `bestselling` / `newArrivals` / `ratingHighToLow` / `priceLowToHigh` / `priceHighToLow`; ignored in `byProductUrls` |
| `minPrice` | int | – | Drop products priced below this amount (USD); when set, products without a price are dropped |
| `maxPrice` | int | – | Drop products priced above this amount (USD); when set, products without a price are dropped |
| `maxItems` | int | `20` | Hard cap on emitted products (1–200) |

`category` accepts: `bestSellers`, `bath`, `clothingAndJewelry`, `decorAndPillows`, `dining`, `foodAndDrinks`, `freeShipping`, `furniture`, `gifts`, `holidays`, `kitchen`, `lighting`, `newAndTrending`, `outdoor`, `rugs`, `sale`, `wallDecorAndMirrors`.

#### Example: keyword search

```json
{
  "mode": "search",
  "searchQuery": "dining chair",
  "sortBy": "ratingHighToLow",
  "maxItems": 30
}
```

#### Example: browse a department with a price range

```json
{
  "mode": "byCategory",
  "category": "kitchen",
  "sortBy": "priceLowToHigh",
  "minPrice": 10,
  "maxPrice": 50,
  "maxItems": 50
}
```

#### Example: look up specific products

```json
{
  "mode": "byProductUrls",
  "productUrls": [
    "https://www.worldmarket.com/p/apothecary-lavender-tonic-scented-candle-128547.html"
  ]
}
```

#### Example: browsing food & drinks for gifting

```json
{
  "mode": "byCategory",
  "category": "foodAndDrinks",
  "sortBy": "bestselling",
  "maxItems": 40
}
```

### Use cases

- **Price monitoring** — track World Market prices for competitive intelligence
- **Catalog enrichment** — pull structured product data (brand, category, images) into a PIM
- **Market research** — analyze best-selling home decor and specialty food trends
- **Deal alerts** — combine `sortBy: priceLowToHigh` with `minPrice`/`maxPrice` to spot bargains
- **Affiliate content** — build gift guides and roundups sourced from real, live product data
- **Inventory / availability tracking** — monitor `availability` for specific items over time

### FAQ

**Is this affiliated with World Market / Cost Plus World Market?**
No. This is an independent, third-party actor that reads the same public pages any shopper's browser sees. It is not affiliated with, endorsed by, or connected to World Market.

**Do I need to log in or provide cookies?**
No. World Market publishes full product data (including price) on public pages without requiring an account.

**Why do some products show a `priceMax` and others don't?**
World Market sells many products in multiple sizes or colors at different price points. `price` is always the lowest available price; `priceMax` is only included when a higher-priced variant exists.

**Why don't all products have a `rating` or `reviewCount`?**
Those fields are only included for products that have at least one customer review. Newer or niche items may not have any yet, and the field is omitted rather than showing a fake `0`. Every product's own page is fetched regardless of mode, so ratings are populated in `search` and `byCategory` results too, not just `byProductUrls`. Products whose page can't be loaded are skipped.

**How many products can I scrape in one run?**
Up to 200 per run via `maxItems`. For larger catalogs, run the actor multiple times with different `category` or `searchQuery` values.

**Does `byCategory` cover every sub-category?**
Each of the 17 options opens one fixed "shop all" page, and a few of them are narrower than the name suggests: `bath` is bath & body, `outdoor` is outdoor decor, `wallDecorAndMirrors` is wall art, and `sale` is clearance. For other slices, use `search` with a keyword, or `byProductUrls` for specific items. `searchQuery` is not applied in `byCategory` mode.

**How is `sortBy` applied?**
`bestselling` and `newArrivals` keep World Market's own listing order. For the price and rating sorts, the actor re-sorts the collected products itself (products without a price or rating go last), because the site's own order is only approximate.

**How fresh is the data?**
Every run fetches live pages directly from worldmarket.com — there is no caching, so prices and availability reflect the current listing at run time.

# Actor input Schema

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

What to fetch.

## `searchQuery` (type: `string`):

Free-text keyword search (mode=search), e.g. `candle`, `dining chair`, `chocolate`.

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

Browse an entire World Market department.

## `productUrls` (type: `array`):

Direct worldmarket.com product-page URLs (e.g. `https://www.worldmarket.com/p/<slug>-<id>.html`).

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

Sort order for search/category results.

## `minPrice` (type: `integer`):

Drop products priced below this amount.

## `maxPrice` (type: `integer`):

Drop products priced above this amount.

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

Hard cap on emitted products.

## Actor input object example

```json
{
  "mode": "search",
  "searchQuery": "candle",
  "productUrls": [],
  "sortBy": "bestselling",
  "maxItems": 20
}
```

# Actor output Schema

## `products` (type: `string`):

Dataset containing all scraped World Market products.

# 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",
    "searchQuery": "candle",
    "productUrls": [],
    "sortBy": "bestselling",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/world-market-product-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 = {
    "mode": "search",
    "searchQuery": "candle",
    "productUrls": [],
    "sortBy": "bestselling",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/world-market-product-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 '{
  "mode": "search",
  "searchQuery": "candle",
  "productUrls": [],
  "sortBy": "bestselling",
  "maxItems": 20
}' |
apify call nimbryxo-studio/world-market-product-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/world-market-product-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/rPjoYNtTrSUbx3aor/builds/Pz0nQaJaZzx6HJbtS/openapi.json