# SUUMO Rentals - New Listings by Ward (`superslowsloth/suumo-rentals`) Actor

SUUMO rental search, one flat row per room: rent, admin fee, deposit, key money, layout, area, floor, building age and access lines. Search by a pasted SUUMO search URL or by prefecture + city codes, newest-first.

- **URL**: https://apify.com/superslowsloth/suumo-rentals.md
- **Developed by:** [Superslow Sloth](https://apify.com/superslowsloth) (community)
- **Categories:** Real estate, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 listing scrapeds

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/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 Rentals — new listings by ward

Runs a [SUUMO](https://suumo.jp) rental search (`chintai`) and returns one
flat row per **room**, not per building. SUUMO's own results page groups rooms
into "cassettes" - one card per building, with a table of every room
currently available in it - and a building with four vacant rooms produces
four rows here, sharing the building's address, access lines, age and floor
count, and differing in the room-level fields: floor, rent, layout and area.

### Input

Give it either a search URL, or a prefecture code plus one or more ward/city
codes - both can be combined in one run.

| Field | Type | Default | What it does |
|---|---|---|---|
| `searchUrls` | array | — | One or more rental search URLs copied straight from suumo.jp, e.g. `https://suumo.jp/jj/chintai/ichiran/FR301FC001/?ar=030&bs=040&ta=13&sc=13113` (東京都渋谷区, Shibuya). Every filter already on the URL - rent band, layout, "no key money" - survives; only the page number is driven by this actor. Recommended for anywhere outside the Kanto region, since a pasted URL already carries the right region code. |
| `prefectureCode` | string | — | SUUMO's own `ta` code, e.g. `"13"` for Tokyo. |
| `cityCodes` | array | — | SUUMO's own `sc` codes (ward/city), e.g. `"13113"` for Shibuya-ku. One search per code, sharing `prefectureCode` and `areaCode`. |
| `areaCode` | string | `"030"` | SUUMO's own region grouping, the `ar` parameter. `"030"` is Kanto, which covers every prefecture this actor was checked against. A search outside Kanto needs its real code - read one off a URL copied from the site, or use `searchUrls` instead. |
| `sortNewest` | boolean | `true` | Ask SUUMO for its own "新着順" (newest-first) order before paging. Turn off to keep whatever sort a pasted URL already carries. |
| `maxItems` | integer | `100` | Stop after this many rooms across every search in the run. |
| `proxyConfiguration` | object | Apify datacenter | See Proxy below. |

### What one row contains

| Field | Notes |
|---|---|
| `room_id`, `building_id`, `detail_url` | `room_id` is SUUMO's own `bc` query parameter on the detail link - the billing key, unique per room. `building_id` is the `jnc_...` path segment; several rows share it when a building has several vacant rooms. |
| `building_name` | The cassette's title, as SUUMO prints it. On a building SUUMO has no name for, it prints the nearest station, floor count and age instead (e.g. "ＪＲ山手線 原宿駅 10階建 築7年") - that is genuinely what the page shows, not a parsing gap. |
| `building_type` | 賃貸マンション / 賃貸アパート / 賃貸一戸建て, as printed - never translated. |
| `address`, `access` | `access` is a list of `"<line>/<station> 歩<N>分"` strings, one per line SUUMO lists; never padded with blanks. |
| `building_age_years`, `building_age_raw` | `0` for a cassette marked "新築" (brand new) - a real age, not a missing one. |
| `floors_above`, `floors_below`, `floors_raw` | `floors_below` is null for an ordinary "N階建" building, not zero - SUUMO does not print "0 basement floors" at all. |
| `room_floor`, `room_floor_raw` | Negative for a basement level (SUUMO prints "B2階" for the second basement floor). Null when SUUMO prints "-", which it does for a house let as a whole rather than floor by floor. |
| `rent_jpy`, `admin_fee_jpy` | Whole yen. `admin_fee_jpy` is null for SUUMO's "-" (no management fee charged) - never `0`, which would claim SUUMO stated a fee of zero. |
| `deposit_jpy` / `deposit_months` / `deposit_raw`, and the same three for key money | SUUMO usually quotes these in 万円 (man-yen), which lands in the `_jpy` column; it occasionally quotes them as a number of months of rent instead (e.g. "1ヶ月"), which lands in the `_months` column instead. The `_jpy` column is never computed from months - that would be a number SUUMO did not itself print. `_raw` always carries the text as shown. |
| `layout`, `area_m2` | 間取り (e.g. "3LDK", "1K") as printed, and 専有面積 in square metres. |
| `building_image_url`, `room_image_url` | The building's own exterior photo and this room's own photo/floor-plan image - the real URLs, read out of SUUMO's lazy-loading markup rather than the 1x1 placeholder it ships in `src`. |
| `is_new` | True only when SUUMO itself marks the room's checkbox "newarrival". SUUMO prints no listing date at all, so this flag - not date math - is the only "new" signal on the page. |
| `source_url` | The exact search URL this row was read from, filters and all. |

### How it pages and sorts

The search is one server-rendered page,
`/jj/chintai/ichiran/FR301FC001/?ar=<region>&bs=040&ta=<prefecture>&sc=<city>`.
Pagination is the `page` query parameter; newest-first sorting is `po1=09`,
read off the sort dropdown's own `<option value="09">新着順</option>` on the
results page. A pasted search URL keeps every other filter it already carries

- only `page`, and `po1` when newest-first was asked for, are added or
  overwritten.

### Proxy

Apify **datacenter** is the default, and it answered this search with real
results. Residential also works, but **only when pinned to Japan**
(`apifyProxyCountry: "JP"`): an unpinned residential exit gets SUUMO's own
"アクセス集中に関するお詫び" (access congestion apology) page - served on a
plain HTTP 200, indistinguishable from a real 200 by status code alone. This
actor detects that page by its text and treats it as a block, retrying from a
different exit rather than reading it as an empty result.

### Billing

Pay per event, all-in: **$0.00059 per room**, plus a small `actor-start` fee.
Platform usage - compute and proxy - is included in that price; you are not
billed for it on top. That undercuts competitor **solidcode**'s SUUMO actor,
at $0.00084 per result, by about 30%. The run-volume leader in this category,
**jungle\_synthesizer**, charges $0.01 per result.

- `listing-scraped` is charged once per room row, deduplicated globally across
  every search in the run - a room seen on two overlapping searches, or on two
  pages of the same search, is billed once.
- `actor-start` is charged only after your input parses, so a run that fails
  on a typo costs nothing.
- A run stops as soon as it reaches your spending limit rather than continuing
  to work unpaid; everything already pushed and charged stays in the dataset.

# Actor input Schema

## `searchUrls` (type: `array`):

One or more rental search URLs copied straight from suumo.jp, e.g. https://suumo.jp/jj/chintai/ichiran/FR301FC001/?ar=030\&bs=040\&ta=13\&sc=13113 (東京都渋谷区). Every filter already on the URL - rent band, layout, "no key money" - is kept; only the page number is driven by this actor. This is the recommended way to run a search outside the Kanto region, since it carries the correct area code (ar) already.

## `prefectureCode` (type: `string`):

SUUMO's own prefecture code, the `ta` parameter of a search URL - e.g. "13" for Tokyo. Used together with Ward/city codes below to build a search when you have not pasted a URL.

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

SUUMO's own ward/city codes, the `sc` parameter of a search URL - e.g. "13113" for Shibuya-ku. One search is run per code, sharing the prefecture and area codes above.

## `areaCode` (type: `string`):

SUUMO's own region grouping, the `ar` parameter of a search URL. "030" is Kanto and covers every prefecture this actor was measured against; a search outside Kanto needs the real code, read off a URL copied from the site - use Search URLs above instead if you are not sure.

## `sortNewest` (type: `boolean`):

Ask SUUMO for its own "新着順" (newest-first) order before paging through results. On by default, since finding new listings is what this actor is for; turn it off to keep whatever sort a pasted search URL already carries.

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

Stop after this many rooms across all searches in this run. One room is one billed row; a building with several vacant rooms counts as several.

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

Datacenter is the default here: SUUMO answers a datacenter exit with real results. Residential also works, but only when pinned to Japan (apifyProxyCountry "JP") - an unpinned residential exit gets SUUMO's own "access congestion" apology page, served as a plain HTTP 200, which reads exactly like a genuine block.

## Actor input object example

```json
{
  "searchUrls": [
    "https://suumo.jp/jj/chintai/ichiran/FR301FC001/?ar=030&bs=040&ta=13&sc=13113"
  ],
  "areaCode": "030",
  "sortNewest": true,
  "maxItems": 100,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `rooms` (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 = {
    "searchUrls": [
        "https://suumo.jp/jj/chintai/ichiran/FR301FC001/?ar=030&bs=040&ta=13&sc=13113"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("superslowsloth/suumo-rentals").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 = {
    "searchUrls": ["https://suumo.jp/jj/chintai/ichiran/FR301FC001/?ar=030&bs=040&ta=13&sc=13113"],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("superslowsloth/suumo-rentals").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 '{
  "searchUrls": [
    "https://suumo.jp/jj/chintai/ichiran/FR301FC001/?ar=030&bs=040&ta=13&sc=13113"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call superslowsloth/suumo-rentals --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,superslowsloth/suumo-rentals"
        }
    }
}
```

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/55dvkaHpGKw5freT5/builds/An3heyrb6Z5efYWdh/openapi.json