# peterpan Property Scraper — Korea Rental Data & API (`sian.agency/peterpan-property-scraper`) Actor peterpanz.com (피터팬의 좋은방 구하기) rental scraper & real estate data API for South Korea. Villa, apartment, officetel & store listings: deposit (보증금), monthly rent (월세), maintenance, size, floor, amenities, address, coordinates, photos — clean JSON/CSV, one row per room. Fast overview or full detail. - **URL**: https://apify.com/sian.agency/peterpan-property-scraper.md - **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community) - **Categories:** Real estate, Automation, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 overview listing extracteds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## peterpan Property Scraper — Korea Rental Data & API 🏠 [![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Dabang Property Scraper](https://img.shields.io/badge/Store-Dabang%20Property%20Scraper-1AE392)](https://apify.com/sian.agency/dabang-property-scraper?fpr=sian) [![able Property Scraper](https://img.shields.io/badge/Store-able%20Property%20Scraper-1AE392)](https://apify.com/sian.agency/able-property-scraper?fpr=sian) [![Trip.com Scraper](https://img.shields.io/badge/Store-Trip.com%20Scraper-93D500)](https://apify.com/sian.agency/trip-com-scraper?fpr=sian) #### 🎉 Turn peterpanz.com (피터팬의 좋은방 구하기) listings into clean, structured data — one row per room, ready for analysis ##### For real-estate analysts, investors, relocation agents, and data teams working the Korean rental & lease market --- ### 📋 Overview **Need Korean rental and lease listings as clean data instead of endless map browsing?** This scraper turns peterpanz.com search results into structured JSON/CSV — one clean record per room, with deposit (보증금), monthly rent (월세), maintenance, size in m² and pyeong, floor, amenities, verification flags, address and photos. **Why analysts and agencies choose us:** - ✅ **One clean row per room** — every listing becomes a structured record, no nested mess - ⚡ **Fast & lightweight** — reads peterpanz's own JSON list API directly, no slow headless browser, no proxy overhead - 🎯 **55+ data points** — deposit, monthly rent, maintenance, room type, supplied & real size (m²/pyeong), floor, amenities, verification, address, coordinates and photos - 🗺️ **Map-area search** — pull every listing inside a lat/lng bounding box, or by villa / apartment / officetel / store vertical - 💴 **Pay-per-result** — only pay for listings you actually receive — transparent and cheap - 💎 **Two depths** — fast *overview* for whole-area sweeps, full *detail* for the free-text description, full-resolution photo gallery, and listing agency - ✨ **Three ways in** — by map bounding box, by pasted peterpanz API URL (keeps every filter), or by listing URL --- ### ✨ Features - 🏢 **Listings, done right** — clean per-room records from peterpanz's structured list feed - 💴 **Korean price model captured** — deposit (보증금) and monthly rent (월세) as integers, so 전세 vs 월세 is obvious at a glance - 📐 **Size both ways** — square metres *and* pyeong (평), plus a deposit-per-pyeong KPI ready out of the box - 🧭 **Coordinates included** — latitude/longitude on every listing for mapping and geo-analysis - 🛡️ **Verification flags** — Naver-verified, peter-verified, premium, agent vs owner — quality signals built in - 🔎 **Detail enrichment** — free-text room description, full-resolution photo gallery, and the listing agency - 🔗 **Paste-a-URL mode** — apply filters on peterpanz, paste the API link, every supported filter is preserved - 📦 **Clean exports** — JSON, CSV, Excel straight from the dataset - 🌐 **Optional Korea proxy** — off by default, available as a one-click escape hatch --- ### 🎬 Quick Start Pick a mode, give it a map bounding box (or a peterpanz search URL), and run. Listings stream into your dataset as clean rows. Export as JSON, CSV, or Excel. ```bash curl -X POST https://api.apify.com/v2/acts/sian.agency~peterpan-property-scraper/runs?token=YOUR_TOKEN \ -H 'Content-Type: application/json' \ -d '{"scrapeMode": "overview", "searchMode": "byBbox", "bbox": "37.49,37.52,127.01,127.05"}' ```` *** ### 🚀 Getting Started (3 Simple Steps) #### Step 1: Choose your input Give a map bounding box (lat/lng), paste a peterpanz `houses/area/pc` API URL, or list specific listing URLs. #### Step 2: Pick depth `overview` for fast whole-area room cards, or `detail` for description, full photos and the listing agency. #### Step 3: Run & export Start the run and download your results as JSON, CSV, or Excel. **That's it! In under a minute, you'll have:** - A clean, per-room dataset - Deposit (보증금), monthly rent (월세) and maintenance as numbers - Room type, size (m²/pyeong), floor, amenities, address, coordinates and photos *** ### 📥 Input Configuration | Field | Type | Required | Description | |-------|------|----------|-------------| | scrapeMode | string | No | `overview` (fast room cards) or `detail` (+ description, full photos, agency) | | searchMode | string | No | `byBbox`, `bySearchUrl`, or `byListingUrl` | | bbox | string | No | Map bounding box `lat_min,lat_max,lng_min,lng_max` (byBbox) | | buildingType | string | No | `villa`, `apt`, `officetel`, or `store` (byBbox) | | orderBy | string | No | `price`, `deposit`, or `random` | | search | string | No | Optional free-text keyword | | searchUrls | array | No | Pasted peterpanz `houses/area/pc` API URLs (filters preserved) | | listingUrls | array | No | peterpanz `/house/{id}` URLs or bare ids (detail mode) | | maxResults | integer | No | Max listings per run (FREE: 25, PAID: unlimited) | | maxPages | integer | No | Max list-API pages to paginate per search | **Example — overview by bounding box:** ```json { "scrapeMode": "overview", "searchMode": "byBbox", "bbox": "37.49,37.52,127.01,127.05", "buildingType": "villa", "maxResults": 200 } ``` **Example — detail by listing URL:** ```json { "scrapeMode": "detail", "searchMode": "byListingUrl", "listingUrls": ["https://www.peterpanz.com/house/19439182"] } ``` *** ### 📤 Output Results are saved to the Apify dataset with **55+ fields** per listing, including: | Field | Type | Description | |-------|------|-------------| | listingId | number | peterpanz house id | | url | string | Canonical `/house/{id}` URL | | propertyTitle | string | Listing subject | | contract\_type | string | 계약 형태 — 월세 / 전세 / 단기임대 | | deposit | number | 보증금 in KRW | | monthly\_fee | number | 월세 in KRW (0 ⇒ 전세) | | maintenance\_cost | number | 관리비 in KRW | | deposit\_per\_pyeong\_krw | number | Computed deposit per 전용평 | | room\_type | string | 방 종류, e.g. `1.5룸` | | real\_size / real\_pyeong | number | 전용면적 in m² / pyeong | | floor | string | 층, e.g. `3층/6층` | | address / sido / sigungu / dong | string | Address parts | | latitude / longitude | number | Coordinates | | naver\_verification / peter\_verified | boolean | Verification flags | | agency\_name | string | Listing agency (detail mode) | | roomDescription | string | Free-text description (detail mode) | | images / image\_count | array / number | Photo URLs / count | **Example:** ```json { "listingId": 19439182, "url": "https://www.peterpanz.com/house/19439182", "propertyTitle": "주말 정상영업 신논현역 도보 3분 인기많은 리모델링 빌라", "contract_type": "단기임대", "deposit": 1000000, "monthly_fee": 1000000, "maintenance_cost": 100000, "room_type": "1.5룸", "real_size": 28, "real_pyeong": 8.46, "floor": "3층/6층", "address": "강남구 논현동", "sigungu": "강남구", "dong": "논현동", "latitude": 37.5061376, "longitude": 127.0271979, "agency_name": "노블공인중개사사무소", "image_count": 7 } ``` *** ### 💼 Use Cases & Examples #### 1. Rental Market Research **Analysts mapping deposit & rent by neighbourhood.** **Input:** a map bounding box · **Output:** per-room dataset with 보증금 & 월세 · **Use:** build a rent heatmap by gu and dong. #### 2. Property Investment Analysis **Investors comparing 전세/월세 across buildings.** **Input:** a filtered peterpanz search · **Output:** deposit-per-pyeong on every room · **Use:** rank candidate areas by value. #### 3. Relocation & Tenant Search **Relocation agents shortlisting rooms for clients.** **Input:** bbox + building-type filter · **Output:** clean rows with deposit, rent, maintenance, amenities · **Use:** hand clients a tidy true-cost comparison sheet. #### 4. Real-Estate Lead Generation **Agencies building prospect lists of active listings.** **Input:** broad bbox sweep · **Output:** address, agency, verification records · **Use:** feed CRM pipelines. #### 5. Price & Trend Monitoring **Data teams tracking deposit/rent movements over time.** **Input:** scheduled runs on the same area · **Output:** snapshots to diff week-over-week · **Use:** detect price changes and new inventory. #### 6. Academic & Policy Research **Researchers studying Korean housing markets.** **Input:** multiple areas · **Output:** structured, reproducible datasets · **Use:** quantitative housing studies. *** ### 🔗 Integration Examples #### JavaScript/Node.js ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_TOKEN' }); const run = await client.actor('sian.agency/peterpan-property-scraper').call({ scrapeMode: 'overview', searchMode: 'byBbox', bbox: '37.49,37.52,127.01,127.05' }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items[0]); ``` #### Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_TOKEN') run = client.actor('sian.agency/peterpan-property-scraper').call( run_input={'scrapeMode': 'overview', 'searchMode': 'byBbox', 'bbox': '37.49,37.52,127.01,127.05'} ) for item in client.dataset(run['defaultDatasetId']).iterate_items(): print(item) ``` #### cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/sian.agency~peterpan-property-scraper/runs?token=YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"scrapeMode": "overview", "searchMode": "byBbox", "bbox": "37.49,37.52,127.01,127.05"}' ``` #### Automation Workflows (N8N / Zapier / Make) 1. **Trigger**: Schedule or webhook 2. **HTTP Request**: Call the actor API 3. **Process**: Handle the JSON results 4. **Action**: Save to a sheet, notify, or sync to CRM *** ### 📊 Performance & Pricing #### FREE Tier (Try It Now) - **25 listings** per run — full feature access, same quality - No credit card required - Perfect for testing and small projects #### PAID Tier (Production Ready) - **Unlimited** listings per run - Pay-per-result: only charged for listings you actually receive 💴 **Cheap by design** — reading peterpanz's own JSON list feed with no proxy overhead keeps the per-listing price among the lowest for Korean real-estate data. 🔗 [View current pricing](https://apify.com/sian.agency/peterpan-property-scraper?fpr=sian) *** ### ❓ Frequently Asked Questions **Q: How many listings can I scrape?** A: FREE tier: 25 per run. PAID tier: unlimited. **Q: Do I need an account or API key?** A: No. Just provide a bounding box, a search URL, or listing URLs. **Q: What output formats are available?** A: JSON, CSV, and Excel — export directly from the Apify dataset. **Q: Are GPS coordinates included?** A: Yes — every overview row carries latitude/longitude plus the structured address. **Q: What's the difference between overview and detail?** A: Overview is the fast list-API data (already ~90% of fields). Detail fetches each listing's full page for the free-text description, full-resolution photo gallery and listing agency, and merges them in. **Q: How do 전세 (jeonse) and 월세 (wolse) appear?** A: Each row has both `deposit` (보증금) and `monthly_fee` (월세). A `monthly_fee` of 0 with a large deposit indicates a 전세 listing. *** ### 🐛 Troubleshooting **No results returned** - Check that the bounding box is `lat_min,lat_max,lng_min,lng_max` and covers a populated area, or that the pasted URL is a peterpanz `houses/area/pc` API link. **Fewer rows than expected** - FREE tier caps at 25 listings per run — upgrade for unlimited. - A small bounding box or a narrow building-type filter may simply return fewer listings. **A specific listing failed in detail mode** - The listing may have expired or been delisted; the run continues and skips it. *** ### ⚖️ Is it legal to scrape data? Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers. You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/). > **Disclaimer:** This is an independent tool and is not affiliated with, endorsed by, or sponsored by peterpan, peterpanz.com, or 피터팬의 좋은방 구하기 / its operator. "peterpan" / "피터팬의 좋은방 구하기" is a trademark of its respective owner. Use this actor in compliance with the site's terms of service and all applicable laws. *** ### 🤝 Support [![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi) **Join our active support community** - For issues or questions, open an issue in the actor's repository - Check the [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools - 📧 *** **Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)** # Actor input Schema ## `scrapeMode` (type: `string`): 🧭 **OVERVIEW** (cheap, primary): one row per listing from peterpanz's own JSON list API — deposit (보증금), monthly rent (월세), maintenance, room type, size in m²/pyeong, floor, amenities, verification flags, address, coordinates & photos. ~90% of fields, no extra cost. 🔎 **DETAIL** (enrich): also fetches each listing's full /house page for the free-text description, full-resolution photo gallery & listing agency. Detail merges overview + detail into one record. ## `searchMode` (type: `string`): 🔀 How listings are discovered. - **byBbox** — give a map bounding box (lat/lng) and an optional building-type vertical (simplest). - **bySearchUrl** — paste a ready-made peterpanz `houses/area/pc` API URL with your filters applied. - **byListingUrl** — fetch specific listings directly (DETAIL only). ## `bbox` (type: `string`): 🗺️ **BY BBOX:** Map bounding box as `lat_min,lat_max,lng_min,lng_max`. The default covers central Seoul (Gangnam). Draw any rectangle on a map app and read the corners. 💡 **TIP:** Smaller boxes return denser, more relevant results. ## `buildingType` (type: `string`): 🏢 **BY BBOX:** Restrict to one vertical. Leave blank for all types. - `villa` = 빌라/주택 · `apt` = 아파트 · `officetel` = 오피스텔 · `store` = 상가/사무실. ## `orderBy` (type: `string`): ↕️ Result sort. `price` (default) and `deposit` are deterministic — safe for stable pagination. `random` is the site UI default but reshuffles per call (causes duplicates/gaps across pages). ## `search` (type: `string`): 🔎 Optional free-text search term applied to the listing query. ## `searchUrls` (type: `array`): 🔗 **BY SEARCH URL:** Paste one or more peterpanz `houses/area/pc` API URLs (the bbox + filters are recovered from the URL). Example — `https://api.peterpanz.com/houses/area/pc?filter=latitude:37.49~37.52||longitude:127.01~127.05&pageSize=50&pageIndex=1&order_by=price`. ## `listingUrls` (type: `array`): 🏠 **BY LISTING URL (DETAIL ONLY):** Paste peterpanz `/house/{id}` URLs or bare house ids (e.g. `https://www.peterpanz.com/house/19439182` or `19439182`). Used with scrapeMode = detail. ## `maxResults` (type: `integer`): 🔢 Maximum listings to return per run. **FREE users:** capped at 25 · **PAID users:** unlimited. ## `maxPages` (type: `integer`): 📄 Maximum list-API pages to paginate per search before stopping (50 listings each). ## `pageSize` (type: `integer`): 📦 Listings per API page (max 50). ## `zoomLevel` (type: `integer`): 🔍 Map zoom level passed to the list API. Default 15. ## `useProxy` (type: `boolean`): 🌐 Route requests through a South Korea residential proxy. **Off by default** — peterpanz's list API is ungated, so leaving this off keeps runs fast and cheap. Enable only if you hit a rate-limit or geo-block. ## Actor input object example ```json { "scrapeMode": "overview", "searchMode": "byBbox", "bbox": "37.49,37.52,127.01,127.05", "buildingType": "", "orderBy": "price", "searchUrls": [ "https://api.peterpanz.com/houses/area/pc?filter=latitude:37.49~37.52||longitude:127.01~127.05&pageSize=50&pageIndex=1&order_by=price" ], "maxResults": 100, "maxPages": 5, "pageSize": 50, "zoomLevel": 15, "useProxy": false } ``` # Actor output Schema ## `results` (type: `string`): All scraped peterpanz listings as a clean JSON/CSV dataset. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "bbox": "37.49,37.52,127.01,127.05", "searchUrls": [ "https://api.peterpanz.com/houses/area/pc?filter=latitude:37.49~37.52||longitude:127.01~127.05&pageSize=50&pageIndex=1&order_by=price" ] }; // Run the Actor and wait for it to finish const run = await client.actor("sian.agency/peterpan-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "bbox": "37.49,37.52,127.01,127.05", "searchUrls": ["https://api.peterpanz.com/houses/area/pc?filter=latitude:37.49~37.52||longitude:127.01~127.05&pageSize=50&pageIndex=1&order_by=price"], } # Run the Actor and wait for it to finish run = client.actor("sian.agency/peterpan-property-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "bbox": "37.49,37.52,127.01,127.05", "searchUrls": [ "https://api.peterpanz.com/houses/area/pc?filter=latitude:37.49~37.52||longitude:127.01~127.05&pageSize=50&pageIndex=1&order_by=price" ] }' | apify call sian.agency/peterpan-property-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=sian.agency/peterpan-property-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "peterpan Property Scraper — Korea Rental Data & API", "description": "peterpanz.com (피터팬의 좋은방 구하기) rental scraper & real estate data API for South Korea. Villa, apartment, officetel & store listings: deposit (보증금), monthly rent (월세), maintenance, size, floor, amenities, address, coordinates, photos — clean JSON/CSV, one row per room. Fast overview or full detail.", "version": "1.0", "x-build-id": "p2qIY3R0PuEb1dzV5" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~peterpan-property-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-peterpan-property-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/sian.agency~peterpan-property-scraper/runs": { "post": { "operationId": "runs-sync-sian.agency-peterpan-property-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/sian.agency~peterpan-property-scraper/run-sync": { "post": { "operationId": "run-sync-sian.agency-peterpan-property-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "scrapeMode": { "title": "🧭 Scrape mode", "enum": [ "overview", "detail" ], "type": "string", "description": "🧭 **OVERVIEW** (cheap, primary): one row per listing from peterpanz's own JSON list API — deposit (보증금), monthly rent (월세), maintenance, room type, size in m²/pyeong, floor, amenities, verification flags, address, coordinates & photos. ~90% of fields, no extra cost.\n\n🔎 **DETAIL** (enrich): also fetches each listing's full /house page for the free-text description, full-resolution photo gallery & listing agency. Detail merges overview + detail into one record.", "default": "overview" }, "searchMode": { "title": "🔀 Search mode", "enum": [ "byBbox", "bySearchUrl", "byListingUrl" ], "type": "string", "description": "🔀 How listings are discovered.\n\n- **byBbox** — give a map bounding box (lat/lng) and an optional building-type vertical (simplest).\n- **bySearchUrl** — paste a ready-made peterpanz `houses/area/pc` API URL with your filters applied.\n- **byListingUrl** — fetch specific listings directly (DETAIL only).", "default": "byBbox" }, "bbox": { "title": "🗺️ Bounding box", "type": "string", "description": "🗺️ **BY BBOX:** Map bounding box as `lat_min,lat_max,lng_min,lng_max`. The default covers central Seoul (Gangnam). Draw any rectangle on a map app and read the corners.\n\n💡 **TIP:** Smaller boxes return denser, more relevant results.", "default": "37.49,37.52,127.01,127.05" }, "buildingType": { "title": "🏢 Building type", "enum": [ "", "villa", "apt", "officetel", "store" ], "type": "string", "description": "🏢 **BY BBOX:** Restrict to one vertical. Leave blank for all types.\n\n- `villa` = 빌라/주택 · `apt` = 아파트 · `officetel` = 오피스텔 · `store` = 상가/사무실.", "default": "" }, "orderBy": { "title": "↕️ Sort order", "enum": [ "price", "deposit", "random" ], "type": "string", "description": "↕️ Result sort. `price` (default) and `deposit` are deterministic — safe for stable pagination. `random` is the site UI default but reshuffles per call (causes duplicates/gaps across pages).", "default": "price" }, "search": { "title": "🔎 Keyword search", "type": "string", "description": "🔎 Optional free-text search term applied to the listing query." }, "searchUrls": { "title": "🔗 Search URLs", "type": "array", "description": "🔗 **BY SEARCH URL:** Paste one or more peterpanz `houses/area/pc` API URLs (the bbox + filters are recovered from the URL). Example — `https://api.peterpanz.com/houses/area/pc?filter=latitude:37.49~37.52||longitude:127.01~127.05&pageSize=50&pageIndex=1&order_by=price`.", "default": [ "https://api.peterpanz.com/houses/area/pc?filter=latitude:37.49~37.52||longitude:127.01~127.05&pageSize=50&pageIndex=1&order_by=price" ], "items": { "type": "string" } }, "listingUrls": { "title": "🏠 Listing URLs or IDs", "type": "array", "description": "🏠 **BY LISTING URL (DETAIL ONLY):** Paste peterpanz `/house/{id}` URLs or bare house ids (e.g. `https://www.peterpanz.com/house/19439182` or `19439182`). Used with scrapeMode = detail.", "items": { "type": "string" } }, "maxResults": { "title": "🔢 Max results", "minimum": 1, "type": "integer", "description": "🔢 Maximum listings to return per run. **FREE users:** capped at 25 · **PAID users:** unlimited.", "default": 100 }, "maxPages": { "title": "📄 Max pages", "minimum": 1, "type": "integer", "description": "📄 Maximum list-API pages to paginate per search before stopping (50 listings each).", "default": 5 }, "pageSize": { "title": "📦 Page size", "minimum": 1, "maximum": 50, "type": "integer", "description": "📦 Listings per API page (max 50).", "default": 50 }, "zoomLevel": { "title": "🔍 Map zoom level", "minimum": 1, "type": "integer", "description": "🔍 Map zoom level passed to the list API. Default 15.", "default": 15 }, "useProxy": { "title": "🌐 Use Korea residential proxy", "type": "boolean", "description": "🌐 Route requests through a South Korea residential proxy. **Off by default** — peterpanz's list API is ungated, so leaving this off keeps runs fast and cheap. Enable only if you hit a rate-limit or geo-block.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```