# MasGusto Grocery Scraper (`nanaslabs/masgusto-scraper`) Actor

Unofficial MasGusto scraper for ZIP-specific prices, availability, discounts, images, and optional product details. Not affiliated with MasGusto.

- **URL**: https://apify.com/nanaslabs/masgusto-scraper.md
- **Developed by:** [Nanas Labs](https://apify.com/nanaslabs) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.50 / 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

## MasGusto Grocery Scraper

### Overview

Scrape ZIP-specific grocery product data from [MasGusto](https://www.masgusto.com/), including prices, availability, promotions, images, and optional product details. The Actor supports direct category and product URLs in English, Spanish, and Portuguese.

MasGusto inventory and pricing vary by delivery area. Before extracting data, the Actor applies the requested five-digit US ZIP code and verifies that the same ZIP appears in the site header. If the ZIP cannot be confirmed, the run stops instead of returning data for the wrong location.

> **Unofficial notice:** This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by MasGusto. All product names and trademarks belong to their respective owners.

### Features

- Scrape MasGusto category pages or direct product URLs
- Collect ZIP-specific prices, promotions, and availability
- Optionally visit product pages for brand, origin, allergens, descriptions, images, review aggregates, and delivery information
- Support MasGusto's English (`en`), Spanish (`es`), and Portuguese (`pt`) locales
- Remove duplicate products across multiple start URLs
- Control output volume and crawl requests with configurable limits
- Export results in JSON, CSV, Excel, XML, and other formats supported by Apify
- Use the Actor through Apify Console, API, Python, or JavaScript integrations

### Use Cases

- **Monitor** — Monitor grocery prices, discounts, and availability for a specific delivery ZIP code
- **Compare** — Compare regional product pricing and inventory over time
- **Aggregate** — Build structured grocery product catalogs for analysis or enrichment
- **Track** — Track new products, promotions, and sold-out items
- **Research** — Analyze brands, product origins, SNAP eligibility, labels, and category coverage

### Supported URLs

The Actor accepts MasGusto category and product URLs under the following locales:

- `https://www.masgusto.com/en/category/...`
- `https://www.masgusto.com/es/category/...`
- `https://www.masgusto.com/pt/category/...`
- `https://www.masgusto.com/en/product/...`
- `https://www.masgusto.com/es/product/...`
- `https://www.masgusto.com/pt/product/...`

Search, login, account, cart, favorites, and other URL types are not supported. The crawler respects `robots.txt`, and search-result pages are intentionally outside its scope.

### Input Parameters

| Parameter | Type | Description | Default |
| --- | --- | --- | --- |
| `startUrls` | array (required) | MasGusto category or product URLs to scrape. | New-products category |
| `zipCode` | string (required) | Five-digit US ZIP code used for regional pricing, availability, and delivery information. | — |
| `maxItems` | integer | Maximum number of unique products to store across the entire run. Use `0` for unlimited. | `10` |
| `maxRequestsPerCrawl` | integer | Maximum number of category and product page requests processed during the run. | `20` |
| `scrapeProductDetails` | boolean | Visit individual product pages for additional details. This is slower and uses more resources. | `false` |

#### Input Example

```json
{
  "startUrls": [
    {
      "url": "https://www.masgusto.com/en/category/new?filter_sub_category=new"
    }
  ],
  "zipCode": "94102",
  "maxItems": 10,
  "maxRequestsPerCrawl": 20,
  "scrapeProductDetails": false
}
```

### Output Example

Each result represents one unique MasGusto product. Prices are returned as JSON numbers in USD, and product URLs are stored as canonical URLs without tracking query parameters.

```json
{
  "productId": "54692",
  "name": "Fresh Young Jicama",
  "productUrl": "https://www.masgusto.com/en/product/Fresh-Young-Jicama/54692",
  "sourceUrl": "https://www.masgusto.com/en/category/new?filter_sub_category=new",
  "locale": "en",
  "zipCode": "94102",
  "scrapedAt": "2026-08-06T18:00:00.000Z",
  "currency": "USD",
  "price": 9.99,
  "basePrice": null,
  "unitPrice": null,
  "discountPercent": null,
  "availability": "available",
  "soldCountText": null,
  "minOrderQuantity": null,
  "maxOrderQuantity": null,
  "imageUrl": "https://example.com/product.jpg",
  "categoryId": null,
  "parentCategoryId": null,
  "labels": [],
  "tags": [],
  "snapEligible": false,
  "detailStatus": "not_requested"
}
```

Prices and availability in this example are illustrative and may change by ZIP code and crawl time.

When `scrapeProductDetails` is enabled, successful results can additionally include:

- `subtitle`
- `brand`
- `origin`
- `unitQuantity`
- `allergens`
- `descriptionText`
- `imageUrls`
- `reviewCount`
- `reviewHighlights`
- `deliveryMessage`

The `detailStatus` field is one of:

- `not_requested` — Product detail scraping was disabled
- `ok` — Product details were collected and merged successfully
- `failed` — Basic product data was preserved after a detail-page failure or request-limit stop

Only aggregate review counts and highlights provided by the website are collected. Individual reviewer names and review bodies are not collected.

### Pricing

This Actor uses pay-per-event pricing:

- **$0.0035 per result**
- **$3.50 per 1,000 results**
- **$0.05 per GB of allocated memory when the Actor starts**
- The Actor is limited to 4 GB, so the start charge is at most **$0.20 per run**

Platform usage is included in the event prices, and there is no monthly Actor fee. You can set a maximum charge for each run in Apify Console or through the API. Always check the Actor's **Pricing** tab for the current price before running it.

### How to Run

#### Apify Console

1. Open the MasGusto Grocery Scraper Actor page.
2. Add one or more supported category or product URLs.
3. Enter the five-digit US ZIP code you want to verify.
4. Set the result and request limits.
5. Enable product details only when you need the additional fields.
6. Click **Start** and wait for the run to finish.
7. Open the **Results** tab and download the dataset in your preferred format.

#### API

Replace `YOUR_USERNAME` and `YOUR_API_TOKEN` with your Apify username and API token.

```bash
curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~masgusto-scraper/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startUrls": [
      {
        "url": "https://www.masgusto.com/en/category/new?filter_sub_category=new"
      }
    ],
    "zipCode": "94102",
    "maxItems": 10,
    "maxRequestsPerCrawl": 20,
    "scrapeProductDetails": false
  }'
```

#### Python SDK

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("YOUR_USERNAME/masgusto-scraper").call(
    run_input={
        "startUrls": [
            {
                "url": "https://www.masgusto.com/en/category/new?filter_sub_category=new"
            }
        ],
        "zipCode": "94102",
        "maxItems": 10,
        "maxRequestsPerCrawl": 20,
        "scrapeProductDetails": False,
    }
)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

### Integration

Connect MasGusto Grocery Scraper with your existing tools and workflows:

- **API access** — Run the Actor and retrieve datasets through the Apify API
- **Webhooks** — Get notified when a run succeeds or fails
- **Scheduling** — Monitor prices and availability on a recurring schedule
- **Zapier / Make** — Send results to spreadsheets, databases, and other applications
- **Python / JavaScript SDKs** — Integrate the Actor into your own applications
- **Dataset exports** — Download results as JSON, CSV, Excel, XML, RSS, or JSONL

### Data Accuracy and Limitations

- Prices, inventory, promotions, delivery messages, and catalogs vary by ZIP code and crawl time.
- MasGusto may change its page structure or data fields without notice, which can temporarily affect extraction.
- The Actor uses one persistent browser session with concurrency set to `1` to preserve ZIP-specific cookies.
- A ZIP code that cannot be applied and confirmed causes the run to fail before regional product data is stored.
- Multiple start URLs share one global product-ID deduplication set and one global `maxItems` limit.
- Login, CAPTCHA bypass, proxy circumvention, search crawling, and cart or favorites modification are outside the Actor's scope.

Always verify critical pricing and inventory decisions against the source website.

# Actor input Schema

## `startUrls` (type: `array`):

MasGusto category or product URLs. Search, account, cart, and other paths are not supported.

## `zipCode` (type: `string`):

Required 5-digit US ZIP code used for regional inventory, delivery, and pricing.

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

Maximum number of unique products to store across the entire run. Use 0 for unlimited.

## `maxRequestsPerCrawl` (type: `integer`):

Maximum number of category and product page requests processed during the run.

## `scrapeProductDetails` (type: `boolean`):

Visit product pages to add brand, origin, allergens, description, images, review summary, and delivery information.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.masgusto.com/en/category/new?filter_sub_category=new"
    }
  ],
  "zipCode": "07302",
  "maxItems": 10,
  "maxRequestsPerCrawl": 20,
  "scrapeProductDetails": false
}
```

# Actor output Schema

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

ZIP-specific product prices, availability, and optional detail fields.

# 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 = {
    "zipCode": "07302"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nanaslabs/masgusto-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 = { "zipCode": "07302" }

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nanaslabs/masgusto-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/0AC2aQxInGAsAyMmL/builds/47UNK2NxGsRWXzB7m/openapi.json