# Japan Residential Rental Listings Bulk — SUUMO & Yahoo (`jpmarketdata/japan-residential-rental-listings-bulk`) Actor

Export paginated Japan residential rental rooms by city from SUUMO and Yahoo! Real Estate with normalized yen rent, fees, area, floor plan, use-case tags, per-source status and resume cursors. Bounded partial coverage.

- **URL**: https://apify.com/jpmarketdata/japan-residential-rental-listings-bulk.md
- **Developed by:** [h ichi](https://apify.com/jpmarketdata) (community)
- **Categories:** Real estate, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 residential rental listing exporteds

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

## Japan Residential Rental Listings Bulk

Export public residential rental rooms from SUUMO and Yahoo! Real Estate in bounded city batches. Sources are independently selectable and have separate parsers, IDs, status, and resume cursors. Two portals are not an all-site or complete nationwide snapshot.

### Input

Provide one five-digit JIS municipality `cityCode` (for example `13113` for Shibuya-ku) and `sources` (`suumo`, `yahoo-realestate`, or both). Each source has its own `StartPage` and `StartRoomOffset` fields for resumption. `maxPagesPerSource` is 1-25 (default 5), `maxItems` is 1-4000 (default 500) across selected sources, and `useCase` is `all`, `solo`, `couple`, or `family`. Solo means a 1R/1K/1DK plan, couple means a 1LDK/2K/2DK plan with at least 30 m2, and family means 2LDK or 3K+ with at least 45 m2; these are sorting heuristics. Optional `maxMonthlyJpy` filters known rent plus management fee. `maxDetailPagesPerSource` (0-15, default 0) limits extra public detail checks on each selected source.

### Output

A `listing` row contains one unique source-prefixed rental-room ID, normalized yen rent and known fees, plan, square meters, area, source URL, heuristic use-case tags, page position and fetched-at time. Each selected source gets an uncharged `source_status` checkpoint before listing export (`statusPhase=checkpoint`), then a final status after its listing batches succeed (`statusPhase=final`). The checkpoint has `itemsEmitted=0` and the requested start page/room offset as its conservative resume cursor. If export stops before the final status, resume from that checkpoint and deduplicate any replayed rows by `sourceListingId`. Final status records `ok`, `partial`, or `failed`, actual exported count, the collection-end cursor, fetched page count, source hit count, truncation reason, and a controlled error code/message if needed. `sourceTotalFound` is each site's claim, never the number exported; it is omitted if the source count was not observed. Final `truncatedBy` is `item-limit`, `page-limit`, `time-limit`, `source-end`, or `source-error`; checkpoints use `publish-in-progress`. `nextPage=0` means the source has no proven next page. Results can shift between runs; deduplicate by the full source-prefixed `sourceListingId`. Do not merge a possible cross-portal duplicate by address or price. Missing fees or deposits remain absent, not zero. Foreign-national consultation wording is only evidence that inquiry may be possible: `foreignerAcceptanceStatus` is always `unverified`, including where the source says `外国人相談可`.

Optional detail checks require the requested room’s canonical URL and source-specific detail markup. A blocked, stale, wrong-room, or incomplete detail remains `not-checked` with no evidence code and a `partial` source status carrying the error. Validated list rows remain exportable; detail checks never incur a separate charge. HTTP 200 block/verification pages are reported as `auth-block`, while missing room identity or markup is `structure-change`.

### Pricing

Provisional PPE hypothesis, requiring owner confirmation before publication: $0.001 per unique, validated listing row successfully exported as `rental-listing-scraped`; source-status rows, page requests and optional detail checks have no event. A partial run charges only emitted listing rows. Empty runs fail without a listing charge; a source failure is explicit even when another source returns usable rows.

### Limits

At most 25 sequential list pages and 15 optional room details per selected source plus one cached robots.txt request per selected host (82 requests total), 4,000 unique rows, 5 MiB per response, 30 seconds per request and 300 seconds per run. Collection stops starting requests after about 120 seconds; one final request may use another 30 seconds, reserving about 150 seconds for batched dataset export and final statuses. Requests to the same host are spaced at least 1.5 seconds apart. SUUMO newest-first and Yahoo site-default ordering can shift or favor some listings; partial extraction is labelled and is not a representative city-wide sample. Current robots rules are retrieved once per selected host and checked before each list/detail request, including wildcard and end-anchored restrictions; unverified rules fail closed. Redirects are rejected. No login, proxy, browser or paid external API is used.

### Privacy

Only public property facts and controlled consultation-evidence codes are output. Broker or tenant names, phone numbers, email addresses, reviews, inquiry content, descriptive prose, photos and precise coordinates are excluded. Details are never interpreted as a binding acceptance decision. SUUMO, Recruit, Yahoo and LY Corporation do not endorse this product.

# Actor input Schema

## `cityCode` (type: `string`):

One five-digit Japanese municipality code, e.g. 13113 for Tokyo Shibuya-ku. One city per run makes the resume cursor unambiguous.

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

Hard cap on validated unique room rows emitted in this run; at most 4,000.

## `useCase` (type: `string`):

all, solo, couple or family. Tags are plan-and-area heuristics, not tenant suitability or acceptance guarantees.

## `maxMonthlyJpy` (type: `integer`):

Optional rent plus known management fee ceiling; omit to collect all prices. Rows with unknown fee cannot be asserted below this ceiling and are excluded when set.

## `sources` (type: `array`):

Select suumo, yahoo-realestate, or both independent public rental portals; source-specific errors and resume cursors are reported separately.

## `suumoStartPage` (type: `integer`):

First page for this source; use the prior source-status nextPage to resume. Newest/default order can drift between runs.

## `suumoStartRoomOffset` (type: `integer`):

Zero-based room index on this source start page; use source-status nextRoomOffset to resume a page cut by maxItems.

## `yahooStartPage` (type: `integer`):

First page for this source; use the prior source-status nextPage to resume. Newest/default order can drift between runs.

## `yahooStartRoomOffset` (type: `integer`):

Zero-based room index on this source start page; use source-status nextRoomOffset to resume a page cut by maxItems.

## `maxPagesPerSource` (type: `integer`):

Read at most 1-25 sequential list pages per selected portal in this run.

## `maxDetailPagesPerSource` (type: `integer`):

Optional 0-15 extra public room details per selected portal for controlled foreign-national consultation evidence; consultation is not acceptance.

## Actor input object example

```json
{
  "cityCode": "13113",
  "maxItems": 500,
  "useCase": "all",
  "sources": [
    "suumo",
    "yahoo-realestate"
  ],
  "suumoStartPage": 1,
  "suumoStartRoomOffset": 0,
  "yahooStartPage": 1,
  "yahooStartRoomOffset": 0,
  "maxPagesPerSource": 5,
  "maxDetailPagesPerSource": 0
}
```

# Actor output Schema

## `listings` (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 = {
    "cityCode": "13113",
    "sources": [
        "suumo",
        "yahoo-realestate"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpmarketdata/japan-residential-rental-listings-bulk").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 = {
    "cityCode": "13113",
    "sources": [
        "suumo",
        "yahoo-realestate",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("jpmarketdata/japan-residential-rental-listings-bulk").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 '{
  "cityCode": "13113",
  "sources": [
    "suumo",
    "yahoo-realestate"
  ]
}' |
apify call jpmarketdata/japan-residential-rental-listings-bulk --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jpmarketdata/japan-residential-rental-listings-bulk"
        }
    }
}
```

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/Yv28nBO9Mm9KHcgzr/builds/upim7Mwdc8aOc7vVX/openapi.json