# SUUMO Property Scraper (`cloud9_ai/suumo-scraper`) Actor

Search and extract product data from Rakuten Ichiba (Japan's largest\
e-commerce): title, price, reviews, ratings, shop info, images. API-based\
for 100% reliability. Perfect for price monitoring, competitor analysis,\
market research.

- **URL**: https://apify.com/cloud9\_ai/suumo-scraper.md
- **Developed by:** [cloud9](https://apify.com/cloud9_ai) (community)
- **Categories:** E-commerce, Lead generation
- **Stats:** 4 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.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

## SUUMO Property Scraper | スーモ不動産検索

Extract comprehensive rental property data from SUUMO, Japan's largest real estate platform. Get rent, deposit, floor plans, location, station access, and more for market analysis, investment research, and relocation planning.

### Features

- **Comprehensive Data Extraction**: Rent, management fees, deposit, key money, floor plan, area size, building age, floor, address, nearest station, walk time, property URL, and image
- **Flexible Filtering**: Search by area, keyword, and rent range
- **Pagination Support**: Automatically follows "次へ" (next) links to collect results across multiple pages
- **Rate Limiting**: Respects SUUMO's servers with 2-second delays between requests
- **Japanese Text Handling**: Properly handles UTF-8 encoding for accurate data extraction
- **Robust Error Handling**: Fallback selectors and validation for missing elements
- **Structured Output**: Clean, ready-to-analyze JSON data with timestamps

### Use Cases

#### Real Estate Market Analysis
- Track rent trends across different neighborhoods
- Compare property prices by area, station, and floor plan
- Identify undervalued properties for investment
- Monitor seasonal price fluctuations

#### Investment Research
- Analyze ROI potential for rental properties
- Evaluate deposit and key money requirements
- Compare building age vs. rent correlation
- Identify high-demand areas by property density

#### Relocation Planning
- Find properties matching budget and location criteria
- Compare commute times from different stations
- Filter by floor plan (1K, 1LDK, 2LDK, etc.)
- Analyze total move-in costs (deposit + key money)

#### Competitive Intelligence
- Monitor competitor pricing strategies
- Track new listing volumes
- Analyze market saturation by area
- Identify emerging rental hotspots

### Input Parameters

| Parameter | Type | Required | Description | Example |
|-----------|------|----------|-------------|---------|
| `area` | string | Yes | SUUMO area code | `"tokyo"`, `"osaka"`, `"kanagawa"` |
| `keyword` | string | No | Search keyword (station, area name) | `"渋谷"`, `"新宿"` |
| `minRent` | integer | No | Minimum monthly rent in 万円 | `5` (= 50,000 yen) |
| `maxRent` | integer | No | Maximum monthly rent in 万円 | `20` (= 200,000 yen) |
| `maxResults` | integer | No | Maximum properties to scrape (default: 50, max: 500) | `100` |

#### Common Area Codes

- Tokyo: `tokyo`
- Osaka: `osaka`
- Kanagawa: `kanagawa`
- Fukuoka: `fukuoka`
- Sapporo: `sapporo`
- Kyoto: `kyoto`
- Aichi: `aichi`

### Output

Each property listing includes:

```json
{
  "propertyName": "レジデンス渋谷",
  "rent": "12.5万円",
  "managementFee": "8000円",
  "deposit": "1ヶ月",
  "keyMoney": "1ヶ月",
  "floorPlan": "1K",
  "areaSize": "25.50m²",
  "buildingAge": "築5年",
  "floor": "3階",
  "address": "東京都渋谷区渋谷1丁目",
  "nearestStation": "JR山手線/渋谷駅",
  "walkTime": "8分",
  "propertyUrl": "https://suumo.jp/chintai/jnc_...",
  "imageUrl": "https://img01.suumo.com/...",
  "scrapedAt": "2024-01-15T10:30:45.123Z"
}
````

### Example Usage

#### Basic Search - Tokyo Properties

```json
{
  "area": "tokyo",
  "maxResults": 100
}
```

#### Filtered Search - Shibuya Area, Budget 5-15万円

```json
{
  "area": "tokyo",
  "keyword": "渋谷",
  "minRent": 5,
  "maxRent": 15,
  "maxResults": 200
}
```

#### Investment Research - Osaka, High-End Properties

```json
{
  "area": "osaka",
  "minRent": 20,
  "maxResults": 150
}
```

### Data Analysis Tips

#### Calculate Total Move-In Cost

Extract numeric values from `deposit`, `keyMoney`, and `rent` to calculate initial payment required.

#### Station Accessibility Score

Lower `walkTime` values indicate better accessibility. Filter properties with ≤10 minutes walk time for premium listings.

#### Price per Square Meter

Divide rent by area size to compare value across different properties.

#### Building Age Premium

Compare rent differences between `築5年` (5 years old) and `新築` (new construction) properties.

### Pricing

- **$4 per 1,000 properties scraped**
- Includes all data fields and images
- No setup fees or minimums
- Pay only for successful scrapes

### Performance

- **Speed**: ~50-100 properties per minute (with 2-second rate limiting)
- **Reliability**: 95%+ success rate
- **Scalability**: Handles up to 500 properties per run
- **Data Quality**: Validated extraction with fallback selectors

### Technical Notes

#### Rate Limiting

The actor implements a 2-second delay between requests to respect SUUMO's servers. This prevents IP blocking and ensures stable long-term usage.

#### Encoding

All Japanese text is properly handled with UTF-8 encoding to preserve kanji, hiragana, and katakana characters.

#### Pagination

Automatically detects and follows "次へ" (next page) links until `maxResults` is reached or no more pages are available.

#### Error Handling

If a data field is missing, the actor returns `"N/A"` instead of failing, ensuring consistent output format.

### Limitations

- Requires valid area codes (see Common Area Codes section)
- Maximum 500 properties per run (technical limitation)
- Does not scrape property detail pages (only listing pages)
- Images may be lazy-loaded thumbnails

### Support

For questions, bug reports, or feature requests:

- GitHub Issues: [github.com/tars/suumo-scraper](https://github.com/tars/suumo-scraper)
- Email: support@tars.ai

### Legal & Ethics

This actor is designed for personal research and market analysis. Users must comply with:

- SUUMO's Terms of Service
- Japanese copyright laws
- GDPR and privacy regulations
- Rate limiting best practices

Do not use scraped data for:

- Republishing SUUMO's content without permission
- Spamming property owners or agents
- Creating competing real estate platforms
- Violating user privacy

### Version History

- **0.1.0** (2024-01): Initial release with basic scraping functionality

# Actor input Schema

## `area` (type: `string`):

Prefecture or area to search (e.g., 'tokyo', 'osaka', 'fukuoka'). Supports English and Japanese.

## `districtMode` (type: `string`):

Prefecture level: broad search. Ward level: curated high-demand wards (better for minpaku analysis). Custom: specify sc codes manually.

## `customSc` (type: `string`):

Comma-separated SUUMO district sc codes. Only used when districtMode=custom. Example: '13104,13113' for Shinjuku & Shibuya.

## `keyword` (type: `string`):

Optional keyword to filter properties (e.g., station name, area name, '民泊可')

## `minRent` (type: `integer`):

Minimum monthly rent in 万円 (e.g., 5 = 50,000 yen)

## `maxRent` (type: `integer`):

Maximum monthly rent in 万円 (e.g., 20 = 200,000 yen)

## `maxResults` (type: `integer`):

Maximum number of properties to scrape

## `enableGeocoding` (type: `boolean`):

Fetch latitude/longitude via 国土地理院 API (free, no API key required). 1 API call per unique city/ward. Adds ~1-3 sec.

## `minpakuFilter` (type: `boolean`):

Only return properties explicitly mentioning 民泊可 / 民泊OK in the listing

## Actor input object example

```json
{
  "area": "tokyo",
  "districtMode": "prefecture",
  "customSc": "13104,13113",
  "keyword": "渋谷",
  "minRent": 5,
  "maxRent": 20,
  "maxResults": 50,
  "enableGeocoding": false,
  "minpakuFilter": 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 = {
    "area": "tokyo",
    "districtMode": "prefecture",
    "maxResults": 50,
    "enableGeocoding": false,
    "minpakuFilter": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("cloud9_ai/suumo-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 = {
    "area": "tokyo",
    "districtMode": "prefecture",
    "maxResults": 50,
    "enableGeocoding": False,
    "minpakuFilter": False,
}

# Run the Actor and wait for it to finish
run = client.actor("cloud9_ai/suumo-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 '{
  "area": "tokyo",
  "districtMode": "prefecture",
  "maxResults": 50,
  "enableGeocoding": false,
  "minpakuFilter": false
}' |
apify call cloud9_ai/suumo-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=cloud9_ai/suumo-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "SUUMO Property Scraper",
        "description": "Search and extract product data from Rakuten Ichiba (Japan's largest       \n e-commerce): title, price, reviews, ratings, shop info, images. API-based             \n for 100% reliability. Perfect for price monitoring, competitor analysis,              \n market research.",
        "version": "0.1",
        "x-build-id": "NyOZuSrAlvDWfWmFu"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/cloud9_ai~suumo-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-cloud9_ai-suumo-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~suumo-scraper/runs": {
            "post": {
                "operationId": "runs-sync-cloud9_ai-suumo-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~suumo-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-cloud9_ai-suumo-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",
                "required": [
                    "area"
                ],
                "properties": {
                    "area": {
                        "title": "Area / Prefecture",
                        "type": "string",
                        "description": "Prefecture or area to search (e.g., 'tokyo', 'osaka', 'fukuoka'). Supports English and Japanese.",
                        "default": "tokyo"
                    },
                    "districtMode": {
                        "title": "District Mode",
                        "enum": [
                            "prefecture",
                            "ward",
                            "custom"
                        ],
                        "type": "string",
                        "description": "Prefecture level: broad search. Ward level: curated high-demand wards (better for minpaku analysis). Custom: specify sc codes manually.",
                        "default": "prefecture"
                    },
                    "customSc": {
                        "title": "Custom District Codes (sc)",
                        "type": "string",
                        "description": "Comma-separated SUUMO district sc codes. Only used when districtMode=custom. Example: '13104,13113' for Shinjuku & Shibuya."
                    },
                    "keyword": {
                        "title": "Search Keyword",
                        "type": "string",
                        "description": "Optional keyword to filter properties (e.g., station name, area name, '民泊可')"
                    },
                    "minRent": {
                        "title": "Minimum Rent (万円)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Minimum monthly rent in 万円 (e.g., 5 = 50,000 yen)"
                    },
                    "maxRent": {
                        "title": "Maximum Rent (万円)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Maximum monthly rent in 万円 (e.g., 20 = 200,000 yen)"
                    },
                    "maxResults": {
                        "title": "Maximum Results",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Maximum number of properties to scrape",
                        "default": 50
                    },
                    "enableGeocoding": {
                        "title": "Enable Geocoding (lat/lng)",
                        "type": "boolean",
                        "description": "Fetch latitude/longitude via 国土地理院 API (free, no API key required). 1 API call per unique city/ward. Adds ~1-3 sec.",
                        "default": false
                    },
                    "minpakuFilter": {
                        "title": "Minpaku (民泊) Properties Only",
                        "type": "boolean",
                        "description": "Only return properties explicitly mentioning 民泊可 / 民泊OK in the listing",
                        "default": false
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```