# Japan Real Estate API (SUUMO 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 `japan-re` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/japan-re/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 or blocked 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, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /japan-re/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 /japan-re/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[])

### POST /japan-re/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

### POST /japan-re/v1/listings/search — 2 credits
Alias of `search` (legacy name). Prefer `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 /japan-re/v1/listings/detail — 2 credits
Alias of `detail` (legacy name). Prefer `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`.

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