# Suumo.jp Scraper - Japan Rental Listings, Prices & Agents (`abotapi/suumo-jp-scraper`) Actor

Scrape Suumo, Japan's largest property portal: rental rooms with rent, management fees, deposits, layout, floor area, station access, photos and the listing agency's name. Search by prefecture and city or paste links, and monitor price changes with recurring updates.

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

## Pricing

from $1.20 / 1,000 listing 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

## Suumo.jp Scraper

Scrape Suumo (suumo.jp), Japan's largest property portal, for rental
listings: rent, management fees, deposits and key money, layout, floor area,
floor, building age, address, station access with walking times, photos and
the listing agency's name. Monitor price changes with recurring updates.

### Why this actor

- **Search by area**: pick a prefecture and optionally JIS city codes; the
  actor walks suumo's rental result pages forward for every city you list.
- **Links mode**: paste rental search links (`/jj/chintai/ichiran/...`) or
  single room links (`/chintai/jnc_.../`). Pagination starts at the page
  named in the link and walks forward.
- **Server-side layout filter**: room layouts are applied by suumo's own
  search grammar, so you never download rooms the filter removes.
- **Room detail reading**: the search page carries the headline fields; a
  room's own page adds the photo set, the full spec table, the agency's
  pitch and the agency name.
- **Recurring updates**: label every room NEW, UPDATED, UNCHANGED,
  REAPPEARED or EXPIRED against the previous run of the same setup, so a
  scheduled run only returns what changed.
- **Resume**: an interrupted run can continue from where it stopped by run
  id, skipping everything already collected.

### Output

Every record is one rental room. Headline fields:

| Field | Meaning |
|---|---|
| `id` | suumo room id (from the `/chintai/jnc_<id>/` link) |
| `rentYen` / `rentDisplay` | monthly rent in yen, and the site's own display form |
| `mgmtFeeYen` | monthly management / common-service fee in yen |
| `depositYen` / `keyMoneyYen` | deposit (shikikin) and key money (reikin) in yen |
| `layout` / `areaSqm` | room layout (1K, 1LDK, ...) and floor area in square meters |
| `floor` | the room's floor |
| `buildingName` / `buildingType` | building name and type (rental mansion, apartment, house) |
| `address` | building address |
| `stations` | station access lines with walking times, e.g. `Toei Shinjuku Line/Ogawamachi Station walk 1 min` (original wording in Japanese) |
| `buildingAge` / `buildingFloors` | building age and total floors |
| `url` / `imageUrl` | room page link and listing photo |

Detail fields (when reading room pages is on, or for pasted room links):
`photos`, `photoCount`, `transport`, `facing`, `structure`, `builtMonth`,
`moveIn`, `dealType`, `guaranteeCompany`, `otherInitialCost`,
`otherMonthlyCost`, `remarks`, `point`, `pointText`, `agencyName` and the
rest of suumo's spec table.

Sample rows (illustrative, not from a live listing):

| id | buildingName | rentYen | layout | areaSqm | address |
|---|---|---|---|---|---|
| 000000000001 | Sample Residence Chiyoda | 161000 | 1DK | 26.0 | Tokyo, Chiyoda-ku |
| 000000000002 | Example Heights Shinjuku | 128000 | 1K | 20.1 | Tokyo, Shinjuku-ku |

### Usage

1. Pick the mode.
2. Search mode: choose the prefecture, optionally list JIS city codes
   (5-digit codes, exactly as suumo uses them in its own links: 13101
   Chiyoda-ku, 13102 Chuo-ku, ...). An empty city list walks the whole
   prefecture. Narrow with the layout codes if needed.
3. Links mode: paste one or more search or room links.
4. Optional: turn on room detail reading for photos, the spec table and the
   agency name (a per-room surcharge applies). Pasted room links are their
   own page, so they are always read.
5. Set max rooms to cap the run (the default run caps at the site's own
   result order; 0 walks until the site runs out).

### Notes and limits

- This actor covers the **rental** side of suumo (chintai). The sale, land
  and new-build verticals use a different page structure and are not
  supported; pasting those links fails with a clear message.
- One run covers one prefecture. City codes must belong to the selected
  prefecture; the run fails fast when one does not.
- Room availability changes hourly on suumo. A room that disappears between
  runs is reported EXPIRED by recurring updates only after a complete scan.
- The layout filter is the filter suumo itself verifies in its search URL;
  the actor ships only filters measured against the live site, so no filter
  silently does nothing.

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

Connect an MCP Connector to this actor and results are piped into your apps
after each run. The optional input fields `mcpConnectors`,
`notionParentPageUrl` and `maxNotifyListings` control delivery; they are
never required.

# Actor input Schema

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

Search by area walks the rental result pages for the prefecture and cities below. My own links walks the links you paste, forward from the page each link names.

## `prefecture` (type: `string`):

The prefecture to search, as its two-digit JIS code. One run covers one prefecture.

## `cityCodes` (type: `array`):

JIS 5-digit city codes, exactly as suumo uses them in its own search links: 13101 Chiyoda-ku, 13102 Chuo-ku, 13103 Minato-ku, 13104 Shinjuku-ku, 13113 Shibuya-ku, and so on. Every city is walked as its own source and shares the run limit. Leave empty to walk the whole prefecture.

## `layouts` (type: `array`):

Room layout filter applied by the site itself, as the two-digit codes of suumo's own search grammar: 01 studio (one room), 02 1K, 03 1DK, 04 1LDK, 05 2K, 06 2DK, 07 2LDK, 08 3K, 09 3DK, 10 3LDK, 11 4K, 12 4DK, 13 4LDK. Empty means every layout.

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

Multi-URL supported. Paste rental search links (/jj/chintai/ichiran/...) or single room links (/chintai/jnc\_.../). Pagination starts at the page named in the link and walks forward. Search-mode fields are ignored in this mode.

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

The search page carries rent, fees, layout, area, address, stations and building age. A room's own page adds the photo set, the full spec table, the agency's pitch and the agency name. Pasted room links are their own page, so they are always read and always carry the surcharge.

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

The single limit that stops a run. 0 means no limit: the walk ends when the site runs out of results.

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

Runaway guard per source. 0 means the walk ends when the site runs out of results.

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

Give the run id of an interrupted run and every room it already collected is skipped. Mutually exclusive with recurring updates once a baseline exists.

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

Label every room NEW, UPDATED, UNCHANGED or REAPPEARED against the previous run of the same setup, and record the ones that vanished as EXPIRED. Unchanged rooms are not returned unless you also turn on the return-unchanged switch. Returns (and bills) extra rows only for what changed.

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

Name the baseline of a recurring schedule yourself. Without it the baseline is keyed on the whole search setup, so two differently-configured schedules never share one baseline.

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

Returns (and bills) every tracked room again, labelled UNCHANGED, instead of only the changed ones.

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

Rooms tracked by the previous run but absent from a COMPLETE scan are returned (and billed) one last time, labelled EXPIRED. A run that stopped early never reports rooms as gone.

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

Optional delivery step AFTER the scrape: pipes dataset results into apps you connected in the Apify MCP Connector setup.

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

Notion connector only: the parent page new Notion pages attach under.

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

How many dataset rows at most each connector receives per run.

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

suumo.jp serves its pages to ordinary connections, so the default is the standard Apify proxy with no group and no country pin. A home-country (Japan) residential exit also works and is only worth it if the standard pool is ever degraded.

## Actor input object example

```json
{
  "mode": "search",
  "prefecture": "13",
  "cityCodes": [
    "13101"
  ],
  "layouts": [
    "02"
  ],
  "urls": [
    "https://suumo.jp/jj/chintai/ichiran/FR301FC001/?ar=030&bs=040&ta=13&sc=13101"
  ],
  "fetchDetails": false,
  "maxItems": 20,
  "maxPages": 0,
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "maxNotifyListings": 50,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# 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",
    "prefecture": "13",
    "cityCodes": [
        "13101"
    ],
    "layouts": [
        "02"
    ],
    "urls": [
        "https://suumo.jp/jj/chintai/ichiran/FR301FC001/?ar=030&bs=040&ta=13&sc=13101"
    ],
    "fetchDetails": false,
    "maxItems": 20,
    "maxPages": 0,
    "incrementalMode": false,
    "emitUnchanged": false,
    "emitExpired": false,
    "maxNotifyListings": 50,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("abotapi/suumo-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",
    "prefecture": "13",
    "cityCodes": ["13101"],
    "layouts": ["02"],
    "urls": ["https://suumo.jp/jj/chintai/ichiran/FR301FC001/?ar=030&bs=040&ta=13&sc=13101"],
    "fetchDetails": False,
    "maxItems": 20,
    "maxPages": 0,
    "incrementalMode": False,
    "emitUnchanged": False,
    "emitExpired": False,
    "maxNotifyListings": 50,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("abotapi/suumo-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",
  "prefecture": "13",
  "cityCodes": [
    "13101"
  ],
  "layouts": [
    "02"
  ],
  "urls": [
    "https://suumo.jp/jj/chintai/ichiran/FR301FC001/?ar=030&bs=040&ta=13&sc=13101"
  ],
  "fetchDetails": false,
  "maxItems": 20,
  "maxPages": 0,
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "maxNotifyListings": 50,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call abotapi/suumo-jp-scraper --silent --output-dataset

```

## MCP server setup

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