# Hot Pepper Gourmet Scraper - Restaurants, Bars & Reviews (`abotapi/hotpepper-jp-scraper`) Actor

Scrape Hot Pepper Gourmet (hotpepper.jp) restaurants and bars across Japan by prefecture, area, genre or URL. Extract names, addresses, phone numbers, GPS, ratings, reviews, budgets, opening hours, seating, facilities, coupons and reservation links.

- **URL**: https://apify.com/abotapi/hotpepper-jp-scraper.md
- **Developed by:** [Abot API](https://apify.com/abotapi) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.60 / 1,000 restaurant 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?

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

## Hot Pepper Gourmet Restaurant Scraper: Ratings, Coupons, Hours

Hot Pepper Gourmet Restaurant Scraper turns Japan's largest restaurant reservation directory, Hot Pepper Gourmet (hotpepper.jp), into structured data. Search restaurants and bars by prefecture, area and genre, or paste restaurant and list links. Every restaurant comes back with address, phone, coordinates, rating, review count, budget, opening hours, closing days, payment methods, seats and facilities, policies, coupon and reservation link. Optionally, every restaurant also carries more of its customer reviews, newest first. Export to JSON, CSV or Excel, or read the results through the API.

### Why This Scraper?

- **Search the way you think.** Type a prefecture such as 東京 or Tokyo, a code such as SA11, or Prefecture/Area such as 東京/新宿, then narrow by genre.
- **Paste links instead.** Prefecture and area lists, genre lists, page-2 lists, online-reservation lists, ranking pages and restaurant pages all work.
- **Rich records.** Around 80 fields per restaurant, including coordinates, nearest station, seats, private rooms, smoking policy, payments and cancellation policy.
- **Customer reviews, nested.** Every detailed row carries the latest reviews; switch on extra reviews and the row carries a longer `reviews` list, paginated for you.
- **Coupons and reservation links.** The featured coupon and the online reservation address of every restaurant.
- **Ranking and reservation filters.** Pull the popularity ranking of a place, or keep only restaurants that take online reservations.
- **Recurring monitoring and cost control.** Incremental mode returns only new or changed restaurants (unchanged ones are not billed), Max items is the one cap, and a detail switch gives lighter summary-only runs.

### Use Cases

- **Market researchers:** map restaurant density, genres, budgets and ratings across Japanese prefectures and neighbourhoods.
- **Food and travel platforms:** build and refresh restaurant directories with coordinates, hours and phone numbers.
- **Sales and supplier teams:** build lead lists of restaurants and bars by station area with address and phone.
- **Franchise and location planners:** compare nearby competitors using ratings, budgets and seat counts.
- **Review analysts:** follow review counts and scores per restaurant on scheduled runs.

### Data You Get

> Sample shape: values are illustrative placeholders, not from a live record.

| Field | Example |
| --- | --- |
| `shopId` | J000000000 |
| `name`, `displayName` | Example Izakaya Shinjuku, Example Izakaya |
| `url` | https://www.hotpepper.jp/strJ000000000/ |
| `genre`, `genreCode` | 居酒屋, G001 |
| `area`, `subArea`, `nearestStation` | 新宿, 新宿西口, 新宿駅 |
| `rating`, `reviewCount` | 4.3, 100 |
| `dinnerBudget`, `lunchBudget`, `budgetDetail` | 3001～4000円, 501～1000円, 3500円(通常平均) |
| `address`, `phone` | 東京都新宿区1-1-1, +81-00-0000-0000 |
| `latitude`, `longitude` | 35.69, 139.7 |
| `hours`, `closedDays` | 月～日: 17:00～23:00, なし |
| `access`, `accessFull` | Walking directions from the nearest stations |
| `couponTitle`, `couponUrl` | Example coupon, link to the coupon page |
| `creditCards`, `qrPayments`, `cardAccepted` | Accepted cards and payment apps |
| `totalSeats`, `maxBanquetCapacity` | 50席, 40人 (with `totalSeatsNumber` and `maxBanquetCapacityNumber`) |
| `privateRoom`, `tatami`, `horigotatsu`, `counterSeats`, `sofa`, `terrace`, `charterAvailable` | Seating facilities, each with the restaurant's own note |
| `smokingPolicy`, `wifi`, `barrierFree`, `parking` | 全席禁煙, あり, なし, なし |
| `allYouCanDrink`, `allYouCanEat`, `alcohol` | Drink and food plans, alcohol selection |
| `childPolicy`, `weddingParty`, `remarks`, `cancellationPolicy` | Policies and notes |
| `reservationUrl`, `servesCuisine` | Online reservation address, cuisine |
| `tags`, `catchphrase`, `badges`, `photo` | List-page tags, catch copy, point labels, main photo |
| `reviews` | Latest reviews: date, rating, text, visit details |
| `isPromoted`, `rank`, `page`, `position`, `listUrl`, `totalResults` | Where the restaurant sat in the list |
| `scrapedAt` | 2026-01-01T00:00:00Z |

Fields the restaurant did not publish, such as `openedOn`, are returned empty rather than guessed.

### How to Use

1. Pick a **mode**: `search` (locations and genres) or `url` (paste links).
2. Fill in the fields for that mode, and choose whether to open every restaurant page for full detail.
3. Set **Max items** to control run size and cost, then click **Start**.
4. Download the dataset as JSON, CSV or Excel, or read it through the API.

**Izakaya in Tokyo:**

```json
{
  "mode": "search",
  "locations": ["東京"],
  "genres": ["G001"],
  "maxItems": 20
}
```

**Ranking of ramen restaurants in Shinjuku, summary only:**

```json
{
  "mode": "search",
  "locations": ["東京/新宿"],
  "genres": ["G013"],
  "sortBy": "ranking",
  "fetchDetails": false,
  "maxItems": 20
}
```

**One restaurant page and an area list:**

```json
{
  "mode": "url",
  "urls": [
    "https://www.hotpepper.jp/strJ000000000/",
    "https://www.hotpepper.jp/SA11/Y055/G001/"
  ],
  "maxItems": 30
}
```

#### Run it from your code

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("abotapi/hotpepper-jp-scraper").call(run_input={"mode": "search", "locations": ["東京"], "genres": ["G001"], "maxItems": 20})
for shop in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(shop["name"], shop["rating"], shop["reviewCount"])
```

JavaScript:

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: '<YOUR_APIFY_TOKEN>' });
const run = await client.actor('abotapi/hotpepper-jp-scraper').call({ mode: 'search', locations: ['東京'], genres: ['G001'], maxItems: 20 });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

Or connect it to Make, Zapier, n8n, Google Sheets or webhooks from the **Integrations** tab.

#### Locations and genres

A location is a prefecture name (東京, 東京都 or Tokyo), a prefecture code such as SA11, a code with an area such as SA11/Y055 or SA11/Y005/X020, or Prefecture/Area names such as 東京/新宿. Pick one or more **Genres** to narrow the list; leave them empty and each genre is walked in turn, so keep Max items in mind for large prefectures. A name that matches nothing is reported in the log, and the run stops with a clear message if none of your locations matched.

#### Links you can paste

In URL mode these all work: a prefecture or area page, a genre list in a prefecture, middle area or small area (also its page-2 form), an online-reservation list, a ranking page, and a restaurant page or its map, reviews and menu pages. Keyword search pages and everything else are skipped with a warning instead of producing wrong rows. A ranking page is a single page of about 20 restaurants.

#### Customer reviews

Every detailed row carries the latest few reviews shown on the restaurant page. Turn on **Add more customer reviews to each restaurant** (`includeReviews`) to replace them with a longer list, newest first. It needs **Fetch restaurant detail pages** switched on. **Max reviews per restaurant** (`maxReviewsPerShop`, default 20, at most 300) limits how many reviews each restaurant carries; the site shows 5 reviews per page and the actor follows its pages until your limit or the last page.

Each review carries `date` (the visit or posting day, YYYY-MM-DD), `rating` (1 to 5), `text` (the review as written, empty when the customer left only a score), `visit` (meal and scene details), `photos` and `reviewId`. Reviewer names and profiles are left out on purpose. Review text is published as written, so it can contain whatever the writer chose to put in it.

#### Resume and recurring updates

Use **Resume from run ID** to continue an interrupted run without paying twice for the same restaurants. For scheduled monitoring turn on **Incremental changes for scheduled runs**: the first run returns every matching restaurant as NEW, later runs return only NEW, UPDATED and REAPPEARED restaurants and each row carries `changeType`, `changedFields`, `firstSeenAt` and `lastSeenAt`. A restaurant turns UPDATED when any returned detail changes, including rating and review count. List position fields (`isPromoted`, `rank`, `page`, `position`, `listUrl`, `totalResults`), `scrapedAt` and the nested reviews are never compared, so a new review alone does not make a restaurant UPDATED; it still does when the review count or rating changes. Add any field you consider noise to **Ignore fields when detecting changes**.

### Send results into your apps (MCP connectors)

Optionally pipe the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. This is an extra delivery step **after** the scrape: the Apify dataset is never changed.

**What gets written to the connector:** a condensed, human-readable **summary** of each record, not the full JSON. Each item becomes one entry with a **title** and its key fields flattened to plain text. The **complete record always stays in the Apify dataset**.

1. Authorize a connector once under **Apify → Settings → Integrations** (Notion, Linear, Airtable, or Apify).
2. Select it in the **"Pipe results into your apps"** input field. (If the picker is empty, you haven't authorized a connector yet.)
3. For **Notion**, also set `notionParentPageUrl` to the page where items should be created.

The connection is mediated by Apify's MCP proxy, so this actor never sees your third-party credentials. Leave the field empty to skip.

### Input Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | string | `search` | Search builds restaurant lists from locations and genres. URL mode takes restaurant pages or area list pages you paste. Fields in the other mode's section are ignored. |
| `locations` | array | `["東京"]` | Prefecture names such as 東京 or Tokyo, prefecture codes such as SA11, a code with an area such as SA11/Y055 or SA11/Y005/X020, or Prefecture/Area names such as 東京/新宿. One list is walked per entry. |
| `genres` | array |  | Keep only these genres. Leave empty to walk every genre in turn. |
| `netReservationOnly` | boolean | `False` | Only restaurants that take online reservations. |
| `sortBy` | string | `default` | Default is the site's own list order. Ranking returns the popularity ranking of each location and genre, which is a single page of about 20 restaurants; online reservation filter and Max list pages do not apply to it. |
| `minRating` | number |  | Skip restaurants whose average review score is below this value (0 to 5). Setting it turns on restaurant detail pages because the score comes from there. |
| `minReviewCount` | integer |  | Skip restaurants with fewer reviews than this. Setting it turns on restaurant detail pages because the review count comes from there. |
| `urls` | array | `12 links` | Paste any of these links: a prefecture or area page, a genre list in a prefecture, middle area or small area (including page-2 forms), an online-reservation list, a ranking page, or a restaurant page with its map, reviews or menu sub-pages. Lists are walked page by page; each restaurant link returns one record. Keyword search pages and other pages are skipped with a warning. Filter fields are ignored in URL mode. |
| `fetchDetails` | boolean | `True` | Open every restaurant page for full data: address, phone, rating, review count, opening hours, closing days, payment methods, seats and facilities, policies and the latest reviews. Off returns only the list-page summary. |
| `includeReviews` | boolean | `False` | Adds the restaurant's customer reviews to each row as a list, newest first: date, score, text, visit details and photos. Without this switch each detailed row carries the latest few reviews from its page. Needs 'Fetch restaurant detail pages' switched on. Each extra review is a separate paid event. |
| `maxReviewsPerShop` | integer | `20` | How many reviews to collect for each restaurant when extra reviews are on (5 reviews per page of the site). Reviews are billed per review returned, so this is also the most each restaurant can add to the bill. |
| `maxPages` | integer |  | Optional limit on list pages walked per list. Empty or 0 means unlimited. This does NOT cap the output and has no finite default: it defers to Max items (default 20), which is the only cap. |
| `maxItems` | integer | `20` | Maximum restaurants to return in total. 0 means unlimited. |
| `proxy` | object | `{'useApifyProxy': True}` | Proxy settings. The default datacenter connection works on every plan. Residential is recommended for the most reliable results, especially on large or frequent runs. If the selected connection is unavailable to your plan or is refused, the run moves on to a backup connection automatically; residential traffic from that automatic step is billed to your Apify plan. |
| `resumeFromRunId` | string |  | Run ID (or dataset ID) of a previous run of this Actor. Restaurants already collected there are skipped, so this run returns only new ones. Leave empty for a normal run. |
| `incrementalMode` | boolean | `False` | Turn this on for daily or recurring monitoring. A restaurant is UPDATED when any returned detail changes, including rating and review count; add fields you consider noise to Ignore fields below. The first run returns all matching restaurants as NEW; later runs return only NEW, UPDATED and REAPPEARED restaurants, and unchanged ones are neither returned nor billed unless Emit unchanged is on. State is kept separately for each search setup (locations, genres, links, order, online reservation filter, detail pages, minimum reviews and rating); use State key to name or share one monitoring campaign. |
| `stateKey` | string |  | Optional name for an incremental monitoring campaign. Leave empty to derive it from the search setup. |
| `emitUnchanged` | boolean | `False` | Off by default. Turn on to also return restaurants that have not changed since the last run, marked UNCHANGED. This returns, and bills, rows you already have, so leave it off unless you want the full snapshot every run. |
| `emitExpired` | boolean | `True` | On by default. Also returns restaurants that were present in an earlier run but are no longer listed, marked EXPIRED. Only produced after a run that walked every tracked list to its last page, so never when Max items or Max list pages cut the run short, when Resume was used, in URL mode with single restaurant links, or for ranking lists. Turn it off if you do not need expiry tracking: each EXPIRED row is a returned (and billed) row. |
| `ignoreFieldsForChanges` | array |  | Field names that must never make a restaurant UPDATED, for example rating, reviewCount or badges. They are still returned in every row. Nothing is ignored by default except run bookkeeping (scrapedAt, position, page, listUrl, totalResults, rank, isPromoted) and the nested customer reviews, so a new review alone does not make a restaurant UPDATED; it still does when the review count or rating changes. Used only in incremental mode. |
| `mcpConnectors` | array |  | Optionally send the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize a connector once under Apify → Settings → Integrations, then select it here. The connector receives a condensed, human-readable summary per item (title + key fields), not the full JSON, the complete record stays in the dataset. Leave empty to skip. |
| `notionParentPageUrl` | string |  | URL (or id) of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors. |
| `maxNotifyListings` | integer | `50` | Cap on items written to each connector per run. Does not affect the dataset. |

### Output Example

> Sample shape: values are illustrative placeholders, not from a live record.

```json
{
  "shopId": "J000000000",
  "name": "Example Izakaya Shinjuku",
  "displayName": "Example Izakaya",
  "url": "https://www.hotpepper.jp/strJ000000000/",
  "genre": "居酒屋",
  "genreCode": "G001",
  "area": "新宿",
  "areaCode": "Y055",
  "subArea": "新宿西口",
  "prefecture": "東京都",
  "city": "新宿区",
  "nearestStation": "新宿駅",
  "tags": [
    "新宿",
    "個室",
    "飲み放題"
  ],
  "catchphrase": "Example catch copy",
  "photo": "https://example.com/photo.jpg",
  "badges": [
    "ポイントつかえる"
  ],
  "cardAccepted": true,
  "smokingPolicy": "全席禁煙",
  "dinnerBudget": "3001～4000円",
  "lunchBudget": "501～1000円",
  "budgetDetail": "3500円(通常平均)",
  "access": "JR Shinjuku Station, 3 min on foot",
  "latitude": 35.69,
  "longitude": 139.7,
  "isPromoted": false,
  "couponTitle": "Example coupon",
  "couponUrl": "https://www.hotpepper.jp/strJ000000000/map/",
  "rating": 4.3,
  "reviewCount": 100,
  "reviews": [
    {
      "date": "2026-01-01",
      "rating": 5.0,
      "text": "Example review text."
    }
  ],
  "address": "東京都新宿区1-1-1",
  "phone": "+81-00-0000-0000",
  "hours": "月～日: 17:00～23:00",
  "closedDays": "なし",
  "creditCards": "利用可 ：VISA",
  "totalSeats": "50席",
  "totalSeatsNumber": 50,
  "maxBanquetCapacity": "40人",
  "privateRoom": "あり",
  "tatami": "なし",
  "horigotatsu": "なし",
  "counterSeats": "あり",
  "sofa": "なし",
  "terrace": "なし",
  "charterAvailable": "貸切可",
  "wifi": "あり",
  "barrierFree": "なし",
  "parking": "なし",
  "allYouCanDrink": "あり",
  "allYouCanEat": "なし",
  "alcohol": "日本酒充実",
  "childPolicy": "お子様連れOK",
  "weddingParty": "可能",
  "remarks": "Example remark",
  "cancellationPolicy": "Example policy",
  "reservationUrl": "https://www.hotpepper.jp/strJ000000000/yoyaku/",
  "servesCuisine": "居酒屋",
  "page": 1,
  "position": 1,
  "listUrl": "https://www.hotpepper.jp/SA11/G001/",
  "totalResults": 1000,
  "detailFetched": true,
  "scrapedAt": "2026-01-01T00:00:00Z"
}
```

### Plan Requirement

The actor runs on the datacenter Apify proxy by default, which works on every plan. Residential is recommended for the most reliable results, especially on large or frequent runs; select it in the proxy setting. If the selected connection is refused or keeps failing, the run steps up to Apify residential automatically (billed to your Apify plan) and steps back down once the cheaper connection reads reliably again. Apify free plans do not include residential proxies: on a free plan the run logs a notice and continues on a backup connection, and some pages may still be unavailable. To get residential access, upgrade at https://apify.com/pricing or supply your own proxy URLs. Paid Apify plans get lower tiered event rates.

What you may see in the run log:

- **Notice, connection unavailable:** "The selected connection is unavailable to this run. Apify free plans do not include residential proxies. Continuing on a backup connection; some pages may still be unavailable."
- **Info:** "Served over the backup connection (the default connection was unavailable)."
- **Failure, proxy refused:** the run ends with "The proxy connection was refused for this account, so no page could be read." and asks for a paid plan or valid proxy URLs.
- **Failure, free plan:** "No results: residential proxies are unavailable on this run, and the backup connection could not load the requested Hot Pepper Gourmet pages."
- **Failure, other:** "Could not load any results page (the requests failed), so nothing was collected. This is a connection problem, not an empty search."

### FAQ

#### How much does it cost?

Pay per event. The current rates are shown on the **Pricing** tab. The events and when each one is charged:

| Event | When it is charged |
| --- | --- |
| Result (`apify-default-dataset-item`) | once for each restaurant pushed to the dataset |
| Detail enrichment (`detail-enrichment`) | once per returned restaurant whose full detail page was added |
| Review enrichment (`review-enrichment`) | once per extra customer review returned on a restaurant row, only when extra reviews are switched on |
| Actor Start (`apify-actor-start`) | once per run, per GB of memory |

Unchanged restaurants in incremental mode are not billed. The latest reviews that come with the restaurant page have no separate charge. Extra reviews are charged per review actually returned, so **Max reviews per restaurant** bounds what each restaurant can add. Use **Max items** to cap the cost of any run.

#### Is it legal to scrape Hot Pepper Gourmet?

This actor collects only publicly available restaurant information. You are responsible for how you use it: follow the site's terms and the laws that apply to you, including Japanese data protection rules, and get legal advice if you plan commercial redistribution.

#### Can I get only new or changed restaurants on a schedule?

Yes. Schedule the actor from the **Schedules** tab and turn on **Incremental mode**.

#### Why is the rating empty on some rows?

The rating comes from the restaurant page. Turn on **Fetch restaurant detail pages**, or the row carries only the list-page summary. New restaurants with no reviews yet have no score.

#### Why did my run fail instead of returning an empty dataset?

If the site cannot be read at all, the run stops with a clear message so "no restaurants matched" is never confused with "nothing could be read". Run it again in a few minutes.

#### Can I use it with AI agents or MCP?

Yes. Call it from any Apify integration or MCP client, and use the connector field to push results into Notion, Linear or Airtable.

### 🔗 More scrapers you might like

Pair this actor with these related scrapers from the same team:

<table>
<tr><td>🧩 <a href="https://apify.com/abotapi/tabelog-scraper"><b>Tabelog Japan Scraper</b></a><br>Scrape Tabelog (tabelog.com) restaurants in Japan by keyword, area or URL. Extract names...</td><td>🧩 <a href="https://apify.com/abotapi/suumo-jp-scraper"><b>Suumo.jp Scraper</b></a><br>Scrape Suumo, Japan's largest property portal: rental rooms with rent, management fees...</td></tr>
<tr><td>🧩 <a href="https://apify.com/abotapi/mistore-jp-scraper"><b>Isetan Mitsukoshi</b></a><br>Scrape the Isetan Mitsukoshi department store online shop (mistore.jp). Search by keyword...</td><td>👗 <a href="https://apify.com/abotapi/zozotown-scraper"><b>ZOZOTOWN</b></a><br>Scrape ZOZOTOWN (zozo.jp), Japan's largest fashion marketplace: name, brand, JPY price...</td></tr>
<tr><td>🧩 <a href="https://apify.com/abotapi/rakuten-ichiba-scraper"><b>Rakuten Ichiba Scraper</b></a><br>Scrape Rakuten Ichiba (rakuten.co.jp) by keyword or URL. Extract JPY prices, discounts...</td><td>🛒 <a href="https://apify.com/abotapi/nitori-net-jp-scraper"><b>Nitori Japan Furniture &amp; Home Goods Scraper</b></a><br>Scrape Nitori Japan (nitori-net.jp) furniture and home goods by keyword, category or...</td></tr>
</table>

👉 [Browse all abotapi scrapers](https://apify.com/abotapi)

### 💬 Support

- 🐞 **Found a bug or a missing field?** Open a ticket on the [Issues tab](https://apify.com/abotapi/hotpepper-jp-scraper/issues/open). We usually reply within hours.
- 🛠️ **Need another site, extra fields or a private build?** Email <contact@abotapi.com>.
- ⭐ **Enjoying it?** A quick review on the actor page helps other users find it.

# Actor input Schema

## `mode` (type: `string`):

Search builds restaurant lists from locations and genres. URL mode takes restaurant pages or area list pages you paste. Fields in the other mode's section are ignored.

## `locations` (type: `array`):

Prefecture names such as 東京 or Tokyo, prefecture codes such as SA11, a code with an area such as SA11/Y055 or SA11/Y005/X020, or Prefecture/Area names such as 東京/新宿. One list is walked per entry.

## `genres` (type: `array`):

Keep only these genres. Leave empty to walk every genre in turn.

## `netReservationOnly` (type: `boolean`):

Only restaurants that take online reservations.

## `sortBy` (type: `string`):

Default is the site's own list order. Ranking returns the popularity ranking of each location and genre, which is a single page of about 20 restaurants; online reservation filter and Max list pages do not apply to it.

## `minRating` (type: `number`):

Skip restaurants whose average review score is below this value (0 to 5). Setting it turns on restaurant detail pages because the score comes from there.

## `minReviewCount` (type: `integer`):

Skip restaurants with fewer reviews than this. Setting it turns on restaurant detail pages because the review count comes from there.

## `urls` (type: `array`):

Paste any of these links: a prefecture or area page, a genre list in a prefecture, middle area or small area (including page-2 forms), an online-reservation list, a ranking page, or a restaurant page with its map, reviews or menu sub-pages. Lists are walked page by page; each restaurant link returns one record. Keyword search pages and other pages are skipped with a warning. Filter fields are ignored in URL mode.

## `fetchDetails` (type: `boolean`):

Open every restaurant page for full data: address, phone, rating, review count, opening hours, closing days, payment methods, seats and facilities, policies and the latest reviews. Off returns only the list-page summary.

## `includeReviews` (type: `boolean`):

Adds the restaurant's customer reviews to each row as a list, newest first: date, score, text, visit details and photos. Without this switch each detailed row carries the latest few reviews from its page. Needs 'Fetch restaurant detail pages' switched on. Each extra review is a separate paid event.

## `maxReviewsPerShop` (type: `integer`):

How many reviews to collect for each restaurant when extra reviews are on (5 reviews per page of the site). Reviews are billed per review returned, so this is also the most each restaurant can add to the bill.

## `maxPages` (type: `integer`):

Optional limit on list pages walked per list. Empty or 0 means unlimited. This does NOT cap the output and has no finite default: it defers to Max items (default 20), which is the only cap.

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

Maximum restaurants to return in total. 0 means unlimited.

## `proxy` (type: `object`):

Proxy settings. The default datacenter connection works on every plan. Residential is recommended for the most reliable results, especially on large or frequent runs. If the selected connection is unavailable to your plan or is refused, the run moves on to a backup connection automatically; residential traffic from that automatic step is billed to your Apify plan.

## `resumeFromRunId` (type: `string`):

Run ID (or dataset ID) of a previous run of this Actor. Restaurants already collected there are skipped, so this run returns only new ones. Leave empty for a normal run.

## `incrementalMode` (type: `boolean`):

Turn this on for daily or recurring monitoring. A restaurant is UPDATED when any returned detail changes, including rating and review count; add fields you consider noise to Ignore fields below. The first run returns all matching restaurants as NEW; later runs return only NEW, UPDATED and REAPPEARED restaurants, and unchanged ones are neither returned nor billed unless Emit unchanged is on. State is kept separately for each search setup (locations, genres, links, order, online reservation filter, detail pages, minimum reviews and rating); use State key to name or share one monitoring campaign.

## `stateKey` (type: `string`):

Optional name for an incremental monitoring campaign. Leave empty to derive it from the search setup.

## `emitUnchanged` (type: `boolean`):

Off by default. Turn on to also return restaurants that have not changed since the last run, marked UNCHANGED. This returns, and bills, rows you already have, so leave it off unless you want the full snapshot every run.

## `emitExpired` (type: `boolean`):

On by default. Also returns restaurants that were present in an earlier run but are no longer listed, marked EXPIRED. Only produced after a run that walked every tracked list to its last page, so never when Max items or Max list pages cut the run short, when Resume was used, in URL mode with single restaurant links, or for ranking lists. Turn it off if you do not need expiry tracking: each EXPIRED row is a returned (and billed) row.

## `ignoreFieldsForChanges` (type: `array`):

Field names that must never make a restaurant UPDATED, for example rating, reviewCount or badges. They are still returned in every row. Nothing is ignored by default except run bookkeeping (scrapedAt, position, page, listUrl, totalResults, rank, isPromoted) and the nested customer reviews, so a new review alone does not make a restaurant UPDATED; it still does when the review count or rating changes. Used only in incremental mode.

## `mcpConnectors` (type: `array`):

Optionally send the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize a connector once under Apify → Settings → Integrations, then select it here. The connector receives a condensed, human-readable summary per item (title + key fields), not the full JSON, the complete record stays in the dataset. Leave empty to skip. Supported: Notion (https://mcp.notion.com/mcp), Linear (https://mcp.linear.app/sse), Airtable (https://mcp.airtable.com/mcp), Apify (https://mcp.apify.com).

## `notionParentPageUrl` (type: `string`):

URL (or id) of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors.

## `maxNotifyListings` (type: `integer`):

Cap on items written to each connector per run. Does not affect the dataset.

## Actor input object example

```json
{
  "mode": "search",
  "locations": [
    "東京"
  ],
  "netReservationOnly": false,
  "sortBy": "default",
  "urls": [
    "https://www.hotpepper.jp/SA11/",
    "https://www.hotpepper.jp/SA11/G001/",
    "https://www.hotpepper.jp/SA11/G001/bgn2/",
    "https://www.hotpepper.jp/SA11/Y055/G001/",
    "https://www.hotpepper.jp/SA11/Y005/X020/G001/",
    "https://www.hotpepper.jp/SA11/net1/",
    "https://www.hotpepper.jp/SA11/rank/",
    "https://www.hotpepper.jp/strJ000239981/",
    "https://www.hotpepper.jp/strJ000239981/map/",
    "https://www.hotpepper.jp/strJ000239981/report/",
    "https://www.hotpepper.jp/strJ000239981/food/",
    "https://www.hotpepper.jp/strJ000239981/?vos=nhppvccp99002"
  ],
  "fetchDetails": true,
  "includeReviews": false,
  "maxReviewsPerShop": 20,
  "maxItems": 20,
  "proxy": {
    "useApifyProxy": true
  },
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": true,
  "maxNotifyListings": 50
}
```

# Actor output Schema

## `overview` (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 = {
    "mode": "search",
    "locations": [
        "東京"
    ],
    "netReservationOnly": false,
    "sortBy": "default",
    "urls": [
        "https://www.hotpepper.jp/SA11/",
        "https://www.hotpepper.jp/SA11/G001/",
        "https://www.hotpepper.jp/SA11/G001/bgn2/",
        "https://www.hotpepper.jp/SA11/Y055/G001/",
        "https://www.hotpepper.jp/SA11/Y005/X020/G001/",
        "https://www.hotpepper.jp/SA11/net1/",
        "https://www.hotpepper.jp/SA11/rank/",
        "https://www.hotpepper.jp/strJ000239981/",
        "https://www.hotpepper.jp/strJ000239981/map/",
        "https://www.hotpepper.jp/strJ000239981/report/",
        "https://www.hotpepper.jp/strJ000239981/food/",
        "https://www.hotpepper.jp/strJ000239981/?vos=nhppvccp99002"
    ],
    "includeReviews": false,
    "maxReviewsPerShop": 20,
    "maxItems": 20,
    "proxy": {
        "useApifyProxy": true
    },
    "incrementalMode": false,
    "emitUnchanged": false,
    "emitExpired": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("abotapi/hotpepper-jp-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 = {
    "mode": "search",
    "locations": ["東京"],
    "netReservationOnly": False,
    "sortBy": "default",
    "urls": [
        "https://www.hotpepper.jp/SA11/",
        "https://www.hotpepper.jp/SA11/G001/",
        "https://www.hotpepper.jp/SA11/G001/bgn2/",
        "https://www.hotpepper.jp/SA11/Y055/G001/",
        "https://www.hotpepper.jp/SA11/Y005/X020/G001/",
        "https://www.hotpepper.jp/SA11/net1/",
        "https://www.hotpepper.jp/SA11/rank/",
        "https://www.hotpepper.jp/strJ000239981/",
        "https://www.hotpepper.jp/strJ000239981/map/",
        "https://www.hotpepper.jp/strJ000239981/report/",
        "https://www.hotpepper.jp/strJ000239981/food/",
        "https://www.hotpepper.jp/strJ000239981/?vos=nhppvccp99002",
    ],
    "includeReviews": False,
    "maxReviewsPerShop": 20,
    "maxItems": 20,
    "proxy": { "useApifyProxy": True },
    "incrementalMode": False,
    "emitUnchanged": False,
    "emitExpired": True,
}

# Run the Actor and wait for it to finish
run = client.actor("abotapi/hotpepper-jp-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 '{
  "mode": "search",
  "locations": [
    "東京"
  ],
  "netReservationOnly": false,
  "sortBy": "default",
  "urls": [
    "https://www.hotpepper.jp/SA11/",
    "https://www.hotpepper.jp/SA11/G001/",
    "https://www.hotpepper.jp/SA11/G001/bgn2/",
    "https://www.hotpepper.jp/SA11/Y055/G001/",
    "https://www.hotpepper.jp/SA11/Y005/X020/G001/",
    "https://www.hotpepper.jp/SA11/net1/",
    "https://www.hotpepper.jp/SA11/rank/",
    "https://www.hotpepper.jp/strJ000239981/",
    "https://www.hotpepper.jp/strJ000239981/map/",
    "https://www.hotpepper.jp/strJ000239981/report/",
    "https://www.hotpepper.jp/strJ000239981/food/",
    "https://www.hotpepper.jp/strJ000239981/?vos=nhppvccp99002"
  ],
  "includeReviews": false,
  "maxReviewsPerShop": 20,
  "maxItems": 20,
  "proxy": {
    "useApifyProxy": true
  },
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": true
}' |
apify call abotapi/hotpepper-jp-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,abotapi/hotpepper-jp-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/oWoWNnkQHy4tYajFE/builds/RbSywLRKtxClfxuVx/openapi.json
