# SUUMO API (Japan real estate scraper) — rent & buy property listings across all 47 prefectures (Tokyo, Osaka, Kyoto, Fukuoka, Hokkaido…) with filters for price, area, station walk-time and building age, plus full listing detail (rent/deposit/key-money, madori layout, m², floor, orientation, structure, station access and photos) and a prefecture/area code lookup — no API key required

> Search SUUMO property listings in any of Japan's 47 prefectures — rentals or homes for sale (used house / used condo / land / new house) — filtered by max price (万円), min area (m²), max station walk-time, building age and a free-text station/area keyword. Paginate with page + max_pages.
> ReefAPI engine `suumo` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/suumo/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/suumo/v1/search — 1 credit
Search SUUMO property listings in any of Japan's 47 prefectures — rentals or homes for sale (used house / used condo / land / new house) — filtered by max price (万円), min area (m²), max station walk-time, building age and a free-text station/area keyword. Paginate with page + max_pages.

**Parameters:**
- `prefecture` (enum, required) — Prefecture to search — any of Japan's 47 prefectures by romaji slug (tokyo, osaka, kyoto, hokkaido, fukuoka…) or its kanji name (東京都, 大阪府). [one of: hokkaido, aomori, iwate, miyagi, akita, yamagata, fukushima, ibaraki, tochigi, gunma, saitama, chiba, tokyo, kanagawa, niigata, toyama, ishikawa, fukui, yamanashi, nagano, gifu, shizuoka, aichi, mie, shiga, kyoto, osaka, hyogo, nara, wakayama, tottori, shimane, okayama, hiroshima, yamaguchi, tokushima, kagawa, ehime, kochi, fukuoka, saga, nagasaki, kumamoto, oita, miyazaki, kagoshima, okinawa]
- `listing_type` (enum, optional, default "rent") — Transaction & property type. Legacy values sale_used_house / sale_used_condo still work. [one of: rent, buy_house, buy_apartment, buy_land, buy_new_house]
- `page` (integer, optional, default 1) — 1-based results page.
- `max_pages` (integer, optional, default 1) — Fetch and merge this many pages from `page` onward (stops on an empty page). Each page ~30 listings.
- `max_price_man` (number, optional) — Maximum price in 万円 (man-yen, ×10,000 JPY). For rent this is the monthly rent ceiling (e.g. 10 = ¥100,000/mo); for sale the total price ceiling (e.g. 5000 = ¥50,000,000).
- `min_area_m2` (number, optional) — Minimum floor/building area in square metres.
- `max_walk_minutes` (integer, optional) — Maximum walking minutes from the nearest train station.
- `building_age` (integer, optional) — Maximum building age in years (e.g. 10 = built within the last 10 years).
- `keyword` (string, optional) — Free-text filter — a station, line, ward/area or building name (Japanese works best, e.g. 新宿, 山手線, 渋谷区).

**Returns:** items[]{listing_id, url, title_ja, address_ja, price_jpy, price_ja, madori, area_m2 (+land_area_m2/building_area_m2 for sale), station_access[], building_age_years, photos[]} + count + page + pages_fetched + has_next_page

**Example request body:**
```json
{
  "prefecture": "tokyo",
  "listing_type": "rent",
  "max_pages": 1
}
```

### POST https://api.reefapi.com/suumo/v1/detail — 1 credit
Full detail for one SUUMO listing — rent/deposit/key-money or sale price, madori layout, floor area, floor, orientation, building structure & age, station access and the photo gallery. For RENT pass listing_id; for SALE pass the listing's `url` from a search result (SUUMO sale pages have no id-only URL). listing_type picks the right parser.

**Parameters:**
- `listing_id` (string, optional) — SUUMO RENT listing id — the digits in a jnc_<id> URL, or a rent search result's listing_id. (For SALE listings pass `url` from the search result instead, since SUUMO sale pages have no id-only URL.)
- `url` (string, optional) — Full SUUMO listing URL (copy the `url` from a search result). REQUIRED for sale listings; optional for rent (listing_id works too).
- `listing_type` (enum, optional, default "rent") — Transaction & property type. Legacy values sale_used_house / sale_used_condo still work. [one of: rent, buy_house, buy_apartment, buy_land, buy_new_house]

**Returns:** listing{} — full record (fields vary by rent vs sale; price_jpy, deposit_jpy, key_money_jpy, madori, area_m2, floor_ja, orientation_ja, structure_ja, building_age_years, station_access[], photos[])

**Example request body:**
```json
{
  "listing_id": "000109252250"
}
```

### POST https://api.reefapi.com/suumo/v1/areas — 1 credit
List Japan's 47 prefectures with their romaji slug, kanji name and SUUMO region/JIS codes — use it to discover or validate the `prefecture` value before searching. Pass an optional query to filter by name.

**Parameters:**
- `query` (string, optional) — Optional filter — match a prefecture by romaji or kanji name substring (e.g. 'osa' → osaka, '東京' → tokyo).

**Returns:** prefectures[]{slug, name_ja, ar, ta} + count

**Example request body:**
```json
{
  "query": "osa"
}
```

### POST https://api.reefapi.com/suumo/v1/listings/search — 1 credit
Legacy name for `search`, kept so older integrations keep working. It runs the exact same code and returns the exact same body (verified byte-for-byte, 2026-08-28). New code should call `search`.

**Parameters:**
- `prefecture` (enum, required) — Prefecture to search — any of Japan's 47 prefectures by romaji slug (tokyo, osaka, kyoto, hokkaido, fukuoka…) or its kanji name (東京都, 大阪府). [one of: hokkaido, aomori, iwate, miyagi, akita, yamagata, fukushima, ibaraki, tochigi, gunma, saitama, chiba, tokyo, kanagawa, niigata, toyama, ishikawa, fukui, yamanashi, nagano, gifu, shizuoka, aichi, mie, shiga, kyoto, osaka, hyogo, nara, wakayama, tottori, shimane, okayama, hiroshima, yamaguchi, tokushima, kagawa, ehime, kochi, fukuoka, saga, nagasaki, kumamoto, oita, miyazaki, kagoshima, okinawa]
- `listing_type` (enum, optional, default "rent") — Transaction & property type. Legacy values sale_used_house / sale_used_condo still work. [one of: rent, buy_house, buy_apartment, buy_land, buy_new_house]
- `page` (integer, optional, default 1) — 1-based results page.
- `max_pages` (integer, optional, default 1) — Fetch and merge this many pages from `page` onward (stops on an empty page). Each page ~30 listings.
- `max_price_man` (number, optional) — Maximum price in 万円 (man-yen, ×10,000 JPY). For rent this is the monthly rent ceiling (e.g. 10 = ¥100,000/mo); for sale the total price ceiling (e.g. 5000 = ¥50,000,000).
- `min_area_m2` (number, optional) — Minimum floor/building area in square metres.
- `max_walk_minutes` (integer, optional) — Maximum walking minutes from the nearest train station.
- `building_age` (integer, optional) — Maximum building age in years (e.g. 10 = built within the last 10 years).
- `keyword` (string, optional) — Free-text filter — a station, line, ward/area or building name (Japanese works best, e.g. 新宿, 山手線, 渋谷区).

**Returns:** See `search`.

**Example request body:**
```json
{
  "prefecture": "tokyo"
}
```

### POST https://api.reefapi.com/suumo/v1/listings/detail — 1 credit
Legacy name for `detail`, kept so older integrations keep working. It runs the exact same code and returns the exact same body. New code should call `detail`.

**Parameters:**
- `listing_id` (string, optional) — SUUMO RENT listing id — the digits in a jnc_<id> URL, or a rent search result's listing_id. (For SALE listings pass `url` from the search result instead, since SUUMO sale pages have no id-only URL.)
- `url` (string, optional) — Full SUUMO listing URL (copy the `url` from a search result). REQUIRED for sale listings; optional for rent (listing_id works too).
- `listing_type` (enum, optional, default "rent") — Transaction & property type. Legacy values sale_used_house / sale_used_condo still work. [one of: rent, buy_house, buy_apartment, buy_land, buy_new_house]

**Returns:** See `detail`.

**Example request body:**
```json
{
  "url": "https://suumo.jp/chukoikkodate/tokyo/sc_hachioji/nc_20015074/"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=suumo
- Human docs page: https://reefapi.com/docs/suumo
- Overview page: https://reefapi.com/suumo-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
