# Hot Pepper Gourmet API Scraper (`cloud9_ai/hotpepper-scraper`) Actor
Extract restaurant data via official Hot Pepper Gourmet API: name, address, genre, budget, ratings, photos, coupons, booking links. Fast, reliable, API-compliant. Build food apps, local guides, competitor analysis.
- **URL**: https://apify.com/cloud9\_ai/hotpepper-scraper.md
- **Developed by:** [cloud9](https://apify.com/cloud9_ai) (community)
- **Categories:** Travel, Integrations
- **Stats:** 2 total users, 1 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/platform/actors/running/actors-in-store#pay-per-event
## What's an Apify Actor?
Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use 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
## Hot Pepper Gourmet Scraper
Extract comprehensive restaurant data from Japan's Hot Pepper Gourmet platform via the official Recruit API. Get restaurant names, addresses, genres, budgets, ratings, photos, and detailed operational information with reliable API-based scraping.
### Features
- **Official API Integration**: Uses Hot Pepper Gourmet Search API for reliable data extraction
- **Flexible Search**: Filter by keyword, area, and genre code
- **Comprehensive Data**: Extract 40+ data points including names, addresses, photos, opening hours, facilities
- **Pagination Support**: Automatically handles pagination to fetch up to 1,000+ results
- **Structured Output**: Clean JSON format with normalized field names
- **Rate Limited**: Built-in request delays (300ms) to respect API rate limits
- **Error Handling**: Robust error handling with detailed logging
- **Timestamp Tracking**: Records scrape time for data freshness tracking
### Use Cases
- **Restaurant Marketing**: Build a local restaurant database for marketing campaigns
- **Market Research**: Analyze restaurant distribution, genres, and budget segments in Japan
- **Business Intelligence**: Monitor competitor restaurants by area and cuisine type
- **Travel Planning**: Extract restaurant recommendations for specific regions and cuisines
- **Data Integration**: Sync Hot Pepper restaurant data to your CRM, spreadsheets, or database
### Input
```json
{
"keyword": "イタリアン",
"area": "Z011",
"genre": "G001",
"apiKey": "your-api-key-here",
"maxResults": 500
}
````
#### Input Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `apiKey` | string | Yes | - | Your Hot Pepper Gourmet API key from . Keep this secret. |
| `keyword` | string | No | - | Search keyword (e.g., restaurant name, cuisine type like "イタリアン" for Italian). |
| `area` | string | No | - | Area code for geographic filtering (e.g., "Z011" for Tokyo). See [Hot Pepper API documentation](https://webservice.recruit.co.jp/hotpepper/gourmet/v1/documentation.html) for complete area codes. |
| `genre` | string | No | - | Genre code for cuisine filtering (e.g., "G001" for Japanese, "G002" for Western). See Hot Pepper API documentation for genre codes. |
| `maxResults` | integer | No | 100 | Maximum number of restaurants to fetch (1-1000). Higher values mean longer execution time and higher costs. |
#### Area Code Examples
- `Z011` - Tokyo
- `Z012` - Yokohama
- `Z013` - Kawasaki
- `Z021` - Osaka
- `Z022` - Kobe
- See API docs for complete list of 47 prefecture codes
#### Genre Code Examples
- `G001` - Japanese cuisine
- `G002` - Western cuisine
- `G003` - Italian
- `G004` - French
- `G006` - Chinese
- `G007` - Korean
- `G008` - Asian
- See API docs for complete list of 20+ genre codes
### Output
```json
{
"id": "J000123456",
"name": "Restaurant Name",
"nameKana": "レストランメイ",
"address": "東京都渋谷区道玄坂1-2-3",
"stationName": "渋谷駅",
"latitude": 35.6595,
"longitude": 139.7004,
"genre": "イタリアン",
"genreCode": "G003",
"genreCatch": "Italian restaurant in Tokyo",
"subGenre": null,
"budget": "¥3,000～¥3,999",
"budgetAverage": "¥3,500",
"budgetMemo": "Average per person",
"catchPhrase": "Authentic Italian in Shibuya",
"capacity": 60,
"access": "5 minutes walk from Shibuya Station",
"url": "https://www.hotpepper.jp/strJ000123456/",
"photoUrlLarge": "https://...",
"photoUrlMedium": "https://...",
"openingHours": "11:00～23:00",
"closingDays": "Mondays",
"partyCapacity": 20,
"wifi": "yes",
"creditCard": "yes",
"privateRoom": "yes",
"lunch": "available",
"midnight": "available",
"english": "available",
"pet": "yes",
"child": "yes",
"parking": "yes",
"barrierFree": "yes",
"nonSmoking": "yes",
"scrapedAt": "2024-02-12T10:30:45.123Z"
}
```
#### Output Fields
| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique restaurant ID in Hot Pepper system |
| `name` | string | Restaurant name in Japanese |
| `nameKana` | string | Restaurant name in Katakana |
| `address` | string | Full address including prefecture, city, and street |
| `stationName` | string | Nearest train station |
| `latitude` | number | Geographic latitude coordinate |
| `longitude` | number | Geographic longitude coordinate |
| `genre` | string | Primary cuisine genre (e.g., "イタリアン") |
| `genreCode` | string | Genre code used for filtering |
| `budget` | string | Typical budget range (e.g., "¥3,000～¥3,999") |
| `budgetAverage` | string | Average cost per person |
| `catchPhrase` | string | Restaurant's marketing catch phrase |
| `capacity` | number | Total seating capacity |
| `url` | string | Direct link to Hot Pepper restaurant page |
| `photoUrlLarge` | string | Large restaurant photo URL (480x360px) |
| `photoUrlMedium` | string | Medium restaurant photo URL (300x225px) |
| `openingHours` | string | Opening hours (e.g., "11:00～23:00") |
| `closingDays` | string | Days the restaurant is closed |
| `partyCapacity` | number | Maximum party size accommodated |
| `wifi` | string | WiFi availability ("yes" / "no") |
| `creditCard` | string | Credit card acceptance ("yes" / "no") |
| `privateRoom` | string | Private room availability ("yes" / "no") |
| `lunch` | string | Lunch availability ("available" / unavailable) |
| `midnight` | string | Late-night service ("available" / unavailable) |
| `english` | string | English language support ("yes" / "no") |
| `pet` | string | Pet-friendly ("yes" / "no") |
| `child` | string | Child-friendly ("yes" / "no") |
| `parking` | string | Parking available ("yes" / "no") |
| `barrierFree` | string | Wheelchair accessible ("yes" / "no") |
| `nonSmoking` | string | Non-smoking areas ("yes" / "no") |
| `scrapedAt` | string | ISO 8601 timestamp of data collection |
### Pricing
**$3 per 1,000 restaurants**
#### Cost Examples
| Restaurants | Cost |
|-------------|------|
| 100 | $0.30 |
| 500 | $1.50 |
| 1,000 | $3.00 |
| 5,000 | $15.00 |
| 10,000 | $30.00 |
*Note: Pricing is based on actual data fetched. Empty results (no matching restaurants) do not incur charges.*
### Tips
1. **Get a Free API Key**: Register at to obtain a Hot Pepper API key. Free tier allows up to 50,000 API calls/month.
2. **Start with Keywords**: If you're new to Hot Pepper, search by keyword (e.g., "ラーメン" for ramen) before filtering by area or genre codes.
3. **Use Area Codes for Geographic Targeting**: Combine area codes with keywords to narrow results to specific regions (Tokyo, Osaka, etc.).
4. **Paginate Large Datasets**: Set `maxResults` to 1000 per run and run multiple actors with different area codes to avoid timeout issues.
5. **Cache Results Locally**: Store exported restaurant data in your database to avoid re-scraping the same data repeatedly.
6. **Monitor API Quota**: Hot Pepper Free API has rate limits. The actor includes 300ms delays between requests to stay within limits.
7. **Export to Popular Formats**: The Apify platform supports exporting results as JSON, CSV, Excel, or direct database integration.
8. **Verify Open Hours**: The `openingHours` field may contain special notation (e.g., "11:00～23:00 (金・土は～0:00)"). Parse carefully for conditional hours.
9. **Photo URLs Expire**: Hot Pepper photo URLs may expire after 30 days. Download and store images locally if archiving data long-term.
10. **API Response Time**: Budget approximately 2-5 minutes for 1,000 restaurant results depending on API latency.
### Integrations
Export scraped restaurant data to your favorite platforms:
- **Google Sheets**: Automatically push results to Google Sheets via Zapier/Make
- **Excel/CSV**: Download results in Excel format with formatted columns
- **Webhooks**: Send data to your API endpoint for real-time processing
- **Database**: Sync directly to PostgreSQL, MongoDB, MySQL via Apify integrations
- **Zapier/Make**: Create workflows to send restaurant data to CRM, email, Slack
- **Google Maps**: Import latitude/longitude for location visualization
- **Data Studio**: Create dashboards and visualizations from Hot Pepper data
### Support
For issues, feature requests, or API troubleshooting:
- **Hot Pepper API Help**: [Official Documentation](https://webservice.recruit.co.jp/hotpepper/gourmet/v1/documentation.html)
- **Apify Support**: [Apify Support Center](https://support.apify.com/)
- **Report Issues**: Open an issue on GitHub or contact support through Apify
### License
Apache-2.0 License
***
**Data Source**: Hot Pepper Gourmet (ホットペッパーグルメ) - Official API by Recruit Co., Ltd.
**Last Updated**: 2024-02-12
# Actor input Schema
## `keyword` (type: `string`):
Search keyword (e.g., restaurant name, cuisine type)
## `area` (type: `string`):
Area code for search (e.g., 'Z011' for Tokyo). See Hot Pepper API docs for area codes.
## `genre` (type: `string`):
Genre code for search (e.g., 'G001' for Japanese food). See Hot Pepper API docs for genre codes.
## `apiKey` (type: `string`):
Your Hot Pepper Gourmet API key from https://webservice.recruit.co.jp/
## `maxResults` (type: `integer`):
Maximum number of results to fetch (default: 100)
## Actor input object example
```json
{
"maxResults": 100
}
```
# 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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {};
// Run the Actor and wait for it to finish
const run = await client.actor("cloud9_ai/hotpepper-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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {}
# Run the Actor and wait for it to finish
run = client.actor("cloud9_ai/hotpepper-scraper").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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 cloud9_ai/hotpepper-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=cloud9_ai/hotpepper-scraper",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Hot Pepper Gourmet API Scraper",
"description": "Extract restaurant data via official Hot Pepper Gourmet API: name, address, genre, budget, ratings, photos, coupons, booking links. Fast, reliable, API-compliant. Build food apps, local guides, competitor analysis.",
"version": "0.1",
"x-build-id": "MsTUnv2Jcja3BuAKf"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/cloud9_ai~hotpepper-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-cloud9_ai-hotpepper-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/cloud9_ai~hotpepper-scraper/runs": {
"post": {
"operationId": "runs-sync-cloud9_ai-hotpepper-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/cloud9_ai~hotpepper-scraper/run-sync": {
"post": {
"operationId": "run-sync-cloud9_ai-hotpepper-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"properties": {
"keyword": {
"title": "Keyword",
"type": "string",
"description": "Search keyword (e.g., restaurant name, cuisine type)"
},
"area": {
"title": "Area",
"type": "string",
"description": "Area code for search (e.g., 'Z011' for Tokyo). See Hot Pepper API docs for area codes."
},
"genre": {
"title": "Genre",
"type": "string",
"description": "Genre code for search (e.g., 'G001' for Japanese food). See Hot Pepper API docs for genre codes."
},
"apiKey": {
"title": "Hot Pepper API Key",
"type": "string",
"description": "Your Hot Pepper Gourmet API key from https://webservice.recruit.co.jp/"
},
"maxResults": {
"title": "Max Results",
"minimum": 1,
"maximum": 1000,
"type": "integer",
"description": "Maximum number of results to fetch (default: 100)",
"default": 100
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```