SUUMO Japan Property Listings Scraper

Slug: fatihtahta/suumo-japan-scraper

Overview

SUUMO Japan Property Listings Scraper collects structured public rental and for-sale property listings, including listing identity, asking prices, addresses, transport access, floor plans, floor area, building details, availability, media, fees, and public relationship or contact information when available. SUUMO is a major Japanese property marketplace whose public listings are useful for housing research, inventory monitoring, comparable-listing analysis, and operational property-data workflows. The Actor supports guided searches across Japanese prefectures and selected major cities, independent SUUMO result or listing URLs, and optional detail enrichment. It turns repeatable search configurations into consistent, grouped JSON records instead of requiring manual browsing and copy-paste work. Results are delivered as structured Apify dataset records suitable for review, export, ETL pipelines, BI dashboards, AI-agent workflows, search indexes, and downstream APIs. The Actor is designed for recurring public-data acquisition while keeping source-dependent fields optional and preserving the displayed values needed for audit and analysis.

What Makes This Actor Different

• Guided Japanese market selection: build a search from a supported prefecture or major city, select rental or purchase categories, and apply price, layout, area, station-distance, building-age, recency, and keyword filters without constructing a URL manually.
• Independent URL collection: add SUUMO search, category, ward, or direct listing URLs as separate seeds. Structured query fields create an additional search and do not rewrite supplied URLs.
• Pipeline-ready property records: one documented property_listing family groups identity, source context, listing terms, pricing, location, property facts, availability, media, contacts, relationships, and additional attributes under stable names.
• Stable identity and provenance: record_id, listing.listing_id, source identifiers, public URLs, source_context.source_url, and source_context.scraped_at support deduplication, repeatable refreshes, audits, and upserts.
• Consistent lightweight and enriched shapes: source_context.enrichment_status distinguishes standard result-page records from records with useful individual-listing details while retaining the same public envelope.
• Operational run receipts: RUN-SUMMARY and RUN-SUMMARY.html report saved counts, duplicates, filters, price and field coverage, enrichment outcomes, representative listings, warnings, stop reason, and artifact references.
• Agent-ready handoff: optional Apify MCP connectors can receive a concise post-run summary after the dataset and reports are saved. The full property dataset remains in Apify and is not sent through MCP by default.
• Evidence-backed validation: recent saved validation runs covered standard regional purchase searches, a keyword-filtered search, and an enriched direct rental listing; measured examples appear in the performance section.

Who Should Use This Actor

• Real estate investors and analysts: assemble public comparable-listing sets by geography, category, asking price, layout, area, or building age for independent research.
• Brokerages and property operations teams: monitor visible rental or sale inventory, review listing terms, and prepare structured internal work queues.
• Market research and analytics teams: create repeatable market snapshots for asking-price, property-mix, availability, and location analysis.
• Proptech and data engineering teams: feed normalized listing records into warehouses, catalogs, search products, BI models, and enrichment pipelines.
• AI agents and workflow automations: generate a scoped input, collect listings, read a run receipt, and route qualified records to the next automated or human-review step.
• Lead generation and enrichment teams: collect public listing, agency, representative, inquiry, and property attributes when SUUMO exposes them.
• Monitoring and reporting teams: schedule consistent searches and compare stable identifiers and point-in-time fields across runs.

Common Use Cases

• Market intelligence: monitor public supply, asking prices, floor plans, floor area, building age, and property categories within a selected Japanese market.
• Comparable-listing research: collect listings within a defined location, transaction category, price band, layout, or size range.
• Rental inventory review: examine advertised rent terms, deposits, key money, fees, contract terms, move-in timing, and public inquiry details when available.
• Competitive monitoring: compare visible property presentation, pricing, availability, agency relationships, and listing copy across recurring snapshots.
• Catalog and directory building: populate internal property and listing indexes with source identifiers, public URLs, addresses, media, and structured attributes.
• Data enrichment: attach current public listing details to CRM, BI, research, or property-operation records using stable identifiers and URLs.
• Recurring reporting: schedule consistent segments for inventory snapshots, new-listing review, price-change analysis, and dashboard refreshes.
• Agentic property research: let an internal agent collect a bounded dataset, validate the run summary, identify records for follow-up, and hand the result to analysts.

Real-World Questions This Data Can Answer

• Which public listings match a prefecture or major city, rental or purchase category, price band, layout, size range, station-distance preference, or keyword?
• What asking-price and property-type mix is visible in a selected market segment at run time?
• Which saved records include numeric price, media, availability, agency, or public contact coverage?
• Which listings appear new, removed, repriced, or updated when stable identifiers are compared with a previous internal snapshot?
• Which properties advertise particular floor plans, floor areas, building ages, transport access, or move-in conditions?
• Which listing records contain enough structured detail for enrichment, analyst review, or downstream monitoring?
• Did a run complete with the expected listing count, enrichment state, price coverage, and duplicate outcome?

Quick Start

1. Select one supported Japanese prefecture or major city, add one or more SUUMO URLs, or use both input modes together.
2. Choose the rental or purchase categories and add only the filters needed for the target segment.
3. Set limit to 10 or 25 for the first validation run and choose whether to enable enrich_data.
4. Start the Actor in Apify Console and inspect the first dataset records.
5. Review RUN-SUMMARY or RUN-SUMMARY.html, then increase the limit or schedule the validated configuration.

Input Parameters

The Actor accepts a guided regional query, independent SUUMO URLs, optional detail enrichment, a run-wide result limit, and optional MCP summary delivery.

Parameter	Type	Description	Default
location_region	string	One supported Japanese prefecture or major city for the generated search. Select a major-city value when city scope is preferred over the wider prefecture.	–
deal_type	array of strings	Rental or purchase categories: rent_all, rent_mansion, rent_apartment, rent_house, buy_all, new_condo, used_condo, new_house, used_house, or land. Selecting an *_all value makes its corresponding subtype selections redundant.	["rent_all"]
min_price	integer	Inclusive lower price in JPY, using 5,000 JPY increments. It represents monthly rent for rental categories and asking price for purchase categories.	–
max_price	integer	Exclusive upper price in JPY, using 5,000 JPY increments.	–
floor_plan	array of strings	Layout groups: studio, 1k_1dk_1ldk, 2k_2dk_2ldk, 3k_3dk_3ldk, 4k_4dk_4ldk, or 5k_or_more. Ignored for land-only searches.	–
min_area	integer	Inclusive minimum floor or land area in square metres.	–
max_area	integer	Exclusive maximum floor or land area in square metres.	–
max_distance_from_station	string	Maximum advertised walking time: within_1_minute, within_3_minutes, within_5_minutes, within_7_minutes, within_10_minutes, or within_15_minutes.	–
building_age	string	new or a maximum age: within_1_year, within_3_years, within_5_years, within_7_years, within_10_years, within_15_years, within_20_years, or within_25_years. Ignored for land-only searches.	–
newly_published	boolean	Restrict the generated search to listings SUUMO marks as newly published.	false
keyword	string	Optional Japanese keyword or short phrase, up to 100 characters, applied to the generated search.	–
startUrls	array of strings	Independent public SUUMO search, category, borough, or direct listing URLs. Query-builder fields do not modify them.	–
enrich_data	boolean	Visit individual listing pages for additional public fees, terms, property facts, availability, media, relationships, and contact fields when available.	true
limit	integer	Maximum listing records to save across the run. Minimum: 10.	50000
mcpConnectors	array of strings	Optional compatible connectors authorized in Apify for post-run summary delivery. The full listing dataset is not sent through MCP.	[]

Supported location_region Values

The Apify input form displays Japanese location names. JSON and API inputs use the corresponding value below.

Market	Value	Market	Value
北海道	hokkaido_	札幌市	hokkaido_/sa_sapporo
青森県	aomori	岩手県	iwate
秋田県	akita	宮城県	miyagi
仙台市	miyagi/sa_sendai	山形県	yamagata
福島県	fukushima	東京都	tokyo
神奈川県	kanagawa	川崎市	kanagawa/sa_kawasaki
横浜市	kanagawa/sa_yokohama	相模原市	kanagawa/sa_sagamihara
千葉県	chiba	千葉市	chiba/sa_chiba
埼玉県	saitama	さいたま市	saitama/sa_saitama
茨城県	ibaraki	栃木県	tochigi
群馬県	gumma	山梨県	yamanashi
長野県	nagano	石川県	ishikawa
新潟県	niigata	新潟市	niigata/sa_niigata
富山県	toyama	福井県	fukui
愛知県	aichi	名古屋市	aichi/sa_nagoya
静岡県	shizuoka	静岡市	shizuoka/sa_shizuoka
浜松市	shizuoka/sa_hamamatsu	岐阜県	gifu
三重県	mie	大阪府	osaka
大阪市	osaka/sa_osaka	堺市	osaka/sa_sakai
兵庫県	hyogo	神戸市	hyogo/sa_kobe
京都府	kyoto	京都市	kyoto/sa_kyoto
滋賀県	shiga	奈良県	nara
和歌山県	wakayama	愛媛県	ehime
香川県	kagawa	高知県	kochi
徳島県	tokushima	岡山県	okayama
岡山市	okayama/sa_okayama	広島県	hiroshima
広島市	hiroshima/sa_hiroshima	島根県	shimane
鳥取県	tottori	山口県	yamaguchi
福岡県	fukuoka	福岡市	fukuoka/sa_fukuoka
北九州市	fukuoka/sa_kitakyushu	佐賀県	saga
長崎県	nagasaki	熊本県	kumamoto
熊本市	kumamoto/sa_kumamoto	大分県	oita
宮崎県	miyazaki	鹿児島県	kagoshima
沖縄県	okinawa

Choosing Inputs

Use location_region when you want the Actor to create a repeatable market search from structured fields. Pair it with deal_type; then add price, floor-plan, area, station-distance, building-age, publication-recency, or keyword filters only when they represent a real analytical boundary. Narrow filters produce more targeted datasets, while leaving optional filters empty improves discovery inside the chosen market and category.

Use startUrls when you already have a public SUUMO result page, category page, borough page, or direct property URL. Each URL remains an independent seed. You can combine URL seeds with a generated regional query in one run, but separate runs by city, category, or price segment are often easier to compare downstream.

Keep enrich_data enabled when fees, contract terms, availability, richer property facts, individual-page media, relationships, or inquiry fields matter. Turn it off for faster validation or when standard result-page identity, asking price, address, layout, area, and thumbnail data are sufficient.

Start with limit set to 10 or 25. Increase it only after reviewing the first rows and the run summary. The maximum applies across the run rather than acting as a promise that the selected market contains that many matching public listings.

Input Recipes

• Validation run: choose one prefecture or major city, one deal category, no optional filters, limit of 10, and enrich_data disabled. Confirm identity, pricing, location, and property fields before scaling.
• Targeted purchase search: use location_region, one or more purchase categories, a JPY price range, floor-plan groups, area bounds, station distance, and building age to create a comparable segment.
• Transit-focused rental search: select rent_all or rental subtypes, set a maximum station walking time, optionally add a keyword such as ペット可, and keep enrichment enabled for rental terms and move-in details.
• Direct listing enrichment: provide known property URLs through startUrls, enable enrich_data, and use a conservative limit. Match returned record_id, source identifiers, and URL against the internal record.
• New-listing monitoring: save one stable location/category/filter configuration with newly_published enabled, run it on a schedule, and compare stable identifiers with the previous snapshot.
• Segmented market analysis: run cities, transaction categories, or price bands separately and retain the input segment with each exported dataset for cleaner comparisons.

Example Inputs

Targeted Tokyo Purchase Search

{
    "location_region": "tokyo",
    "deal_type": ["new_condo", "used_condo"],
    "min_price": 50000000,
    "max_price": 120000000,
    "floor_plan": ["2k_2dk_2ldk", "3k_3dk_3ldk"],
    "limit": 25,
    "enrich_data": false
}

Recently Published Osaka Rentals

{
    "location_region": "osaka/sa_osaka",
    "deal_type": ["rent_all"],
    "max_distance_from_station": "within_10_minutes",
    "newly_published": true,
    "keyword": "ペット可",
    "limit": 25,
    "enrich_data": true
}

Direct Listing Enrichment

{
    "startUrls": ["https://suumo.jp/chintai/jnc_000107533873/?bc=100509695377"],
    "limit": 10,
    "enrich_data": true
}

Output

Output Destination

The actor writes results to an Apify dataset as JSON records. The dataset is designed for direct consumption by analytics tools, ETL pipelines, AI agents, and downstream APIs with minimal post-processing.

The current public contract contains one record family, property_listing. Lightweight and enriched records share the same envelope; optional nested fields appear only when the selected page and listing expose them.

Record Envelope And Stable Identifiers

Every record uses record_type = "property_listing". The recommended idempotency key is record_id, which uses the strongest available SUUMO unit or building identifier and falls back to the public listing URL when a stronger source identifier is unavailable. listing.listing_id, property.property_id, entity.external_ids, and url provide additional join and reconciliation options.

Use record_id for routine deduplication and upserts. If a workflow mixes records from multiple sources, use a composite such as source_context.source_domain + record_id. Stable identifiers make repeated records easier to merge, deduplicate, sync, and compare, while source_context.source_url and source_context.scraped_at preserve discovery provenance and collection time.

Example: Property Listing Record

This synthetic example follows the saved public structure and uses sample-safe values.

{
    "record_type": "property_listing",
    "record_id": "sample-building-101",
    "url": "https://suumo.jp/example-listing/",
    "source_context": {
        "source_name": "SUUMO",
        "source_domain": "suumo.jp",
        "source_url": "https://suumo.jp/chintai/tokyo/",
        "scraped_at": "2026-07-24T12:00:00.000Z",
        "language": "ja",
        "country": "JP",
        "position": 1,
        "enrichment_status": "enriched"
    },
    "entity": {
        "title": "サンプルレジデンス 101号室",
        "name": "サンプルレジデンス",
        "description": "駅徒歩圏内の1LDKサンプル物件",
        "url": "https://suumo.jp/example-listing/",
        "external_ids": {
            "building_id": "sample-building",
            "unit_id": "sample-building-101",
            "suumo_property_code": "100000000000"
        }
    },
    "listing": {
        "listing_id": "sample-building-101",
        "listing_type": "rental",
        "deal_type": "rent_mansion",
        "source_category": "賃貸マンション",
        "transaction_type": "仲介",
        "contract_term": "普通借家 2年",
        "updated_at": "2026/07/24",
        "next_update_due": "2026/08/01"
    },
    "pricing": {
        "price": 145000,
        "price_text": "14.5万円",
        "currency": "JPY",
        "rent": "14.5万円",
        "management_fee": "8000円",
        "deposit": "14.5万円",
        "key_money": "14.5万円",
        "brokerage_fee": "1.1ヶ月",
        "insurance": "2万円2年"
    },
    "location": {
        "address": "東京都サンプル区一丁目",
        "country": "Japan",
        "country_code": "JP",
        "transport_access": ["東京メトロサンプル線/サンプル駅", "徒歩6分"],
        "transport_text": "東京メトロサンプル線「サンプル」歩6分"
    },
    "property": {
        "property_id": "sample-building-101",
        "building_id": "sample-building",
        "unit_id": "sample-building-101",
        "name": "サンプルレジデンス",
        "property_type": "賃貸マンション",
        "floor": "1階/5階建",
        "floor_plan": "1LDK",
        "floor_plan_details": "洋6 LDK10",
        "floor_area": 42.5,
        "floor_area_text": "42.50m²",
        "area_unit": "m²",
        "year_built": 2021,
        "built_text": "2021年9月",
        "structure": "鉄筋コン",
        "orientation": "南"
    },
    "availability": {
        "available_from_text": "即入居可"
    },
    "media": {
        "main_image_url": "https://img01.suumo.com/sample/property-main.jpg",
        "image_urls": [
            "https://img01.suumo.com/sample/property-main.jpg",
            "https://img01.suumo.com/sample/property-room.jpg"
        ]
    },
    "attributes": {
        "tags": ["ペット相談", "角住戸"],
        "detail_title": "サンプルレジデンス 101号室"
    }
}

Run Summary, Report, And Artifacts

The default dataset is the primary output. The default key-value store also contains:

• RUN-SUMMARY: machine-readable JSON with timestamps, status, input scope, saved and enriched counts, duplicate count, completed chunks, listing/property/currency/country breakdowns, field coverage, numeric price range, enrichment outcomes, representative listings, warnings, stop reason, and artifact keys.
• RUN-SUMMARY.html: a self-contained human-readable report presenting the same operational information as KPI cards and tables.
• RUN-SUMMARY-ERROR: a best-effort diagnostic written only when the summary itself cannot be completed; already-saved dataset records remain the primary result.

Property teams can use these artifacts to confirm whether the expected segment ran, review saved and enriched totals, inspect price and field coverage, and identify warnings without opening every listing. Data teams and AI agents can treat the summary as a run receipt for recurring comparisons, alert routing, import approval, and retry decisions.

This Actor does not currently publish an interactive map because the public record contract does not expose stable latitude and longitude fields. The HTML artifact is a run report, not a geographic map.

Field Reference

Only record_type, source_context, and entity are required at the top level. Source-context fields marked required are required inside source_context; all other fields are optional because availability varies by listing family, page, region, and enrichment outcome.

Record Identity

• record_type (string, required): stable record-family discriminator; currently property_listing.
• record_id (string, optional): strongest available listing, unit, building, or URL-based identifier; recommended upsert key.
• url (string, optional): primary public SUUMO listing URL and fallback URL-level join key.

Source Context

• source_context (object, required): collection provenance and enrichment state.
• source_context.source_name (string, required): source marketplace name.
• source_context.source_domain (string, required): normalized source domain.
• source_context.source_url (string, optional): public search, category, region, or direct page that produced the record.
• source_context.scraped_at (string, required): collection timestamp.
• source_context.language (string, required): source-text language code, normally ja.
• source_context.country (string, required): source country code, normally JP.
• source_context.position (integer, required): one-based source position within the processed page or batch.
• source_context.enrichment_status (string, required): lightweight or enriched.

Entity

• entity (object, required): human-readable identity and source identifiers.
• entity.title / entity.name (string, optional): display title and property or building name.
• entity.description (string, optional): public source-provided listing summary.
• entity.url (string, optional): public URL associated with the entity.
• entity.external_ids (object, optional): source identifiers retained as strings.
• entity.external_ids.building_id (string, optional): SUUMO building or project identifier.
• entity.external_ids.unit_id (string, optional): unit-level identifier.
• entity.external_ids.suumo_property_code (string, optional): public property code exposed on some rental listings.

Listing

• listing (object, optional): classification, transaction terms, unit count, and source dates.
• listing.listing_id (string, optional): listing-level identifier aligned with record_id when available.
• listing.listing_type (string, optional): broad transaction family: rental or sale.
• listing.deal_type (string, optional): normalized search category.
• listing.transaction_type (string, optional): source-provided transaction or brokerage role.
• listing.source_category (string, optional): original Japanese category label.
• listing.units_available (integer, optional): unambiguous displayed available-unit count.
• listing.contract_term (string, optional): displayed rental contract term.
• listing.information_provided_at (string, optional): source-provided information date.
• listing.updated_at (string, optional): displayed update date; format can vary by listing family.
• listing.next_update_due (string, optional): displayed expected next-update date.

Pricing

• pricing (object, optional): advertised prices, rents, and public fee terms; values are not valuations or completed transaction prices.
• pricing.price (number, optional): normalized numeric JPY asking price or monthly rent.
• pricing.price_text (string, optional): exact displayed price text.
• pricing.currency (string, optional): currency code for numeric price values.
• pricing.rent / pricing.sale_price (string, optional): displayed rent or asking-price text.
• pricing.monthly_payment (string, optional): illustrative monthly payment shown by SUUMO.
• pricing.management_fee (string, optional): recurring management or common-area fee.
• pricing.deposit / pricing.key_money (string, optional): displayed rental deposit and key-money terms.
• pricing.maintenance_reserve (string, optional): displayed repair or maintenance reserve.
• pricing.other_fees / pricing.initial_costs (string, optional): additional fee and move-in cost text.
• pricing.brokerage_fee (string, optional): public brokerage commission terms.
• pricing.guarantee (string, optional): guarantee-company requirements or fees.
• pricing.insurance (string, optional): insurance requirement or cost.

Location

• location (object, optional): displayed address and public transport context.
• location.address (string, optional): Japanese address text, which may omit unit-level detail.
• location.country / location.country_code (string, optional): country name and normalized code.
• location.transport_access (array of strings, optional): ordered rail, station, bus, and advertised walking-time snippets.
• location.transport_text (string, optional): richer transport description.
• location.nearby_information (string, optional): public neighborhood, amenity, or nearby-place summary.

Property

• property (object, optional): physical and classification details for the advertised home, building, or land.
• property.property_id / property.building_id / property.unit_id (string, optional): property, building, and unit identifiers.
• property.name / property.building_name (string, optional): source-provided property and development names.
• property.property_type (string, optional): original or normalized housing or land category.
• property.floor (string, optional): unit-floor and building-floor context.
• property.floor_plan (string, optional): Japanese floor-plan label.
• property.floor_plan_details (string, optional): room-level layout description.
• property.floor_area (number, optional): numeric area in square metres.
• property.floor_area_text (string, optional): exact area text, including supplementary units or notes.
• property.area_unit (string, optional): normalized area unit.
• property.year_built (integer, optional): parsed four-digit construction or completion year.
• property.built_text (string, optional): exact construction, completion, or handover text.
• property.building_details (array of strings, optional): building age, structure, or floor-count snippets.
• property.total_units (integer, optional): displayed total units.
• property.additional_area (string, optional): balcony, land, or secondary area text.
• property.structure (string, optional): structure and floor-count text.
• property.orientation (string, optional): advertised facing direction.
• property.tenure (string, optional): land-right or tenure description.
• property.zoning (string, optional): Japanese land-use zoning.
• property.parking (string, optional): parking availability and displayed cost.
• property.conditions (string, optional): occupancy, rental, or other public conditions.

Availability

• availability (object, optional): move-in, handover, and viewing information.
• availability.available_from_text (string, optional): source-provided move-in or handover timing.
• availability.viewing_information (string, optional): public viewing, open-house, or reservation guidance.

Media

• media (object, optional): deduplicated absolute public image URLs.
• media.main_image_url (string, optional): first captured image URL.
• media.image_urls (array of strings, optional): property photos and, on some enriched pages, supporting page imagery. Consumers requiring a property-only gallery should apply their own image selection rules.

Contact Details

• contact_details (object, optional): public inquiry information shown on individual listing pages.
• contact_details.phones (array of strings, optional): normalized public phone numbers.
• contact_details.inquiry_text (string, optional): concise public inquiry wording.
• contact_details.inquiry_details (string, optional): expanded contact, license, transaction-role, hours, or closing-day text.
• contact_details.related_links_text (string, optional): descriptions of related public company or property resources.

Relationships

• relationships (object, optional): agency, representative, and builder information nested within the listing record.
• relationships.agency.name (string, optional): public agency name.
• relationships.agency.overview (string, optional): public company or licensing summary.
• relationships.agent.description (string, optional): public representative commentary.
• relationships.builder.name (string, optional): source-provided builder name.

Additional Attributes

• attributes (object, optional): useful public listing fields without a stronger canonical group.
• attributes.tags (array of strings, optional): ordered feature, status, or selling-point labels.
• attributes.detail_title (string, optional): expanded listing-page title.
• attributes.meta_description (string, optional): public page description retained for text search and review.
• attributes.restrictions (string, optional): material source-provided restrictions.
• attributes.notes (string, optional): additional public notes or provisions.
• attributes.source_details (object, optional): uncommon public source fields retained under their original labels.

Data Model Notes

• Identity fields: use record_id for standard upserts; retain url and entity.external_ids for reconciliation and fallback matching.
• Source and provenance: use source_context.source_url to trace discovery scope and source_context.scraped_at to timestamp the snapshot.
• Property and listing attributes: listing, pricing, location, property, and availability contain the main business values for analysis and review.
• Point-in-time values: asking prices, rents, availability, dates, descriptions, and public terms reflect what was visible at collection time.
• Nested objects: semantic groups keep related values together and reduce ambiguous flat-column names in JSON-first pipelines.
• Optional fields: null-check or test for field presence because rental, purchase, land, lightweight, and enriched records expose different detail.
• Repeated runs: compare record_id plus selected business fields and retain Apify run metadata outside the record for change history.

Data Quality, Guarantees, And Handling

• Structured records: results are normalized into predictable JSON objects for downstream use.
• Field preservation: meaningful schema-supported listing and property values are kept in stable public fields or grouped objects when available; optional source values may be absent when a specific listing does not expose them.
• Best-effort extraction: fields may vary by region, availability, listing type, page presentation, visibility, or source-side changes.
• Optional fields: null-check optional values in downstream code, dashboards, and AI workflows.
• Deduplication: use record_id; for multi-source systems, combine it with source_context.source_domain.
• Freshness: results reflect publicly available information at run time.
• Repeated runs: use the recommended idempotency key when syncing into warehouses, CRMs, search indexes, vector stores, or monitoring systems.
• Schema awareness: rely on documented fields and handle newly absent optional values gracefully.
• Run receipts: use RUN-SUMMARY or RUN-SUMMARY.html to audit listing counts, duplicate outcomes, enrichment status, field coverage, warnings, and export readiness; they do not replace dataset records.

Tips For Best Results

• Start with limit set to 10 or 25 and inspect the output before increasing scope.
• Use one city, transaction category, property type, or price band per run when clean segment comparison matters.
• Leave optional filters empty for broad discovery within the selected location and deal category.
• Add filters gradually so their effect on result count and field mix remains understandable.
• Keep enrich_data disabled for quick validation and enable it when individual-listing terms or richer facts are required.
• Schedule the same saved input for monitoring instead of recreating filters manually.
• Use record_id for deduplication and retain the original input and Apify run ID with each export.
• Review the run summary and a small row sample before importing into production dashboards, CRMs, or research pipelines.

How To Run On Apify

1. Open the Actor in Apify Console.
2. Configure a supported location and deal category, add SUUMO URLs, or use both modes.
3. Add optional filters, choose enrichment, and set the maximum listing count.
4. Click Start and wait for the run to finish.
5. Open the dataset and inspect the first records and run summary.
6. Download results in JSON, CSV, Excel, or another format supported by Apify datasets.

Agentic And API-First Usage

The Actor can serve as a structured public property-data acquisition step inside a larger automated workflow. Its bounded inputs, stable record family, field reference, idempotency guidance, and machine-readable run receipt let agents reason about both listing records and run completeness without private context.

Agent Workflow Pattern

1. Generate or select a scoped input from the supported fields.
2. Run the Actor manually, on a schedule, or through Apify platform automation.
3. Wait for completion and read the dataset records.
4. Validate records against the field reference and required envelope.
5. Read RUN-SUMMARY to verify counts, filters, duplicate outcomes, enrichment state, field coverage, warnings, and artifact readiness.
6. Upsert records into the downstream system using record_id.
7. Trigger market analysis, enrichment, alerts, BI refreshes, search indexing, lead review, or human verification.

Practical guidance for agents and workflow builders:

• Ground generated inputs in the documented parameters and enum values.
• Begin with small validation runs before allowing broader automated collection.
• Provide downstream AI steps with the field reference and one representative output example.
• Provide the run summary so agents can distinguish a complete small result from a warning or empty outcome.
• Treat optional listing and property fields as nullable; do not infer missing prices, coordinates, ownership, or availability.
• Store run ID, input configuration, segment name, and export metadata outside the listing record for audit trails.
• When context is limited, pass the input schema, idempotency key, field reference, and one sample record rather than the entire README.

Scheduling & Automation

Scheduling

Automated Data Collection

Schedule recurring runs in Apify to refresh a stable property segment daily, weekly, or on a custom cadence. Keep the input unchanged when longitudinal comparison is the goal.

• Navigate to Schedules in Apify Console.
• Create a daily, weekly, or custom-cron schedule.
• Configure and save the input parameters.
• Enable notifications for run completion.
• Add webhooks for automated processing.

Integration Options

• BI dashboards: monitor asking-price ranges, property mix, field coverage, and visible inventory over time.
• Warehouses and ETL: load nested JSON into normalized tables while retaining raw exports for full-fidelity audit.
• CRM enrichment: attach public listing, property, agency, inquiry, and availability attributes to existing operational records.
• Google Sheets or Airtable: review bounded listing sets, qualify records, and share market snapshots with non-technical teams.
• Webhooks and alerts: trigger validation, ingestion, notification, or analyst-review workflows after completion.
• Search and AI systems: index titles, descriptions, attributes, locations, and stable metadata for discovery and retrieval workflows.
• MCP connectors: authorize a compatible connector in Apify and select it in the Actor input to receive a concise listing-run summary and available dataset/report links. Delivery is best-effort and does not send the full dataset by default.

Export Formats And Downstream Use

Apify datasets can be downloaded or consumed directly by downstream systems:

• JSON: preserve nested groups, arrays, numeric prices, booleans, and source context for APIs, applications, agents, and pipelines.
• CSV or Excel: support spreadsheet review, stakeholder sharing, and lightweight analysis after deliberate flattening.
• API access: retrieve completed dataset records for automated ingestion.
• BI and warehouses: build dashboards, historical tables, segment comparisons, and monitoring models.
• Search or vector indexes: support keyword discovery, semantic retrieval, agent context, and property-research interfaces.

Downstream Pipeline Guide

• Idempotency: upsert by record_id; include source_context.source_domain in the key when combining sources.
• Null handling: treat every field except the documented required envelope and required source context as nullable or absent.
• Type handling: preserve numbers, strings, integers, arrays, and nested objects in JSON-first destinations.
• Flattening: flatten nested paths deliberately for CSV or Excel and retain the original JSON export for full fidelity.
• Partitioning: store run date, input segment, location, deal category, and workflow name alongside records.
• Change detection: compare stable keys and selected fields such as pricing.price, listing.updated_at, availability, and key property attributes.
• Quality checks: monitor total records, duplicate count, record_id coverage, price coverage, enrichment counts, and important optional-field fill rates.
• Human review: route records with missing critical business fields, unusual prices, changed availability, or high-value segments into a review queue.
• Retention: define separate retention policies for raw snapshots, run summaries, normalized warehouse tables, and derived analysis.

Performance And Coverage Expectations

The following are measured local validation runs from July 24, 2026. They demonstrate the tested shapes and should not be treated as universal performance guarantees.

Run type	Example scope	Listings	Duration	Coverage notes
Standard regional search	Tokyo, new condominiums, no enrichment, limit 10	10	1 second	10 priced records, 10 with media, 0 duplicates
Keyword-filtered search	Tokyo, new condominiums, one keyword, no enrichment	2	1 second	2 priced records, 2 with media, 0 duplicates
Direct enriched listing	One public rental listing URL with enrichment	1	1 second	Enriched record with availability and media; no numeric price in that sample

Execution time varies with selected filters, result volume, target availability, response size, enrichment depth, and the amount of information exposed per listing. Highly filtered and lightweight runs can finish faster, while broad discovery and detail-rich enrichment may take longer. This Actor currently does not create a coordinate map, so no map-generation time is included in these measurements. The Actor does not claim fastest execution, complete market coverage, or lossless source replication; use measured run receipts and field-level coverage for operational decisions.

Limitations

• Results depend on what SUUMO publicly exposes at run time and may not represent complete market inventory.
• Optional pricing, contact, relationship, availability, property, and media fields may be absent on sparse or incompatible listings.
• Very broad markets can take longer and may require a higher limit or separate segment runs.
• Public listing visibility, regional presentation, listing status, and source-side changes can affect available records and field naming.
• Asking prices, rents, availability, descriptions, and terms are point-in-time public signals and should be verified before operational decisions.
• Enriched media.image_urls can include supporting page imagery in addition to property photographs; image-critical workflows should apply their own selection rules.
• The Actor provides structured public listing data, not MLS access, ownership verification, legal advice, financial advice, investment advice, valuation, appraisal, or brokerage advice.

Troubleshooting

• No results returned: verify the selected region, deal category, filters, and direct URLs, and confirm that SUUMO currently exposes matching public listings.
• Fewer results than expected: remove overly narrow filters, raise the limit, or verify that the target segment contains enough matching listings.
• Some fields are empty: optional fields depend on the listing family, page, region, and whether useful enriched details are available.
• Duplicate-looking records: compare record_id, source identifiers, URLs, and unit-level fields to determine whether records represent distinct units or variants.
• Run takes longer than expected: lower the validation limit or split a broad market into separate cities, categories, or price segments.
• Output changed: compare the current row with the field reference and retain a small sample for support.
• Downstream import failed: validate JSON, nullable fields, nested objects, arrays, and whether the destination expects flattened columns.
• MCP summary was not delivered: confirm that a compatible connector was authorized and selected; the dataset and key-value-store artifacts remain the authoritative outputs.

FAQ

What data does this Actor collect?

It collects public SUUMO rental and sale listing identity, asking prices or rents, location, transport access, property facts, availability, media, fees, source context, and public relationship or contact fields when available.

Can I filter by location, property type, price, size, station distance, building age, recency, or keyword?

Yes. Use location_region, deal_type, price bounds, floor-plan groups, area bounds, station distance, building age, newly_published, and keyword. These fields apply to the generated regional search, not supplied URLs.

Can I collect a ward page or direct listing URL?

Yes. Add supported public SUUMO search, category, borough, ward, or direct listing URLs through startUrls.

Why did I receive fewer results than my limit?

limit is a maximum, not a promised count. The selected market may expose fewer matching public listings, or filters may reduce the visible result set.

How should I choose a limit for my first run?

Start with 10 or 25, inspect the dataset and run summary, and increase the value after confirming the segment and output shape.

What does enrichment change?

Enrichment can add individual-listing fees, terms, availability, property facts, media, relationships, and inquiry details. source_context.enrichment_status records whether useful detail was added.

Where can I find the run summary or map?

Use RUN-SUMMARY for machine-readable review and RUN-SUMMARY.html for a human-readable report in the run outputs. The Actor does not currently create an interactive map because stable coordinates are not part of the public contract.

How do I avoid duplicates across runs?

Upsert by record_id and retain source_context.source_domain. Use URLs and source identifiers for reconciliation when needed.

Can I schedule recurring runs and use the output with AI agents?

Yes. Apify schedules, APIs, webhooks, exports, and the optional MCP summary handoff support recurring and agentic workflows. Agents should rely on the documented schema and treat optional fields as nullable.

Can I export CSV, Excel, or JSON?

Yes. Apify datasets support common export formats. JSON preserves the complete nested contract; flatten nested fields deliberately for tabular formats.

Does this Actor collect private data or provide official MLS, ownership, or appraisal data?

No. It collects information publicly displayed by SUUMO and does not provide private records, official MLS completeness, ownership verification, valuations, or appraisals.

Compliance & Ethics

Responsible Data Collection

This Actor collects publicly available property listing information from SUUMO for legitimate business purposes, including:

• Real estate research and market analysis
• Property inventory monitoring and operational reporting
• Structured enrichment, catalog, and data-pipeline workflows

Users are responsible for evaluating their collection and use under applicable rules. This section is informational and not legal advice.

Best Practices

• Use collected data in accordance with applicable laws, regulations, and the target site’s terms.
• Respect individual privacy and personal information.
• Use data responsibly and avoid disruptive or excessive collection.
• Do not use this Actor for spamming, harassment, discrimination, unlawful housing practices, or other harmful purposes.
• Follow relevant data-protection, fair-housing, consumer-protection, and sector-specific requirements where applicable.
• Review retention, access-control, and data-sharing policies before operationalizing the dataset.

Support

For help, use the Issues area or the Actor page in Apify Console. Include the input used with sensitive values redacted, the Apify run ID, expected and actual behavior, and an optional small output sample. If the issue concerns an import or automation, also include the downstream destination, export format, and relevant field mapping.