{ "openapi": "3.0.1", "info": { "title": "KB Land Korea Apartment Price API – KB부동산 시세, Jeonse, Deals", "description": "South Korea real estate API for KB Land (KB부동산, kbland.kr), no login: apartment prices (official KB 시세 sale/jeonse/rent per unit type), real transactions, listing counts, 20-year monthly history, Seoul and district averages. KB시세·실거래가·전세가율. $6/1K complexes, 50 free/month.", "version": "0.2", "x-build-id": "4qcFKwhJENX38iOUA" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/k-data-lab~kbland-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-k-data-lab-kbland-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/k-data-lab~kbland-scraper/runs": { "post": { "operationId": "runs-sync-k-data-lab-kbland-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/k-data-lab~kbland-scraper/run-sync": { "post": { "operationId": "run-sync-k-data-lab-kbland-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": { "mode": { "title": "모드", "enum": [ "complexes", "regions" ], "type": "string", "description": "\"complexes\"(기본값) 또는 \"regions\". 예: 특정 아파트 시세는 \"complexes\", 구·동 평균 시세는 \"regions\". 단지 KB시세 = 단지별 평형 KB시세(매매·전세·월세 하한/일반/상한), 단지 정보, 매물 건수, 최근 실거래가. 지역 시세 = 시도·시군구·읍면동의 평균 매매가·전세가, 평당가, 전세가율, 주간·월간 변동률, 실거래 건수, 순위. (EN: \"complexes\" (default) = KB 시세 (sale/jeonse/rent, low/general/high) per unit type, specs, listing counts and last deals for specific apartment complexes; \"regions\" = average sale/jeonse prices, jeonse ratio and weekly/monthly change for Korean provinces, districts or neighbourhoods.)", "default": "complexes" }, "searchKeywords": { "title": "단지명 검색어", "type": "array", "description": "KB부동산 검색창처럼 단지명·브랜드로 찾습니다. 예: 은마, 래미안, 헬리오시티. 검색어마다 최대 1,000개 단지까지 (최대 단지 수 설정에 따라 멈춤). complexes 모드 전용. 비워 두면 검색하지 않습니다. (EN: apartment complex names in Korean as typed on KB Land, e.g. [\"은마\"] for Eunma, [\"헬리오시티\"] for Helio City, [\"래미안\"] for a brand; romanized names may not match. Exact-name matches come first, larger complexes first.)", "items": { "type": "string" } }, "complexIds": { "title": "단지 ID 또는 URL", "type": "array", "description": "KB부동산 단지기본일련번호(예: 1374) 또는 단지 페이지 주소(예: https://kbland.kr/c/1374). 결과의 complexId를 다시 넣으면 정기 모니터링에 쓸 수 있습니다. 비워 두면 건너뜁니다. 예: [\"1374\"]. (EN: KB Land complex IDs or kbland.kr/c/ URLs, e.g. [\"186\"] = Eunma; reuse complexId from earlier results for scheduled monitoring.)", "default": [], "items": { "type": "string" } }, "regions": { "title": "지역 (해당 지역의 모든 단지)", "type": "array", "description": "시군구 또는 읍면동 이름. 예: 강남구 대치동, 성남시 분당구, 마포구, 반포동. 같은 이름이 여러 곳이면 상위 지역을 앞에 붙여 주세요(예: 서울 중구). 10자리 법정동코드도 됩니다. complexes 모드 전용. 비워 두면 건너뜁니다. (EN: every complex in a Korean district or neighbourhood, written in Korean, e.g. [\"강남구 대치동\"] = Daechi-dong, Gangnam-gu, [\"서울 중구\"]; or a 10-digit legal-dong code. Largest complexes first.)", "default": [], "items": { "type": "string" } }, "popularTop": { "title": "KB부동산 인기 단지 TOP N", "minimum": 0, "maximum": 100, "type": "integer", "description": "KB부동산 실시간 조회수 순위 상위 N개 단지(0~100). 0이면 사용하지 않습니다. 예: 10 = 지금 가장 많이 조회된 10개 단지. (EN: top N complexes by live views on KB Land (0-100); 0 = off.)", "default": 0 }, "propertyTypes": { "title": "단지 종류", "type": "array", "description": "검색·지역·인기 단지 결과에서 남길 종류. 단지 ID로 직접 넣은 단지는 항상 가져옵니다. \"아파트\", \"주상복합\", \"오피스텔\" 중 여러 개. 예: [\"아파트\"] = 아파트만 (기본값은 셋 다). (EN: property types to keep: 아파트 = apartment, 주상복합 = mixed-use apartment, 오피스텔 = officetel. Example: [\"아파트\"] for apartments only.)", "items": { "type": "string", "enum": [ "아파트", "주상복합", "오피스텔" ], "enumTitles": [ "아파트", "주상복합", "오피스텔" ] }, "default": [ "아파트", "주상복합", "오피스텔" ] }, "maxComplexes": { "title": "최대 단지 수", "minimum": 1, "maximum": 10000, "type": "integer", "description": "이번 실행에서 가져올 최대 단지 수(모든 입력 합계). 결과 1건 = 단지 1개(모든 평형 포함). 예: 3 = 빠른 시험, 100 = 지역 전체 조사. (EN: max complexes per run across all inputs; one result = one complex with all unit types. 3 = quick test (default prefill), 100 = whole neighbourhood. The first 50 complexes each month are free.)", "default": 20 }, "includeDeals": { "title": "평형별 최근 실거래가·매물 평균가 포함", "type": "boolean", "description": "평형마다 최근 매매·전세 실거래가(금액·계약일·층), 전세 시세 하한/상한, KB 평균가, 매물 평균 호가를 붙입니다. 추가 요금 없음 (평형 수만큼 요청이 늘어 조금 느려집니다). 예: 호가만 빠르게 보려면 false, 실거래가가 필요하면 true(기본값). (EN: add the latest real sale/jeonse transaction (price, date, floor) and average asking price per unit type; no extra charge.)", "default": true }, "includePriceHistory": { "title": "KB시세 월별 추이 포함 (유료 추가 항목)", "type": "boolean", "description": "평형마다 지난 N년의 월별 KB시세(매매·전세 하한/일반/상한, 월세)를 priceHistory 배열로 붙입니다. 단지당 price-history 이벤트가 추가로 과금됩니다. 예: 최근 3년 월별 시세 추이 차트가 필요하면 true (historyYears와 함께). (EN: add monthly KB price history per unit type (priceHistory array); charged as one extra price-history event per complex.)", "default": false }, "historyYears": { "title": "추이 기간 (년)", "minimum": 1, "maximum": 20, "type": "integer", "description": "KB시세 추이를 몇 년치 가져올지 (올해 포함, 1~20). 예: 3(기본값), 10 = 10년치. includePriceHistory가 true일 때만 쓰입니다. (EN: years of monthly history, 1-20 (default 3); used only when includePriceHistory is true.)", "default": 3 }, "oneRowPerUnitType": { "title": "평형마다 한 줄로 펼치기", "type": "boolean", "description": "켜면 평형(면적)마다 한 줄이 되고 단지 정보가 각 줄에 반복됩니다. 엑셀·구글시트에 바로 쓰기 좋습니다. 과금은 그대로 단지 1개당 1건입니다. 예: 시트에 평형별로 펼치려면 true, 단지당 1행(평형은 배열)은 false(기본값). (EN: one dataset row per unit type (spreadsheet-friendly) instead of one row per complex; billing stays one event per complex.)", "default": false }, "regionLevel": { "title": "지역 단위", "enum": [ "sido", "sigungu", "dong" ], "type": "string", "description": "지역 시세 모드에서 가져올 단위. 읍면동은 아래 '지역 필터'에 시군구(또는 시도) 이름이 필요합니다. \"sido\" = 시도, \"sigungu\" = 시군구(기본값), \"dong\" = 읍면동. 예: 서울 구별 비교는 \"sigungu\" + regionFilter [\"서울\"]. regions 모드 전용. (EN: \"sido\" = 16 provinces, \"sigungu\" = ~250 districts (default), \"dong\" = neighbourhoods inside the districts named in regionFilter. Example for Seoul districts: \"sigungu\" + regionFilter [\"서울\"].)", "default": "sigungu" }, "regionFilter": { "title": "지역 필터", "type": "array", "description": "이 이름이 들어간 지역만 남깁니다. 예: 서울, 경기 성남시, 강남구. 비우면 전국. regions 모드 전용. 예: [\"서울\"] = 서울 시군구만. (EN: keep only regions whose name contains one of these Korean names, e.g. [\"서울\"] = Seoul's 25 districts; empty = nationwide.)", "default": [], "items": { "type": "string" } }, "regionPropertyType": { "title": "지역 시세 대상", "enum": [ "apartment", "officetel", "both" ], "type": "string", "description": "지역 평균을 계산할 주택 종류. \"apartment\" = 아파트(기본값), \"officetel\" = 오피스텔, \"both\" = 둘 다. 예: \"both\". regions 모드 전용. (EN: \"apartment\" (default), \"officetel\" or \"both\".)", "default": "apartment" }, "maxRegions": { "title": "최대 지역 수", "minimum": 1, "maximum": 5000, "type": "integer", "description": "지역 시세 모드에서 가져올 최대 지역 수. 예: 1000(기본값) = 사실상 전부, 25 = 상위 25개 지역만. regions 모드 전용. (EN: maximum regions to return (default 1000 = all).)", "default": 1000 }, "proxyConfiguration": { "title": "프록시", "type": "object", "description": "보통은 필요 없습니다(직접 연결, 막히면 자동으로 Apify Proxy 사용). 예: {\"useApifyProxy\": false} (기본값 그대로 두면 됩니다). (EN: usually not needed; the actor connects directly and switches to Apify Proxy automatically if blocked.)", "default": { "useApifyProxy": 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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }