# American Girl Product Scraper (`dromb/american-girl-wave1`) Actor

Scrape American Girl product search results, categories, prices, and detailed item data from the public storefront. Supports search, category browsing, filters, sorting, and detailed product information with HTML enrichment.

- **URL**: https://apify.com/dromb/american-girl-wave1.md
- **Developed by:** [Dmitriy Gyrbu](https://apify.com/dromb) (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.40 / 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.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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

## American Girl Product Scraper

Extract American Girl products, prices, availability, variants, images,
categories, and detailed item data from the public US storefront. Use the data
for price monitoring, catalog research, assortment tracking, availability
checks, and ecommerce analysis.

This is an unofficial Actor and is not affiliated with or endorsed by American
Girl.

### Supported operations

| Operation | What it returns | Required input |
|---|---|---|
| `search` | Products matching a keyword | `query` |
| `category` | Products from one collection | `slug` or `url` |
| `item` | One product with variants and optional page enrichment | `slug` |
| `categories` | Public storefront collections | none |
| `search_filters` | Search facets and sort options | optional `query` |
| `probe` | Small upstream availability check | none |

The default run searches for `doll` and requests only 10 results.

### Quick start

#### Search products

```json
{
  "operation": "search",
  "query": "doll",
  "limit": 10,
  "sort": "relevance",
  "proxyMode": "auto"
}
```

#### Browse a collection

```json
{
  "operation": "category",
  "slug": "18-doll-collection",
  "limit": 10,
  "sort": "price_asc"
}
```

#### Retrieve one product

```json
{
  "operation": "item",
  "slug": "felicity-merriman-18-inch-doll-book-accessories-historical-characters-jmv35",
  "details": true
}
```

#### List categories

```json
{
  "operation": "categories",
  "limit": 20
}
```

### Input guide

- `query`: keyword for `search`; optional seed for `search_filters`.
- `slug`: collection slug for `category` or product slug for `item`.
- `url`: full collection URL as an alternative for `category`.
- `page`: result page, starting from 1.
- `limit`: 1–60 results per page. Start with 10.
- `sort`: `relevance`, `new`, `bestsellers`, `price_asc`, `price_desc`,
  `name_asc`, or `name_desc`.
- `category`: optional collection filter for keyword search.
- `brand`: optional brand filter.
- `details`: enrich product records from the storefront page. This is slower;
  leave it disabled for listing runs.
- `include_hidden`: include internal/hidden collections in `categories`.
- `includeRaw`: add the original source payload to the run summary.
- `proxyMode`: `auto`, `direct`, `apify`, or `custom`.

Because the Console displays a union schema, fields unrelated to the selected
operation are ignored.

### Output

Product Dataset items can include:

- identifiers: `id`, `slug`, `barcode`
- catalog fields: `name`, `brand`, `category`, `source_url`
- pricing: `price`, `discount_price`, `currency`, `price_info`
- availability: `in_stock`, `stock_status`, `stock`
- media: `image`, `images`
- content: `short_description`, `description`, `features`
- merchandising: `variants`, `specifications`, `attributes`

Example:

```json
{
  "id": "JMV35",
  "slug": "felicity-merriman-18-inch-doll-book-accessories-historical-characters-jmv35",
  "name": "Felicity Merriman 18-inch Doll, Book & Accessories",
  "price": 135,
  "currency": "USD",
  "in_stock": true,
  "source_url": "https://www.americangirl.com/products/..."
}
```

The default Key-Value Store contains `OUTPUT` with `success`, `status`, totals,
published item count, proxy diagnostics, quota status, and structured errors.
For automation, require both platform `SUCCEEDED` and
`OUTPUT.success === true`.

### Ready-to-run Saved Tasks

The Actor package includes bounded use cases for:

- doll product search
- public category discovery
- 18-inch doll collection browsing
- one detailed product lookup

Each task uses a small result limit so it is suitable as a first test and easy
to adapt.

### Proxy and cost behavior

`auto` uses a direct request first because the Searchspring catalog is normally
available without a proxy. This is the cheapest recommended mode. Select
`apify` only if direct requests are blocked. `custom` uses operator-provided
proxy URLs configured outside the public input.

Keep `details` disabled for bulk search/category runs. Enable it only when the
extra product-page fields justify the additional requests.

### Use with n8n or Make

A practical workflow is:

`American Girl Actor -> wait for run -> check OUTPUT.success -> Dataset ->
Google Sheets, Telegram, inventory system, or BI dashboard`

Start a run with the Apify API:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/s3SSpmv1gH7lsAadK/runs?token=YOUR_APIFY_TOKEN&waitForFinish=120" \
  -H "Content-Type: application/json" \
  -d '{"operation":"search","query":"doll","limit":10}'
```

Read the run summary and Dataset using the IDs returned by the run:

```bash
curl "https://api.apify.com/v2/key-value-stores/STORE_ID/records/OUTPUT?token=YOUR_APIFY_TOKEN"
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?clean=true&format=json&token=YOUR_APIFY_TOKEN"
```

Store the Apify token in your automation platform's credential manager, not in
a public workflow.

### Limits and responsible use

- Searchspring and storefront structures can change without notice.
- `details=true` depends on the product-page HTML and may return only
  Searchspring fields when page enrichment is unavailable.
- Free or trial usage may be limited; inspect `OUTPUT.free_trial_quota`.
- Use reasonable page sizes and request frequency.
- Users are responsible for complying with applicable laws and site terms.

# Actor input Schema

## `operation` (type: `string`):

Select the operation to perform

## `query` (type: `string`):

Search query for products (required for search operation)

## `slug` (type: `string`):

Category or item slug (for category and item operations)

## `url` (type: `string`):

Full category or item URL (alternative to slug)

## `page` (type: `integer`):

Page number (for search and category operations)

## `limit` (type: `integer`):

Number of results per page (max 60). Start small for faster, cheaper runs.

## `sort` (type: `string`):

Sort order for results

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

Collection slug to filter search results by category

## `brand` (type: `string`):

Filter results by brand name

## `details` (type: `boolean`):

Fetch additional details from product pages (slower)

## `include_hidden` (type: `boolean`):

Include hidden/internal categories in categories operation

## `includeRaw` (type: `boolean`):

Include raw API response in output

## `proxyMode` (type: `string`):

How to use proxies

## Actor input object example

```json
{
  "operation": "search",
  "query": "doll",
  "page": 1,
  "limit": 10,
  "sort": "relevance",
  "details": false,
  "include_hidden": false,
  "includeRaw": false,
  "proxyMode": "auto"
}
```

# Actor output Schema

## `results` (type: `string`):

Normalized dataset items returned by the actor.

## `summary` (type: `string`):

Run summary JSON stored under the OUTPUT key.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("dromb/american-girl-wave1").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("dromb/american-girl-wave1").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 '{}' |
apify call dromb/american-girl-wave1 --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dromb/american-girl-wave1"
        }
    }
}

```

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/s3SSpmv1gH7lsAadK/builds/3fR21iGndarRaYAqe/openapi.json