# depreciated Liffull draft (`fatihtahta/homes-jp-property-scraper`) Actor

Extract structured LIFULL HOME'S property listings with asking prices, locations, property specs, amenities, media, agency names, enrichment, and map-ready coordinates. Built for market research, comps, inventory monitoring, CRM enrichment, BI dashboards, and AI-agent workflows.

- **URL**: https://apify.com/fatihtahta/homes-jp-property-scraper.md
- **Developed by:** [Fatih Tahta](https://apify.com/fatihtahta) (community)
- **Categories:** Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Homes.jp Property Scraper

**Slug:** `fatihtahta/homes-jp-property-scraper`

### Overview

Homes.jp Property Scraper collects public Japanese property listings with asking prices, transaction modes, addresses, transportation details, property attributes, media, availability, and available agency information. [LIFULL HOME'S](https://www.homes.co.jp/) is a major Japanese property portal whose public listings are useful for property discovery, market monitoring, comparable-listing research, and operational review. The actor supports residential and commercial rent and purchase segments, with additional structured filters for used-apartment searches. Optional enrichment adds detail-page fields to the same listing record when they are publicly available. Repeatable inputs and a grouped output contract make recurring collection easier to review and integrate. Results are delivered as structured dataset records suitable for export, ETL pipelines, BI dashboards, AI-agent workflows, CRM enrichment, and downstream processing.

#### What Makes This Actor Different

- **One pipeline-ready record family:** every dataset item is a `property_listing` with stable identity fields and grouped `listing`, `pricing`, `location`, `property`, `media`, `relationships`, and `source_context` objects.
- **Broad transaction-mode selection:** one run can cover selected residential or commercial rent and purchase modes in the order supplied.
- **Nationwide prefecture selection:** choose any of Japan's 47 prefectures for each residential or commercial listing mode.
- **Evidence-backed filters:** publication date works across the six residential modes; price, exclusive floor area, room layout, station walking time, building age, renovation, amenities, media, keyword, and sorting controls are available for used-apartment sale searches.
- **Optional detail enrichment:** standard records remain valid when enrichment is disabled or unavailable, while enriched records may add descriptions, fees, precise address fields, coordinates, agency names, amenities, and fuller media.
- **Run receipts:** machine-readable and human-readable summaries report saved counts, duration, input scope, field coverage, enrichment outcomes, location and price breakdowns, warnings, and artifact availability.
- **Map-ready enriched runs:** enriched runs create an interactive clustered map. Runs with no usable coordinates still receive a zero-marker map that clearly reports the coordinate outcome.
- **Deduplication-friendly identity:** `record_id` is the recommended idempotency key, with the canonical public `url` retained as an audit link.
- **Optional workflow handoff:** user-authorized Apify MCP connectors can receive a compact post-run summary and available dataset/report/map links without copying the full listing dataset through the connector.

### Who Should Use This Actor

- **Real estate investors and analysts:** assemble public asking-price, location, property-type, area, age, and amenity datasets for screening and comparable-listing research.
- **Brokerages and property operations teams:** monitor visible rental and sale inventory, availability, transaction terms, media, and published agency relationships.
- **Market research teams:** create repeatable snapshots by transaction mode, price band, floor area, room layout, building age, or publication window.
- **Proptech and data engineering teams:** ingest grouped property records into warehouses, search indexes, product catalogs, internal APIs, or BI models.
- **CRM and enrichment teams:** attach current public listing attributes, source links, address details, and agency names to existing property or opportunity records.
- **AI agents and workflow builders:** run a bounded property search, read a documented JSON contract, evaluate run receipts, and route results into a controlled downstream step.
- **Monitoring and reporting teams:** schedule consistent inputs and compare repeated datasets by stable identifier to identify additions, removals, price changes, and status changes.

### Common Use Cases

- **Market intelligence:** monitor public asking prices, listing availability, property mix, amenities, and geographic distribution.
- **Comparable-listing research:** collect rental or sale listings within a selected transaction segment, price range, area range, or room layout.
- **Inventory monitoring:** repeat the same input on a schedule and compare `record_id`, price, status, availability, and update fields.
- **Used-apartment segmentation:** create focused datasets by price, exclusive floor area, station walking time, building age, renovation category, media availability, or keyword.
- **Property catalog enrichment:** add structured listing, location, property, pricing, media, and agency fields to an internal catalog.
- **Recurring reporting:** use run summaries for operational review and dataset exports for dashboards, alerts, and historical analysis.
- **Map-based review:** inspect the distribution of coordinate-capable enriched listings without adding map rows to the dataset.
- **Agentic research workflows:** allow an internal agent to select a valid scope, collect records, review run quality, and prepare a follow-up analysis or notification.

### Real-World Questions This Data Can Answer

- Which public HOME'S listings match a selected rent or purchase segment?
- Which used apartments match a chosen asking-price, floor-area, layout, building-age, amenity, or publication-date profile?
- How do asking prices and property types vary across the locations returned by a run?
- Which listings appear new, removed, repriced, or updated compared with a previous dataset?
- Which records include coordinates, descriptions, images, amenities, or agency information after enrichment?
- Which public listings are available now, and which include move-in, occupancy, or transaction terms?
- Which records need analyst review because important optional fields were not publicly available?

### Quick Start

1. Choose a supported listing mode, or paste one public HOME'S search, category, or results URL.
2. For a structured used-apartment search, add only the price, area, layout, age, feature, media, date, keyword, and sort filters you need.
3. Set a small `limit`, such as 5 or 10, for the first validation run.
4. Start the actor in Apify Console and inspect the first dataset records.
5. Confirm the output fields and enrichment level, then raise the limit, schedule the input, export the dataset, or select an optional MCP connector.

### Input Parameters

Use either one public HOME'S URL or the structured prefecture search controls; leaving both URL and location empty uses the default Tokyo residential-rental scope.

| Parameter | Type | Description | Default |
| --- | --- | --- | --- |
| `url` | array of URLs | Public HOME'S search, category, or results URL. Although the input accepts multiple entries, use one URL per run because the first valid URL defines the starting scope. | – |
| `location` | string | One of Japan's 47 prefectures. A supplied URL takes precedence over this field. | `tokyo` |
| `deal_type` | array of strings | Listing modes, processed in selection order. Values: `rent_residential`, `buy_residential_apartment_new`, `buy_residential_apartment_used`, `buy_residential_house_new`, `buy_residential_house_used`, `buy_residential_land`, `rent_commercial_store`, `rent_commercial_office`, `rent_commercial_land`, `rent_commercial_parking`, `rent_commercial_warehouse_factory`, `rent_commercial_other`, `buy_commercial_store`, `buy_commercial_office`, `buy_commercial_warehouse_factory`, `buy_commercial_other`. | `["rent_residential"]` |
| `min_price` | integer | Minimum asking price in JPY for used-apartment sale searches. Choose a supported threshold from ¥5,000,000 to ¥100,000,000. | – |
| `max_price` | integer | Maximum asking price in JPY for used-apartment sale searches. Must be at least `min_price`. | – |
| `min_area` | integer | Minimum exclusive floor area in square metres for used-apartment sale searches. Supported picker values span 10–200 m². | – |
| `max_area` | integer | Maximum exclusive floor area in square metres for used-apartment sale searches. Must be at least `min_area`. | – |
| `bedroom_count` | array of strings | Accepted layouts for used apartments: `studio`, `1k`, `1dk`, `1ldk`, `2k`, `2dk`, `2ldk`, `3k`, `3dk`, `3ldk`, `4k`, `4dk`, `4ldk_or_more`. | `[]` |
| `distance_from_metro` | string | Maximum published walking time to a station: `any`, `within_1_minute`, `within_5_minutes`, `within_7_minutes`, `within_10_minutes`, `within_15_minutes`, `within_20_minutes`. | `any` |
| `building_max_age` | string | Maximum building age: `any`, `within_3_years`, `within_5_years`, `within_10_years`, `within_15_years`, `within_20_years`, `within_25_years`, `within_30_years`. | `any` |
| `renovations` | array of strings | Required renovation categories: `full`, `water_areas`, `interior`, `water_or_interior`. | `[]` |
| `amenities` | array of strings | Required features: `second_floor_or_above`, `parking`, `south_facing`, `auto_lock`, `bath_reheating`, `online_consultation`. | `[]` |
| `multimedia` | array of strings | Required media indicators: `floor_plan`, `images`, `panorama`. | `[]` |
| `publication_date` | string | Publication window: `any`, `today`, `within_3_days`, `within_7_days`. | `any` |
| `sort_by` | string | Listing order: `recommended`, `price_ascending`, `price_descending`, `area_descending`, `newest_building`, `address`, `newest_listing`. | `recommended` |
| `keyword` | string | Required search words, up to 80 characters, for a used-apartment search. | – |
| `enrich_data` | boolean | Adds publicly available descriptions, fuller media, fees, availability, agency, address, coordinates, and amenities to the same listing record when available. | `true` |
| `limit` | integer | Maximum number of property records saved across the run. Leave empty to continue through the available selected scope. | – |
| `mcpConnectors` | array of connector resources | Optional user-authorized Apify connectors that receive a compact run summary and available output links after durable results are saved. Full listing rows are not sent through this handoff. | `[]` |

`publication_date` applies across the six residential modes. The other structured filter fields are intentionally scoped to `buy_residential_apartment_used`; for other modes, leave them empty and use the applicable prefecture, mode, URL, limit, and enrichment settings.

### Choosing Inputs

#### URL scope or structured search

Use `url` when a public HOME'S page already expresses the desired search, category, or result scope. Use one URL per run so recurring comparisons retain a clear input boundary. Use the structured search when you want a prefecture-level listing mode and, for used apartments, explicit filter controls.

#### Transaction modes

Select one or more `deal_type` values when the same run should collect several residential or commercial segments. Separate modes into different runs when you need cleaner per-segment counts, independent schedules, or simpler downstream partitions.

#### Used-apartment filters

Publication date applies to the six residential modes. Price, area, room layout, station distance, building age, renovation, amenities, multimedia, keyword, and sort settings apply to used-apartment sale searches. Narrower filters produce more targeted datasets. Leaving optional filters empty improves discovery within the selected mode without inventing requirements the listing must satisfy.

#### Enrichment and limits

Keep `enrich_data` enabled when descriptions, fees, fuller media, precise address fields, coordinates, agency names, or amenities matter. Disable it for a lighter validation or monitoring dataset based on search-result fields. Begin with a small `limit`, review several records and the run summary, then increase it after confirming the contract fits the downstream workflow.

### Input Recipes

- **Validation run:** use `location: "Tokyo"`, one listing mode, `enrich_data: false`, and a limit of 5–10 to inspect identifiers, prices, property fields, and URLs.
- **Targeted used-apartment research:** select `buy_residential_apartment_used`, then combine a price range, area range, room layouts, station walking time, and building age.
- **Recently published residential inventory:** choose one residential mode with `publication_date`, enrichment as needed, and a bounded limit. Use `sort_by: "newest_listing"` for used apartments.
- **Direct public search monitoring:** paste one HOME'S search or results URL, keep the input stable across scheduled runs, and compare records using `record_id`.
- **Enriched review run:** enable `enrich_data` for a small validated scope when the workflow needs descriptions, fees, coordinates, amenities, agency names, or fuller media.
- **Segmented analysis:** create separate runs by transaction mode or used-apartment price band so each dataset and run receipt maps cleanly to one analytical segment.

### Example Inputs

#### Example: residential rental validation

```json
{
  "location": "Tokyo",
  "deal_type": ["rent_residential"],
  "sort_by": "recommended",
  "enrich_data": false,
  "limit": 10
}
```

#### Example: targeted used-apartment research

```json
{
  "location": "Tokyo",
  "deal_type": ["buy_residential_apartment_used"],
  "min_price": 20000000,
  "max_price": 50000000,
  "min_area": 40,
  "bedroom_count": ["2ldk", "3ldk"],
  "limit": 25
}
```

#### Example: direct public URL with enrichment

```json
{
  "url": [
    {
      "url": "https://www.homes.co.jp/chintai/tokyo/list/"
    }
  ],
  "deal_type": ["rent_residential"],
  "enrich_data": true,
  "limit": 20,
  "mcpConnectors": []
}
```

### 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 shape: `property_listing`. Run summaries, reports, diagnostics, and maps are separate key-value-store artifacts, not dataset records.

#### Record envelope and stable identifiers

Every normal record has `record_type`, `record_id`, `url`, `source_context`, and `entity`. Use `record_id` as the recommended idempotency key for warehouse merges, CRM synchronization, search indexing, and repeated-run comparisons. Use `url` as the public listing audit link; `source_context.source_url` identifies the public page associated with collection, while `source_context.canonical_url` is included when available.

For an upsert workflow, merge on `record_id` and update point-in-time business fields such as price, availability, listing status, publication dates, and property attributes. Stable identifiers make records easier to merge, deduplicate, synchronize, and compare across repeated runs.

#### Example: property listing record

```json
{
  "record_type": "property_listing",
  "record_id": "1420900001234",
  "url": "https://www.homes.co.jp/chintai/room/sample-listing/",
  "source_context": {
    "source_id": "homes_jp_property_scraper",
    "source_name": "LIFULL HOME'S",
    "source_domain": "homes.co.jp",
    "source_url": "https://www.homes.co.jp/chintai/tokyo/list/",
    "canonical_url": "https://www.homes.co.jp/chintai/room/sample-listing/",
    "page_number": 1,
    "position": 1,
    "scraped_at": "2026-07-27T10:15:30+00:00",
    "language": "ja",
    "country": "JP",
    "enrichment_status": "enriched"
  },
  "entity": {
    "title": "Sample Shinjuku Residence 502",
    "description": "Sample south-facing apartment near public transport."
  },
  "listing": {
    "listing_id": "1420900001234",
    "listing_type": "rent",
    "deal_type": "rent_residential",
    "listing_status": "instock",
    "available_from": "即時",
    "updated_at": "2026-07-27",
    "transaction_method": "仲介"
  },
  "pricing": {
    "price": 128000,
    "price_text": "12.8万円",
    "currency": "JPY",
    "deposit_terms": "敷金1ヶ月 / 礼金1ヶ月",
    "fees": {
      "管理費等": "8,000円"
    }
  },
  "location": {
    "address": "東京都新宿区西新宿",
    "street_address": "西新宿2丁目",
    "city": "新宿区",
    "region": "東京都",
    "postal_code": "160-0023",
    "country": "Japan",
    "country_code": "JP",
    "latitude": 35.6896,
    "longitude": 139.6917,
    "transportation": "JR山手線 新宿駅 徒歩8分"
  },
  "property": {
    "property_type": "賃貸マンション",
    "building_structure": "鉄筋コンクリート造",
    "floor": "5階 / 12階建",
    "unit": "502",
    "floor_plan": "2LDK",
    "orientation": "南",
    "floor_area": 40.25,
    "floor_area_text": "40.25m²",
    "area_unit": "m²",
    "building_age_text": "築8年",
    "year_built": 2018,
    "amenities": ["オートロック", "宅配ボックス"]
  },
  "media": {
    "main_image_url": "https://image.homes.jp/sample/main.jpg",
    "image_urls": [
      "https://image.homes.jp/sample/main.jpg",
      "https://image.homes.jp/sample/interior.jpg"
    ],
    "photos": [
      {
        "url": "https://image.homes.jp/sample/interior.jpg",
        "caption": "リビング"
      }
    ]
  },
  "relationships": {
    "agency": {
      "name": "Sample Housing Shinjuku"
    }
  },
  "attributes": {
    "source_specific": {
      "detail_facts": {
        "設備": "エアコン、追焚機能"
      }
    }
  }
}
```

Optional groups and fields appear only when the listing and selected enrichment mode provide them. A standard record uses the same envelope but usually contains fewer detail fields and has `source_context.enrichment_status` set to `standard` or `recovery_exhausted`.

#### Run Summary, Map, And Artifacts

The default dataset remains the primary output. Stable run artifacts are available from the run's key-value-store output:

| Artifact | Purpose |
| --- | --- |
| `RUN-SUMMARY` | Machine-readable run receipt with timestamps, duration, public input scope, saved counts, record and deal-type breakdowns, enrichment coverage, location counts, coordinate coverage, pricing metrics, property types, warnings, and artifact keys. |
| `RUN-SUMMARY.html` | Human-readable report with KPI cards and breakdown tables for operational review. |
| `results-map` | Interactive clustered listing map created for enriched runs. It reports inspected, mapped, skipped-coordinate, and deduplicated-marker counts. |
| `RUN-SUMMARY-ERROR` | Best-effort diagnostic created only when summary generation fails after records were saved. |

Property teams can use these artifacts to confirm what a run saved, assess enrichment and coordinate coverage, and review location or price distributions. Data teams and AI agents can treat the JSON summary as a run receipt for recurring comparisons, alert routing, import decisions, and follow-up review. The map is conditional on `enrich_data`; when an enriched run has no usable coordinates, the actor still creates a valid zero-marker map rather than adding placeholder rows to the dataset.

### Field Reference

#### Record envelope

- **record\_type** *(string, required)*: Stable record family; currently `property_listing`.
- **record\_id** *(string, required)*: Recommended deduplication and upsert key, using the source listing identifier or canonical URL fallback.
- **url** *(string, required)*: Canonical public listing URL for audit and review.

#### Source context

- **source\_context** *(object, required)*: Provenance, position, timing, and enrichment metadata.
- **source\_context.source\_id** *(string, required)*: Stable source identifier.
- **source\_context.source\_name** *(string, required)*: Public source name.
- **source\_context.source\_domain** *(string, required)*: Source domain.
- **source\_context.source\_url** *(string, required)*: Public page associated with the record.
- **source\_context.canonical\_url** *(string, optional)*: Canonical listing URL when available separately.
- **source\_context.page\_number** *(integer, optional)*: One-based result-page number when determinable.
- **source\_context.position** *(integer, required)*: One-based position in the normalized result batch.
- **source\_context.scraped\_at** *(string, required)*: UTC timestamp when the record was produced.
- **source\_context.language** *(string, required)*: Source-content language code, normally `ja`.
- **source\_context.country** *(string, required)*: Source-market country code, normally `JP`.
- **source\_context.enrichment\_status** *(string, required)*: `standard`, `enriched`, or `recovery_exhausted`.

#### Listing identity

- **entity** *(object, required)*: Human-facing listing identity.
- **entity.title** *(string, required)*: Public listing title.
- **entity.description** *(string, optional)*: Detailed public description when available.

#### Listing

- **listing** *(object, optional)*: Transaction, availability, publication, and source terms.
- **listing.listing\_id** *(string, optional)*: Source-native listing identifier.
- **listing.listing\_type** *(string, optional)*: Normalized `rent` or `sale` category.
- **listing.deal\_type** *(string, optional)*: Selected residential or commercial transaction mode.
- **listing.listing\_status** *(string, optional)*: Normalized source availability status.
- **listing.available\_from** *(string, optional)*: Published move-in or handover timing.
- **listing.posted\_at** *(string, optional)*: Published listing date or timestamp.
- **listing.updated\_at** *(string, optional)*: Source-provided update date or timestamp.
- **listing.occupancy\_status** *(string, optional)*: Published occupancy or vacancy state.
- **listing.transaction\_method** *(string, optional)*: Published agency or transaction role.
- **listing.contract\_period** *(string, optional)*: Lease or contract duration.
- **listing.remarks** *(string, optional)*: Additional public listing remarks.

#### Pricing

- **pricing** *(object, optional)*: Asking-price and transaction-cost information.
- **pricing.price** *(number, optional)*: Normalized asking price in the listed currency; this is not a valuation.
- **pricing.price\_text** *(string, optional)*: Original human-readable asking-price text.
- **pricing.currency** *(string, optional)*: Currency code, normally `JPY`.
- **pricing.unit\_price\_text** *(string, optional)*: Published price-per-area text.
- **pricing.deposit\_terms** *(string, optional)*: Published deposit or key-money terms.
- **pricing.fees** *(object, optional)*: Named fee values such as management charges or insurance requirements.

#### Location

- **location** *(object, optional)*: Address, transportation, country, and coordinate fields.
- **location.address** *(string, optional)*: Best available display address.
- **location.street\_address** *(string, optional)*: Street-level address when published.
- **location.city** *(string, optional)*: City, ward, town, or municipality.
- **location.region** *(string, optional)*: Prefecture or first-level region.
- **location.postal\_code** *(string, optional)*: Published postal code.
- **location.country** *(string, optional)*: Human-readable country name.
- **location.country\_code** *(string, optional)*: ISO country code.
- **location.latitude** *(number, optional)*: WGS84 latitude available from enrichment.
- **location.longitude** *(number, optional)*: WGS84 longitude available from enrichment.
- **location.transportation** *(string, optional)*: Station, route, and walking-time text.

#### Property

- **property** *(object, optional)*: Physical attributes, layout, age, capacity, and amenities.
- **property.property\_type** *(string, optional)*: Source property category.
- **property.building\_structure** *(string, optional)*: Published construction or structural type.
- **property.floor** *(string, optional)*: Unit floor and/or total-floor text.
- **property.unit** *(string, optional)*: Published room or unit identifier.
- **property.floor\_plan** *(string, optional)*: Compact room layout such as `2LDK`.
- **property.layout\_details** *(string, optional)*: Detailed room configuration.
- **property.orientation** *(string, optional)*: Primary exposure or balcony direction.
- **property.floor\_area** *(number, optional)*: Normalized floor area in square metres.
- **property.floor\_area\_text** *(string, optional)*: Original floor-area text.
- **property.building\_area\_text** *(string, optional)*: Published building-area text where applicable.
- **property.balcony\_area** *(number, optional)*: Normalized balcony area in square metres.
- **property.balcony\_area\_text** *(string, optional)*: Original balcony-area text.
- **property.area\_unit** *(string, optional)*: Unit used by normalized area values, normally `m²`.
- **property.building\_age\_text** *(string, optional)*: Original building-age text.
- **property.year\_built** *(integer, optional)*: Construction year when available.
- **property.number\_of\_rooms** *(number, optional)*: Separate normalized room count when supplied.
- **property.total\_units** *(integer, optional)*: Number of units in the building.
- **property.total\_units\_text** *(string, optional)*: Original building-unit-count text.
- **property.parking** *(string, optional)*: Published parking availability or terms.
- **property.amenities** *(array of strings, optional)*: Deduplicated property features and equipment.

#### Media

- **media** *(object, optional)*: Deduplicated public listing media.
- **media.main\_image\_url** *(string, optional)*: Primary image URL.
- **media.image\_urls** *(array of strings, optional)*: Image URLs in source presentation order after deduplication.
- **media.photos** *(array of objects, optional)*: Detail-page photos with a required `url` and optional `caption`.
- **media.photos\[].url** *(string, required per photo)*: Public photo URL.
- **media.photos\[].caption** *(string, optional)*: Source-provided caption.

#### Relationships

- **relationships** *(object, optional)*: Related real-estate organizations published with the listing.
- **relationships.agency** *(object, optional)*: Agency handling or offering the listing.
- **relationships.agency.name** *(string, optional)*: Published agency name.

#### Source-specific attributes

- **attributes** *(object, optional)*: Useful HOME'S values that do not fit a stronger canonical group.
- **attributes.source\_specific** *(object, optional)*: Non-duplicated source-specific values.
- **attributes.source\_specific.search\_title** *(string, optional)*: Search-result title when it differs from the enriched title.
- **attributes.source\_specific.search\_floor\_area\_text** *(string, optional)*: Search-result area text when it differs from the enriched detail value.
- **attributes.source\_specific.detail\_facts** *(object, optional)*: Additional public detail label/value pairs not already represented in canonical fields.

### Data Model Notes

- **Identity:** use `record_id` for matching, deduplication, and upserts; retain `url` as the public audit link.
- **Provenance:** `source_context` identifies the source, public source page, record position, production time, and enrichment outcome.
- **Nested groups:** listing, pricing, location, property, media, relationships, and source-specific attributes remain grouped for predictable JSON-first consumption.
- **Point-in-time values:** asking price, status, availability, descriptions, agency relationships, and public listing dates reflect what was visible at run time.
- **Optionality:** enrichment, listing type, transaction mode, geography, and source availability affect which optional fields appear; consumers should null-check or test for field presence.
- **Repeated runs:** compare records by `record_id`, then evaluate selected business fields and retain Apify run metadata alongside the dataset for historical analysis.

### 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 retained in stable public fields or grouped objects; optional values may still be absent when a listing does not expose them.
- **Best-effort extraction:** field availability can vary by location, listing mode, property category, publication state, visibility, and source-side changes.
- **Optional fields:** downstream code, dashboards, and schemas should test for field presence rather than assuming every enriched field exists.
- **Deduplication:** use `record_id` as the primary stable key and `url` as the audit link.
- **Freshness:** records reflect publicly available listing information at run time.
- **Repeated runs:** use `record_id` when syncing into warehouses, CRMs, search indexes, vector stores, or monitoring systems.
- **Schema awareness:** rely on documented fields and handle newly missing optional fields gracefully.
- **Run receipts:** use summary and map artifacts to audit counts, enrichment, coordinate coverage, warnings, and map readiness without treating those artifacts as dataset records.

### Tips For Best Results

- Start with a limit of 5–10 and inspect several records before increasing scope.
- Use one URL, transaction segment, or analytical price band per run when clean comparisons matter.
- Leave optional used-apartment filters empty for broader discovery within the selected mode.
- Add filters gradually so you can see how each choice changes the returned dataset.
- Keep enrichment enabled only when the additional detail fields and map artifact add value to the workflow.
- Schedule recurring runs with identical inputs for consistent change detection.
- Store the input configuration and Apify run identifier alongside each historical export.
- Review `RUN-SUMMARY` and the map, when present, before importing a large run into a production dataset.

### How to Run on Apify

1. Open Homes.jp Property Scraper in Apify Console.
2. Choose one public HOME'S URL or configure the structured Tokyo listing scope.
3. Select transaction modes, applicable used-apartment filters, enrichment, and a maximum result count.
4. Click **Start** and wait for the run to finish.
5. Open the dataset and inspect the first property records and run artifacts.
6. Export the dataset as JSON, CSV, Excel, or another format supported by Apify.

### Agentic And API-First Usage

Homes.jp Property Scraper can act as a structured public property-data acquisition step inside scheduled automations, internal tools, and AI-agent workflows. Its explicit inputs, grouped record envelope, stable identifier, and run receipts allow an automated system to reason about both the requested scope and the resulting dataset.

#### Agent workflow pattern

1. Generate or select a scoped input using only the documented parameters and allowed values.
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 confirm required identity fields.
5. Read `RUN-SUMMARY`, `RUN-SUMMARY.html`, and `results-map` when present to verify saved counts, enrichment, warnings, coordinates, and artifact readiness.
6. Upsert records into the downstream system using `record_id`.
7. Trigger market analysis, CRM enrichment, alerts, BI refreshes, search/vector indexing, or human review.

For agentic use, keep prompts grounded in the supported input fields, begin with bounded validation runs, and provide downstream agents with the Field Reference plus one representative record. Treat optional values as unavailable rather than asking an agent to infer them. Store run identifiers, input configurations, and export metadata separately for auditability. When context is limited, provide the input schema, `record_id` guidance, and a representative JSON record instead of the entire documentation page.

Optional MCP delivery can hand a compact run summary and available output links to a selected, user-authorized connector. Authorize the connector in Apify and select it in `mcpConnectors`; the actor receives the connector ID while Apify supplies third-party credentials server-side. Review the destination after the run; connector delivery is a summary handoff, not a bulk listing export.

### Scheduling & Automation

#### Scheduling

**Automated Data Collection**

Use Apify schedules to refresh a consistent property scope daily, weekly, or on a custom cadence. Keep the same input when the goal is reliable run-to-run comparison.

1. Navigate to **Schedules** in Apify Console.
2. Create a daily, weekly, or custom schedule.
3. Configure and save the actor input.
4. Enable appropriate run-completion notifications.
5. Add webhooks when another system should process completed runs.

#### Integration Options

- **Data warehouses:** preserve nested JSON or map it into normalized listing, location, pricing, property, media, and agency tables.
- **BI dashboards:** monitor asking prices, saved counts, property types, statuses, enrichment coverage, and geographic distribution.
- **CRM enrichment:** attach public listing links, prices, attributes, addresses, availability, and agency names to property or opportunity records.
- **Webhooks:** trigger validation, ingestion, alerting, or reporting after a completed run.
- **Search and vector indexes:** support structured discovery, retrieval, semantic search, and controlled agent context.
- **Google Sheets or Airtable:** review bounded listing exports, segment assignments, and analyst notes.
- **MCP connectors:** authorize a compatible connector in Apify, select it in the input, and receive a compact run summary plus available dataset, report, and map links.

### Export Formats And Downstream Use

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

- **JSON:** preserves nested objects, arrays, numbers, and the complete public record contract for APIs, applications, AI agents, and pipelines.
- **CSV or Excel:** supports spreadsheet review and lightweight analysis; nested groups should be flattened deliberately.
- **API access:** supports automated ingestion into internal applications and data services.
- **BI and warehouses:** enables historical reporting, dashboarding, segmentation, and monitoring.
- **Search or vector indexes:** supports listing discovery, semantic retrieval, and agent context when indexed with stable identifiers and selected descriptive fields.

### Downstream Pipeline Guide

- **Idempotency:** merge or upsert on `record_id`; retain `url` for source review.
- **Null handling:** treat all fields outside the required envelope as optional and test nested paths before use.
- **Type handling:** preserve numeric prices, coordinates, areas, arrays, and nested objects in JSON-first systems.
- **Flattening:** flatten nested groups deliberately for tabular exports and retain the original JSON for full fidelity.
- **Partitioning:** store run date, input segment, transaction mode, geography, and workflow name alongside records.
- **Change detection:** compare repeated records by `record_id`, then evaluate `pricing.price`, `listing.listing_status`, `listing.available_from`, `listing.updated_at`, and selected property attributes.
- **Quality checks:** monitor saved count, required identifiers, unique `record_id` count, price availability, enrichment status, and important optional-field fill rates.
- **Human review:** route records with missing business-critical fields, unusual prices, changed status, or selected high-value segments to an analyst queue.
- **Retention:** choose separate retention periods for raw exports, normalized warehouse tables, and operational snapshots based on the workflow.

### Performance And Coverage Expectations

No universal public runtime benchmark is published for this actor. Use a small validation run to establish timing for your chosen transaction mode, filters, enrichment setting, result count, and scheduling environment before planning larger recurring jobs.

Execution time varies with filter selectivity, visible result volume, listing information depth, enrichment, coordinate availability, map creation, and source availability. Highly targeted or non-enriched validation runs may finish sooner than broad or detail-rich runs, but actual duration should be measured from your own run summary rather than assumed from a generic estimate. `RUN-SUMMARY` records the duration and saved count for each completed run so operators can build evidence from their own representative workloads.

### Limitations

- Results depend on what LIFULL HOME'S publicly exposes at run time.
- The structured location search supports all 47 prefectures; use a supported public HOME'S URL for a narrower city, ward, neighborhood, or station scope.
- Used-apartment filters do not apply to every residential or commercial transaction mode.
- Optional enrichment fields can be absent even when enrichment is enabled.
- Very broad scopes or detail-rich runs can take longer, and a requested limit is a maximum rather than a guarantee of that many matching records.
- Asking prices, statuses, availability, descriptions, and agency relationships are point-in-time public signals and should be independently verified before operational decisions.
- The actor does not provide MLS access, ownership verification, appraisal-grade valuations, or legal, financial, investment, valuation, or brokerage advice.

### Troubleshooting

- **No results returned:** verify the URL, prefecture, transaction mode, filter applicability, and whether HOME'S currently shows matching public listings.
- **Fewer results than the limit:** the limit is a ceiling; the public source may expose fewer matching listings for the selected scope.
- **Some fields are absent:** optional values depend on the listing, transaction type, enrichment outcome, and publicly visible information.
- **Duplicate-looking records:** compare `record_id` first, then check whether the rows represent different units, URLs, transaction modes, or listing updates.
- **The run takes longer than expected:** lower the validation limit, disable enrichment when detail fields are unnecessary, or separate broad segments into independent runs.
- **Output changed:** compare current records with the Field Reference and retain a small sample for support.
- **A downstream import failed:** check JSON validity, optional nested paths, array handling, number types, and whether a tabular destination expects flattened columns.
- **MCP delivery is absent:** confirm a compatible connector was authorized and selected; the dataset and run artifacts remain the primary outputs.

### FAQ

#### What data does this actor collect?

It collects public HOME'S property listings with identity, transaction, asking-price, location, property, media, availability, agency, and source-context fields when available.

#### Which transaction types are supported?

The input includes residential rentals; new and used apartments; new and used houses; residential land; and commercial store, office, land, parking, warehouse/factory, and other rent or purchase segments.

#### Can I filter by price, area, layout, age, amenities, or publication date?

`publication_date` works across the six residential modes. Price, area, layout, age, amenities, and the other structured filters are scoped to `buy_residential_apartment_used` and should be left empty for other modes.

#### Why did I receive fewer results than my limit?

`limit` is the maximum number of records to save, not a guaranteed count. The selected public scope may contain fewer visible matches.

#### Where are the run summary and interactive map?

Open the run's key-value-store outputs. `RUN-SUMMARY` and `RUN-SUMMARY.html` are run receipts; `results-map` is created for enriched runs.

#### How should I choose a limit for my first run?

Begin with 5–10 records, inspect the schema and optional-field coverage, then increase the limit for the validated workflow.

#### Can I schedule recurring runs?

Yes. Save a stable input in an Apify schedule and compare results by `record_id`.

#### How do I avoid duplicates across runs?

Use `record_id` as the primary upsert key. Preserve the Apify run identifier and input configuration separately for historical comparisons.

#### Can I use the output with AI agents and automated workflows?

Yes. Use the documented input schema, grouped JSON records, run receipts, and optional summary-only MCP handoff as controlled workflow boundaries.

#### Can I export the data?

Yes. Apify datasets support JSON, CSV, Excel, API access, and other platform-supported export formats.

#### Does this actor collect private data or provide official valuation data?

It is designed for publicly available property listing information. It does not provide MLS access, ownership verification, appraisals, or investment recommendations.

### Compliance & Ethics

#### Responsible Data Collection

This actor collects publicly available property-listing information from LIFULL HOME'S for legitimate purposes, including:

- **Real estate** research and market analysis
- Property discovery, inventory monitoring, and operational reporting
- Structured data integration, enrichment, and workflow automation

Users are responsible for determining whether their collection and use comply with applicable requirements. This section is informational and not legal advice.

#### Best Practices

- Use collected information 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.
- Review retention, access-control, and data-sharing policies before operationalizing the dataset.

### Support

Use the actor page's **Issues** tab to request help. Include the redacted input, Apify run ID, expected behavior, actual behavior, and—when useful—a small output sample. For pipeline-related issues, also identify the downstream destination or export format and explain how it handles nested or optional fields. No service-level response commitment is implied.

# Actor input Schema

## `url` (type: `array`):

Paste a public homes.co.jp search, category, or results-list URL. The input accepts multiple lines for compatibility, but this actor currently starts from the first valid HOME'S URL, so use one URL per run for predictable monitoring and refresh workflows.

## `location` (type: `string`):

Choose one prefecture for a clear, repeatable search boundary. Leave this empty to use Tokyo. Use a supported HOME'S results URL above for a narrower city, ward, neighborhood, or station scope.

## `deal_type` (type: `array`):

Select the residential or commercial rent and sale routes to collect. Modes are processed in the order selected; the default collects residential rentals. Publication date applies to the six residential modes; the other structured filters below only affect Buy | used apartments.

## `min_price` (type: `integer`):

Set the lowest asking price for Buy | used apartments. Choose a supported HOME'S threshold from ¥5,000,000 to ¥100,000,000; this value is ignored for other listing modes.

## `max_price` (type: `integer`):

Set the highest asking price for Buy | used apartments. Choose a supported HOME'S threshold from ¥5,000,000 to ¥100,000,000 and keep it greater than or equal to the minimum price.

## `min_area` (type: `integer`):

Keep used-apartment listings at or above this exclusive floor area. Choose a supported HOME'S threshold from 10 to 200 m²; this value is ignored for other listing modes.

## `max_area` (type: `integer`):

Keep used-apartment listings at or below this exclusive floor area. Choose a supported HOME'S threshold from 10 to 200 m² and keep it greater than or equal to the minimum area.

## `bedroom_count` (type: `array`):

Select one or more HOME'S layout categories to narrow used-apartment sale listings, such as Studio, 1LDK, or 3LDK. Leave empty to accept any layout; this filter is omitted for other listing modes.

## `distance_from_metro` (type: `string`):

Choose the longest acceptable advertised walk to the nearest station for used-apartment listings. Keep Any for no walking-time filter.

## `building_max_age` (type: `string`):

Limit used-apartment listings to buildings no older than the selected age. Keep Any when building age should not narrow the dataset.

## `renovations` (type: `array`):

Select renovation work that must be indicated on used-apartment listings. Leave empty when renovation status should not narrow the search.

## `amenities` (type: `array`):

Select proven HOME'S features such as parking, south-facing orientation, auto-lock entry, or online consultation. All selected values refine used-apartment sale searches; leave empty for no feature requirement.

## `multimedia` (type: `array`):

Require used-apartment listings to advertise the selected media types, such as a floor plan, property images, or panorama. Leave empty when media availability should not filter results.

## `publication_date` (type: `string`):

Choose how recently the listing information must have been published for any of the six residential listing modes. Keep Any time to include listings regardless of publication date.

## `sort_by` (type: `string`):

Choose how HOME'S orders used-apartment results before collection. Ordering affects which listings appear first when a result limit is set.

## `keyword` (type: `string`):

Enter up to 80 characters of free text for a used-apartment search. HOME'S requires all supplied words, so use focused terms when building repeatable monitoring or downstream comparison datasets.

## `enrich_data` (type: `boolean`):

Keep enabled to add available descriptions, fuller photo sets, fees, availability, agency, address details, coordinates, and amenities. Disable it for quicker validation runs when search-result data is sufficient; unsuccessful detail collection still leaves a valid standard listing.

## `limit` (type: `integer`):

Choose the maximum number of property records to save across the run. Leave empty to continue through all listings available to the selected source scope and listing modes.

## `mcpConnectors` (type: `array`):

Choose user-authorized MCP connectors for an optional post-run summary and workflow handoff. The delivery contains compact run totals plus available dataset, summary, report, and map links—not the full listing dataset. Leave empty to only save listings to the Apify dataset and key-value store.

## Actor input object example

```json
{
  "location": "tokyo",
  "deal_type": [
    "rent_residential"
  ],
  "bedroom_count": [],
  "distance_from_metro": "any",
  "building_max_age": "any",
  "renovations": [],
  "amenities": [],
  "multimedia": [],
  "publication_date": "any",
  "sort_by": "recommended",
  "enrich_data": true,
  "mcpConnectors": []
}
```

# Actor output Schema

## `results` (type: `string`):

Grouped, pipeline-ready LIFULL HOME'S property listings in the default dataset.

## `runSummaryJson` (type: `string`):

Stable machine-readable totals, coverage, breakdowns, warnings and artifact availability.

## `runSummaryHtml` (type: `string`):

Human-readable report for reviewing the completed or stopped run.

## `resultsMap` (type: `string`):

Clustered map generated for enriched runs. It may contain zero markers when no valid coordinates are available.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("fatihtahta/homes-jp-property-scraper").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("fatihtahta/homes-jp-property-scraper").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 '{}' |
apify call fatihtahta/homes-jp-property-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fatihtahta/homes-jp-property-scraper"
        }
    }
}

```

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/wbzOizcmiQxMXgRfy/builds/lq5RbtSUTmc2bLh6w/openapi.json