{
  "openapi": "3.0.1",
  "info": {
    "title": "serve Property Scraper — Korea Real Estate Data & API",
    "description": "serve.co.kr (부동산써브) scraper & Korea real estate data API. Sale, jeonse & monthly-rent listings: price, deal type, area, rooms, floor, direction, geo, agency contact, cross-portal ids — clean JSON/CSV, one row per listing. Fast overview or full detail. No account needed. 부동산써브 매물 데이터·부동산 API.",
    "version": "1.0",
    "x-build-id": "mg5MgJOmxLDhDE7XX"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~serve-property-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-serve-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~serve-property-scraper/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-serve-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~serve-property-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-serve-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 serve's listing API — already ~85% complete with price, deal type, category, areas, rooms, floor, geo, agency contact and cross-portal ids.\n\n🔎 **DETAIL** (enrich): also fetches each listing's full record — parking, heating, households, building approval date and the full street address. Detail merges overview + detail into one record.",
            "default": "overview"
          },
          "searchMode": {
            "title": "🔀 Search mode",
            "enum": [
              "byLdong",
              "bySearchUrl",
              "byCrawl",
              "byArticleId"
            ],
            "type": "string",
            "description": "🔀 How listings are discovered.\n\n- **byLdong** — give one or more legal-dong codes (ldongCd).\n- **bySearchUrl** — paste a serve.co.kr listing URL that carries an `ldongCd` param.\n- **byCrawl** — automatically sweep a region (Seoul metro by default) and visit every neighbourhood with listings.\n- **byArticleId** — fetch specific listings directly as `atclNo:CATEGORY` (DETAIL only).",
            "default": "byLdong"
          },
          "ldongCodes": {
            "title": "📍 Legal-dong codes",
            "type": "array",
            "description": "📍 **BY LEGAL-DONG:** One or more legal-dong codes (ldongCd) to list. Example: `4113511100` = 분당 금곡동, `1168010600` = 강남 대치동.\n\n💡 **TIP:** Find an ldongCd by opening a neighbourhood on serve.co.kr's map and copying the `ldongCd` from the listing request, or use the **By region crawl** mode to discover them automatically.",
            "default": [
              "4113511100"
            ],
            "items": {
              "type": "string"
            }
          },
          "searchUrls": {
            "title": "🔗 Search URLs",
            "type": "array",
            "description": "🔗 **BY SEARCH URL:** Paste one or more serve.co.kr listing URLs that include an `ldongCd` query parameter. Any supported serve filter present in the URL is preserved.\n\n💡 **TIP:** Example — `https://www.serve.co.kr/good/v1/map/getAtclList?ldongCd=4113511100`",
            "items": {
              "type": "string"
            }
          },
          "articleIds": {
            "title": "🏠 Article ids",
            "type": "array",
            "description": "🏠 **BY ARTICLE ID (DETAIL ONLY):** Specific listings as `atclNo:CATEGORY` pairs — the category code is required by serve's detail API. Example: `333750957:OFT`. Bare ids work if you set **Category** to a single code (OFT / APT / RED / LOT).\n\n💡 Category codes: OFT = officetel, APT = apartment, RED = house/villa, LOT = presale.",
            "items": {
              "type": "string"
            }
          },
          "category": {
            "title": "🏷️ Category",
            "type": "string",
            "description": "🏷️ Property group filter (overview), or the detail category code for bare article ids.\n\n- Friendly groups: `apt` (아파트), `officetel` (오피스텔), `house` (주택/빌라), `presale` (분양권), `all`.\n- Single detail codes: `OFT`, `APT`, `RED`, `LOT`.\n\nLeave blank for all categories."
          },
          "order": {
            "title": "↕️ Sort order",
            "type": "string",
            "description": "↕️ Result sort order: `default`, `newest`, `price`, `area` (or serve's numeric `orderCd`). Leave blank for the default order."
          },
          "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
          },
          "maxRecordsPerDong": {
            "title": "📄 Max records per neighbourhood",
            "minimum": 1,
            "type": "integer",
            "description": "📄 Maximum listings to pull from a single legal-dong before moving on.",
            "default": 60
          },
          "maxDongs": {
            "title": "🗺️ Max neighbourhoods (crawl)",
            "minimum": 1,
            "type": "integer",
            "description": "🗺️ **BY REGION CRAWL:** Maximum neighbourhoods (legal-dongs) to visit during a region sweep.",
            "default": 5
          },
          "minArticles": {
            "title": "🔢 Min listings per neighbourhood (crawl)",
            "minimum": 1,
            "type": "integer",
            "description": "🔢 **BY REGION CRAWL:** Skip neighbourhoods with fewer than this many listings.",
            "default": 1
          },
          "drcCdListStr": {
            "title": "🧭 Direction filter",
            "type": "string",
            "description": "🧭 serve's direction filter (`drcCdListStr`), carried verbatim."
          },
          "maxHhcnt": {
            "title": "🏘️ Max households",
            "type": "string",
            "description": "🏘️ serve's max-households filter (`maxHhcnt`), carried verbatim."
          },
          "maxCmplxUseAprvDt": {
            "title": "📅 Max approval date",
            "type": "string",
            "description": "📅 serve's max use-approval-date filter (`maxCmplxUseAprvDt`), carried verbatim."
          },
          "floorExpsrListStr": {
            "title": "🏬 Floor exposure filter",
            "type": "string",
            "description": "🏬 serve's floor-exposure filter (`floorExpsrListStr`), carried verbatim."
          },
          "useProxy": {
            "title": "🌐 Use Korea residential proxy",
            "type": "boolean",
            "description": "🌐 Route requests through a Korea residential proxy. **Off by default** — serve.co.kr's listing APIs are reachable without a proxy, 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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}