# Dollar General Products, Prices & Store Scraper (`dromb/dollar-general-scraper-clean`) Actor

Extract Dollar General product search results, exact item details, prices, inventory and fulfillment signals, categories, filters, and public store-directory data for retail monitoring and product research.

- **URL**: https://apify.com/dromb/dollar-general-scraper-clean.md
- **Developed by:** [Dmitriy Gyrbu](https://apify.com/dromb) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 25 total users, 5 monthly users, 97.8% 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?

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

## Dollar General Product Store Scraper

This unofficial Actor returns Dollar General product listings, product details, filters, top-level categories, store details, and city store-directory results. It is not affiliated with or endorsed by Dollar General.

### Quick start

```json
{
  "operation": "search",
  "query": "milk",
  "store_id": 1,
  "page": 1,
  "limit": 5,
  "sort": "recommended"
}
```

### Operations

| Operation | Purpose | Key inputs |
| --- | --- | --- |
| `probe` | One-item connectivity/product check | `store_id` |
| `categories` | Top-level `/c/...` links from the storefront | none |
| `store` | Exact public store-directory detail | `store_id` |
| `stores` | City directory or exact numeric lookup | `query` as `City, ST` or a store number; `limit` |
| `search_filters` | Search or category filters and public sort options | `query`, or a category identifier; `store_id` |
| `search` | Store-aware keyword product search | `query`, `store_id`, `page`, `limit`, `sort` |
| `category` | Store-aware category products | `category_id`, `category_url`, or `category_slug`; `store_id`, `page`, `limit`, `sort` |
| `item` | Store-aware product detail | `upc` or `item_url`; `store_id` |

The defaults are `operation=search`, `query=milk`, `store_id=1`, `page=1`, `limit=5`, `sort=recommended`, and `include_reviews=false`. `page` is 1-based. `limit` accepts 1–100. Sort values are `recommended`, `price_asc`, `price_desc`, and `highest_rated`.

When a category URL or slug is supplied without an ID, the Actor opens that category page and uses the ID sent by the live frontend. It does not derive or guess an ID from the slug. Item review compatibility fields may be empty because reviews are not provided by the product-detail response.

### Access and reliability

The current storefront requires a US Residential Chromium session. The Actor creates a fresh bounded proxy session for each bootstrap attempt and tries no more than five times because an individual Residential exit can still be blocked or fail to tunnel. Success on the first attempt is not guaranteed. Guest authorization is captured only from the live frontend, held in memory for the run, and never included in datasets, `OUTPUT`, or logs.

The runtime uses the official Python 3.11 Playwright Chrome Actor image; it does not download a browser at runtime. Product calls use the current `dggo.dollargeneral.com` provider endpoints. Store and category-directory operations parse public `www.dollargeneral.com` pages in the same browser session.

Exact store `1` is the known public Ada, Oklahoma directory page. Other numeric store IDs are resolved by a bounded scan of public directory links. If the exact location cannot be found within that scan, the Actor returns a fail-honest error rather than fabricated store data.

### Output

Successful records are pushed individually to the default Dataset with their existing public field names and added `operation` and `record_type` context. A legitimate zero-match search leaves the Dataset empty.

Every run writes a JSON summary to the default key-value store under `OUTPUT`:

```json
{
  "source": "dollargeneral_us",
  "operation": "search",
  "status": "success",
  "success": true,
  "total": 0,
  "errors": []
}
```

Expected failures are described only in `OUTPUT`; fake error records are never pushed to the Dataset.

### Limitations

Prices, inventory, and fulfillment flags are store-aware and can change. Public page markup and frontend provider schemas can change. Proxy rotation reduces transient blocking but cannot eliminate it. Store-number discovery is deliberately bounded, so a valid store may fail honestly if its directory path is not encountered.

# Actor input Schema

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

The operation to perform.

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

Product search keyword for search/search_filters, or a store lookup query such as 'Ada, OK' for stores.

## `store_id` (type: `integer`):

Dollar General store number used for product pricing, inventory, store details, and item detail.

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

1-based page number.

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

Maximum product, store, or filter rows to retrieve.

## `category_id` (type: `string`):

Dollar General category ID for category browsing or category-based filters. Example 639 is Food & Beverage > Beverages.

## `category_url` (type: `string`):

Full Dollar General category URL for category browsing or category-based filters.

## `category_slug` (type: `string`):

Relative Dollar General category path.

## `upc` (type: `string`):

Product UPC for item operation. Derive a current UPC from search or category results when possible.

## `item_url` (type: `string`):

Full Dollar General product URL. A UPC in the URL is used for item operation.

## `include_reviews` (type: `boolean`):

When true, expose reviews/reviews_returned compatibility fields on item output. The current Dollar General product-detail response may not provide review rows, so the list can be empty.

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

recommended, price_asc, price_desc, highest_rated

## Actor input object example

```json
{
  "operation": "search",
  "query": "milk",
  "store_id": 1,
  "page": 1,
  "limit": 5,
  "include_reviews": false,
  "sort": "recommended"
}
```

# Actor output Schema

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

Dataset items returned by the selected operation.

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

Run summary JSON stored under the OUTPUT key when available.

# 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/dollar-general-scraper-clean").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/dollar-general-scraper-clean").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/dollar-general-scraper-clean --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dromb/dollar-general-scraper-clean"
        }
    }
}
```

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/DKzAsP9SNVgU3nf5p/builds/EZokT284O6WuA14Kl/openapi.json