SUUMO Rental Property Scraper (Japan)

Scrapes rental apartments from SUUMO — Japan's #1 property portal (Recruit). Tokyo alone advertises close to 2 million rental listings.

Public data only. No login, no cookies, no browser.

What you get

ROOM — one row per rentable unit

SUUMO nests rooms inside buildings: a listing page shows 30 buildings holding roughly 265 actual units. The unit is the row, because that's what has a price and a URL. Each row carries:

Field	Example
rent	13万円
adminFee	7000円
deposit (敷金)	6.5万円
keyMoney (礼金)	13万円
layout (間取り)	1DK
area	29.4m2
floor	3階
roomUrl	direct SUUMO link

…plus its building nested under building:

"building": {
  "category": "賃貸マンション",
  "name": "マミービル",
  "address": "東京都新宿区高田馬場２",
  "stations": ["ＪＲ山手線/高田馬場駅 歩5分",
               "東京メトロ東西線/高田馬場駅 歩3分",
               "東京メトロ副都心線/西早稲田駅 歩7分"],
  "ageAndStructure": ["築7年", "5階建"]
}

Values are kept exactly as SUUMO renders them — 13万円 stays 13万円. No unit conversion, because guessing wrong between man-yen and yen would corrupt the data silently. Parsing is left to you.

SEARCH_SUMMARY — one row per run

How many ads SUUMO advertises, how many buildings and rooms actually came back, how deep the run paged, and which filters were sent.

Input

Field	What it does
Prefecture	15 verified prefectures — Tokyo, Osaka, Kyoto, Aichi, Fukuoka, Hokkaido…
City / ward codes	optional sc codes, e.g. 13104 Shinjuku, 13113 Shibuya
Min / max rent	in 万円 (man-yen): 8 = ¥80,000/month, 8.5 = ¥85,000
Layout	multi-select: 1R, 1K, 1DK, 1LDK, 2K … 4LDK+
Min / max area	m²
Max walk to station	minutes
Max rooms	0 = unlimited

Example

{
  "prefecture": "tokyo",
  "cityCodes": ["13104"],
  "minRent": "8",
  "maxRent": "15",
  "layouts": ["02", "03"],
  "maxWalkMinutes": 10,
  "maxItems": 500
}

To find a ward code, run the search on suumo.jp and read sc= out of the URL.

What this actor protects you from

SUUMO never returns an error for a bad input — every mistake comes back as a healthy HTTP 200. Four of those were found and are now handled:

1. Integer rent silently returns nothing. cb=8 gives an empty page; cb=8.0 gives 116,149 results. Whatever you type is normalised to the decimal form SUUMO requires — otherwise "8 to 15 man-yen" quietly looks like "no apartments match your budget."
2. A ward code from the wrong prefecture is silently dropped, and SUUMO returns the entire prefecture instead. Because sc values are JIS municipal codes prefixed with the prefecture number, this is checked arithmetically and refused before the run.
3. Region/prefecture code pairs must agree or the page comes back empty. Only pairs verified to return listings are offered.
4. Unknown filters are ignored, not rejected. Every filter here was verified to actually change the result count.

And when page 1 legitimately comes back empty, the run says so explicitly rather than reporting a successful crawl of nothing.

Notes on reliability

• No WAF, no challenge. Plain server-rendered HTML.
• SUUMO does rate-limit, answering bursts with HTTP 503. This actor paces itself instead of racing: concurrency defaults to 2, with a polite delay between pages and a long backoff on 503. Raising concurrency makes runs slower, not faster, once throttling starts.
• Runs unattended. No session, no token, nothing to refresh.
• advertisedHits is not the number of rows you can get. SUUMO counts every agency ad (120,284 for Shinjuku) but collapses duplicates into buildings. Both numbers are reported so the gap is visible.

Scope

Rentals only (chintai). For-sale mansions, houses and land use a different page structure and are deliberately out of scope rather than half-supported.

There is also no detail-fetch toggle — unlike the other property actors here, SUUMO's listing page already carries every field the room detail page repeats, so a detail pass would cost ~9× the requests to re-fetch what you already have.

See CRAWLING_METHOD.md for the full reverse-engineering trail, the region-code sweep and all four trap write-ups.