# FamilyMart Japan Product Scraper (`mrdoe/family-mart-japan-scraper`) Actor

Extract FamilyMart Japan's full product catalogue rice balls, bento, sandwiches, sweets, hot snacks and drinks. Get name, pre-tax and tax included price, release date, regional availability, description, category and photo for every item. Browse by category/pull specific product details. No login.

- **URL**: https://apify.com/mrdoe/family-mart-japan-scraper.md
- **Developed by:** [MrDoe](https://apify.com/mrdoe) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 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.
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?

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

### What does FamilyMart Japan Product Scraper do?

**FamilyMart Japan Product Scraper extracts [FamilyMart](https://www.family.co.jp)'s product catalogue** - rice balls, bento, sandwiches, bread, sweets, hot snacks, drinks, and more - straight from family.co.jp. For each product you get the name, pre-tax and tax-included price, release date, region-availability note, description, category, and photo. No login, no API key.

Run it on Apify for scheduled runs, a REST API, and integrations with Google Sheets, Make, Zapier and more.

#### Two operations

| Operation | What it does | Key input |
| --- | --- | --- |
| **Browse a category** | Lists every product currently shown in one FamilyMart category (or all of them) | `category` / `categories` |
| **Product details** | Full detail for specific products | `productUrl` / `productUrls` |

### Why use it?

- **New-product tracking** - FamilyMart's line-up changes weekly; the `newgoods` category plus `releaseDate` and the "予告" (upcoming) flag surface what's about to launch.
- **Price monitoring** - both the pre-tax and tax-included "FamilyMart standard price" per product.
- **Regional planning** - the `region` / `notes` fields carry FamilyMart's own availability caveats (e.g. limited to Kyushu, or Kagoshima/Miyazaki only).
- **Menu / competitive research** - a clean nationwide snapshot of a major Japanese convenience-store chain's range.

### Data it extracts

| Field | Description |
| --- | --- |
| `productId` | FamilyMart's numeric product id |
| `name` | Product name (Japanese) |
| `price` | Pre-tax price (JPY) when shown |
| `priceWithTax` | Tax-included FamilyMart standard price (JPY) |
| `currency` | Always `JPY` |
| `description` | Product blurb - details only |
| `releaseDate`, `releaseLabel` | Parsed release date (`YYYY-MM-DD`) + the original Japanese label |
| `badge`, `isUpcoming` | "予告" badge for not-yet-released items |
| `region` / `notes` | FamilyMart's regional-availability caveats |
| `category`, `categoryLabel`, `breadcrumbs` | Category slug + Japanese label + breadcrumb trail |
| `image` | Product photo URL |
| `productUrl` | Canonical family.co.jp detail URL |

### How to use it

1. Pick an **Operation**: *Browse a category* or *Product details*.
2. For browsing, choose a **Category** (or *All categories*, or list several under *Categories - batch*). Optionally add a **Product name filter**.
3. For details, paste one or more product detail **URLs** (or the `category/id` shorthand, e.g. `obento/0616195`). A bare id alone won't work - FamilyMart URLs need the category segment.
4. Set **Max items** to cap a browse run.
5. Click **Start**. Download as JSON, CSV, Excel or HTML, or pull from the API.

### Input

| Field | Type | Description |
| --- | --- | --- |
| `operation` | string | `search` or `productDetails` (required) |
| `category` | string | One category slug or `all` |
| `categories` | array | Several slugs; include `all` to sweep everything |
| `productName` | string | Case-insensitive name filter (search) |
| `productUrl` / `productUrls` | string / array | Detail URL(s) or `category/id` shorthand(s) |
| `maxItems` | integer | Row cap for search (default 20) |
| `proxyConfiguration` | object | Proxy settings (default Apify proxy is enough) |

### Output

Each dataset row is one product. Download in JSON, HTML, CSV or Excel.

```json
{
  "_operation": "productDetails",
  "productId": "0616195",
  "name": "ハンバーグ&フライドチキン弁当（マスタードソース）",
  "price": 610,
  "priceWithTax": 658,
  "currency": "JPY",
  "description": "ハンバーグとフライドチキンを組み合わせた、食べ応えのあるお弁当です。",
  "releaseDate": "2026-09-01",
  "releaseLabel": "2026年9月1日発売予定",
  "badge": null,
  "isUpcoming": false,
  "region": null,
  "category": "obento",
  "categoryLabel": "お弁当",
  "breadcrumbs": ["お弁当", "ハンバーグ&フライドチキン弁当（マスタードソース）"],
  "image": "https://www.family.co.jp/content/dam/family/goods/0616195.jpg",
  "productUrl": "https://www.family.co.jp/goods/obento/0616195.html",
  "status": "success"
}
```

### Known limitations

- **Product catalogue only.** This scrapes family.co.jp's 商品情報 pages - not the FamiPay app, the ファミマオンライン shop, or the Wolt/Uber Eats delivery menus.
- **No nutrition or allergen tables.** FamilyMart does not publish per-product nutrition/allergen data on the product page (it lives in a separate site section), so those fields are not available here.
- **Nationwide info, not per-store.** Regional caveats are in `region` / `notes`; there is no per-store stock signal.
- Prices are the "FamilyMart standard price"; individual stores may differ.
- Product ids rotate as the line-up refreshes - an unknown URL returns a single `status: "error"` row.

### FAQ

**Do I need an account or key?** No.

**Is scraping this legal?** It collects only public product-catalogue data, no personal data. You are responsible for complying with FamilyMart's site terms and applicable law.

**Can it get store locations?** Not this Actor - it's product data only.

# Actor input Schema

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

Which FamilyMart data to scrape. One operation per run.

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

Which product category to list for the search operation. Choose "All categories" to sweep every category in one run.

## `categories` (type: `array`):

Several category slugs in one run (e.g. omusubi, obento, dessert). Wins over "Category" when filled. Include "all" to sweep every category.

## `productName` (type: `string`):

Only return products whose name contains this text (case-insensitive, Japanese or English). Applies to the search operation.

## `productUrl` (type: `string`):

A full family.co.jp product detail URL, or the shorthand "category/id" (e.g. "obento/0616195"). A bare product id alone will not work - FamilyMart detail URLs require the category segment. Used by the productDetails operation. Leave blank to have the Actor pick a current product.

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

Several product detail URLs (or "category/id" shorthands) in one run. Wins over "Product detail URL" when filled.

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

Caps total rows for the search operation (productDetails always returns one row per URL). Default 20.

## `proxyConfiguration` (type: `object`):

FamilyMart's catalogue is public and lightly trafficked; the default Apify proxy is plenty.

## Actor input object example

```json
{
  "operation": "search",
  "category": "newgoods",
  "productName": "",
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

No description

# 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 = {
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("mrdoe/family-mart-japan-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 = { "maxItems": 20 }

# Run the Actor and wait for it to finish
run = client.actor("mrdoe/family-mart-japan-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 '{
  "maxItems": 20
}' |
apify call mrdoe/family-mart-japan-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mrdoe/family-mart-japan-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/pVReM9shgnoWPbmXv/builds/7hwCnREg9r3d8qQlo/openapi.json