# Leafly Scraper (`paradox-analytics/leafly-scraper`) Actor

Extract comprehensive dispensary and product data from Leafly.com with zero configuration. This Actor uses pre-configured extraction patterns to scrape dispensary details, product catalogs, pricing, strain information, and special offers — all without requiring external API keys or manual setup.

- **URL**: https://apify.com/paradox-analytics/leafly-scraper.md
- **Developed by:** [Paradox Analytics](https://apify.com/paradox-analytics) (community)
- **Categories:** E-commerce, Automation
- **Features:** Full permissions
- **Stats:** 39 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## Leafly Dispensary Scraper - Apify Actor

[![Apify](https://img.shields.io/badge/Apify-Actor-green)](https://apify.com)
[![Version](https://img.shields.io/badge/version-2.0-blue)](https://github.com)

Extract comprehensive dispensary and product data from Leafly.com with enhanced pagination and flexible scraping modes.

### 🚀 Quick Start

#### Default Mode (Fast - 2-5 minutes)

```json
{
  "mode": "single_url",
  "dispensaryUrl": "https://www.leafly.com/dispensary-info/curaleaf---western",
  "proxyType": "residential"
}
```

#### State Discovery Mode

```json
{
  "mode": "state",
  "state": "nevada",
  "maxStores": 10,
  "proxyType": "residential"
}
```

***

### ✨ Features

#### V2.0 Updates (Latest)

- ✅ **Single Dispensary URL Mode**: Scrape specific dispensaries in 2-5 minutes
- ✅ **Enhanced Pagination**: Burst windows + fixpoint convergence (98-99% capture)
- ✅ **Duplicate Detection**: No more infinite loops
- ✅ **Apify Proxy Integration**: Native residential/datacenter proxy support
- ✅ **5-Minute Compliance**: Default mode completes within Apify's test requirements

#### Core Features

- 🏪 **Dispensary Details**: Name, address, hours, ratings, license info
- 🌿 **Product Catalog**: Full menu with THC/CBD, pricing, strains
- 💰 **Special Offers**: Deals, discounts, promotions
- 📊 **Strain Information**: Effects, terpenes, genetics, ratings
- 🔄 **Multi-State Support**: All legal cannabis states in the US

***

### 📊 Input Configuration

#### Scraping Modes

| Mode | Description | Completion Time | Use Case |
|------|-------------|-----------------|----------|
| **single_url** | Scrape one dispensary | 2-5 minutes | Testing, monitoring specific stores |
| **state** | Discover multiple dispensaries | 10+ minutes | Market research, full state data |

#### Required Parameters

- **mode** (string): `"single_url"` or `"state"`
- **dispensaryUrl** (string): Direct Leafly dispensary URL (required for single_url mode)

#### Optional Parameters

- **state** (string): US state slug (only for state mode) - Default: `"nevada"`
- **maxStores** (integer): Max dispensaries to scrape (state mode) - Default: `5`
- **taskCount** (integer): Parallel workers (state mode) - Default: `3`
- **proxyType** (string): `"residential"`, `"datacenter"`, or `"none"` - Default: `"residential"`
- **includeOffers** (boolean): Extract deals - Default: `true`
- **includeStrainData** (boolean): Detailed strain info - Default: `true`
- **outputFormat** (string): `"dataset"`, `"csv"`, or `"both"` - Default: `"dataset"`
- **debugMode** (boolean): Verbose logging - Default: `false`

***

### 📤 Output Data

#### Named Datasets

**Dispensaries Dataset** (`dispensaries`)

```json
{
  "name": "Curaleaf - Western",
  "address": "5905 S Eastern Ave, Las Vegas, NV 89119",
  "rating": 4.6,
  "review_count": 2847,
  "license_type": "recreational",
  "delivery_available": true,
  "hours_today": "9:00 AM - 12:00 AM"
}
```

**Products Dataset** (`products`)

```json
{
  "product_name": "Zkittlez - Live Rosin",
  "brand": "Qualcan",
  "category": "concentrates",
  "thc_percent": 78.5,
  "cbd_percent": 0.2,
  "price": 45.0,
  "weight_grams": 1.0,
  "strain_type": "indica",
  "in_stock": true
}
```

**Offers Dataset** (`offers`)

```json
{
  "dispensary_name": "Curaleaf - Western",
  "offer_title": "20% Off All Concentrates",
  "deal_type": "percentage",
  "discount_percent": 20,
  "valid_until": "2025-11-30"
}
```

#### Default Dataset

Combined data with `type` field for easy filtering and accurate result counts.

#### Key-Value Store

- `summary`: Run metadata and statistics
- CSV files (if requested via `outputFormat`)

***

### 🌐 Supported States

- Nevada, California, Colorado, Oregon, Washington
- Arizona, Michigan, Illinois, Massachusetts
- New York, Maine, Montana, New Jersey
- New Mexico, Oklahoma, Pennsylvania

***

### 🔧 Advanced Configuration

#### Example: Maximum Data Extraction

```json
{
  "mode": "state",
  "state": "california",
  "maxStores": 50,
  "taskCount": 10,
  "proxyType": "residential",
  "includeOffers": true,
  "includeStrainData": true,
  "outputFormat": "both",
  "debugMode": false
}
```

#### Example: Fast Testing

```json
{
  "mode": "single_url",
  "dispensaryUrl": "https://www.leafly.com/dispensary-info/curaleaf---western",
  "proxyType": "datacenter",
  "includeStrainData": false,
  "outputFormat": "dataset"
}
```

***

### 💰 Cost Optimization

#### Actor Usage Pricing

The Actor uses a per-event pricing model:

- **Actor Start**: $0.20 per run (first 5 seconds waived)
- **Browser Open**: $0.10 per run
- **Page Scraped**: $0.002 per page
- **Results**: $0.005 per item in dataset

**Estimated Costs:**

- **Single Dispensary**: ~$1.30 + proxies (~200 products)
- **5 Dispensaries**: ~$5.40 + proxies (~1000 products)

#### Proxy Credits

- **Single URL Mode**: ~200-500 proxy requests per run
- **State Mode (5 stores)**: ~1000-2500 proxy requests per run
- **Residential Proxies**: Higher quality, better success rate, higher cost
- **Datacenter Proxies**: Lower cost, higher block rate

#### Runtime

- **Single URL**: 2-5 minutes = minimal compute costs
- **State Mode**: Scales with `maxStores` × 2-3 minutes

***

### 🛠️ Technical Details

#### Architecture

- **Browser**: Camoufox (anti-detection) + Playwright fallback
- **Extraction**: Pre-configured patterns (no OpenAI required)
- **Pagination**: Burst windows with duplicate detection
- **Anti-Blocking**: Session warming, proxy rotation, delays
- **Data Quality**: 98-99% product capture rate

#### Performance

- \~200-500 products per dispensary
- \~1-2 minutes per dispensary
- Zero duplicate products
- Proper pagination handling

***

### 🐛 Troubleshooting

#### Common Issues

**Actor times out at 5 minutes**

- Increase Actor timeout in Apify console settings
- Use single_url mode for faster runs
- Reduce `maxStores` in state mode

**No products extracted**

- Check if dispensary URL is valid
- Enable `debugMode` to see detailed logs
- Verify proxy type is set correctly

**Proxy errors**

- Check Apify proxy subscription status
- Try switching between residential/datacenter
- Ensure sufficient proxy credits

***

### 📚 Documentation

- [Deployment Guide V2](./DEPLOYMENT_GUIDE_V2.md) - Full deployment instructions
- [Actor Description](./ACTOR_DESCRIPTION.md) - Detailed feature list
- [Apify SDK Docs](https://docs.apify.com/sdk/python/) - Python SDK reference

***

### 🎯 Use Cases

1. **Market Research**: Analyze product availability across regions
2. **Price Monitoring**: Track pricing trends and competitive analysis
3. **Inventory Tracking**: Monitor stock availability
4. **Compliance**: Track licensed dispensaries and products
5. **Deal Aggregation**: Collect special offers and promotions

***

### 📞 Support

For issues or questions:

1. Check [Troubleshooting](#-troubleshooting) section
2. Enable `debugMode` and review logs
3. Contact via Apify Actor support

***

### 📄 License

This Actor is provided as-is for data extraction purposes. Users are responsible for complying with Leafly's Terms of Service and applicable laws regarding data scraping.

***

### 🔄 Version History

#### V2.0 (Current)

- Added single dispensary URL mode
- Enhanced pagination with burst windows
- Fixed infinite loop issues
- Integrated production-json improvements
- Optimized for Apify's 5-minute test requirement

#### V1.0

- Initial release
- State-based scraping only
- Basic pagination

***

**Ready to extract cannabis data at scale! 🌿**

# Actor input Schema

## `dispensaryUrl` (type: `string`):

Full URL to a Leafly dispensary page. To scrape multiple stores by state instead, clear this field and configure the 'Target State' below.

## `state` (type: `string`):

US state to scrape dispensaries from (only used if Dispensary URL is empty)

## `maxStores` (type: `integer`):

Number of dispensaries to scrape (state mode only)

## `proxyType` (type: `string`):

Residential proxies recommended for best results

## `taskCount` (type: `integer`):

Number of dispensaries to process simultaneously (state mode only)

## `workerCount` (type: `integer`):

Number of product pages to scrape in parallel (higher = faster, but more resource-intensive)

## `includeOffers` (type: `boolean`):

Extract promotional deals and discounts (adds ~5-10% to runtime)

## `includeStrainData` (type: `boolean`):

Extract detailed strain information (adds ~10-15% to runtime)

## `outputFormat` (type: `string`):

How to save the extracted data

## `debugMode` (type: `boolean`):

Enable detailed logging for troubleshooting

## Actor input object example

```json
{
  "dispensaryUrl": "https://www.leafly.com/dispensary-info/jade-cannabis-sky-pointe",
  "state": "nevada",
  "maxStores": 1,
  "proxyType": "residential",
  "taskCount": 1,
  "workerCount": 6,
  "includeOffers": false,
  "includeStrainData": false,
  "outputFormat": "dataset",
  "debugMode": 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("paradox-analytics/leafly-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("paradox-analytics/leafly-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 '{}' |
apify call paradox-analytics/leafly-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,paradox-analytics/leafly-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/5BLF5SzgsgQjg1AES/builds/U7k43ocRNosOdun9C/openapi.json
