직방 크롤링 - klaus9267/locator GitHub Wiki

직방 크롤링 API 분석

📋 개요

직방의 매물 검색은 4가지 매물 유형으로 구성됩니다:

  • 아파트: 단지 기반 → 매물별 상세 조회
  • 빌라: 지역 기반 → ID 수집 → 일괄 상세 조회
  • 원룸: 지역 기반 → ID 수집 → 일괄 상세 조회
  • 오피스텔: 지역 기반 → ID 수집 → 일괄 상세 조회

🏢 아파트 검색 API

1. 아파트 목록 조회

GET https://apis.zigbang.com/apt/locals/{localCode}/item-catalogs

파라미터

파라미터 값 설명
tranTypeIn[0] trade 매매
tranTypeIn[1] charter 전세
tranTypeIn[2] rental 월세
includeOfferItem true 특가매물 포함
offset 0 페이징 시작점
limit 10 가져올 개수

예시

https://apis.zigbang.com/apt/locals/41465/item-catalogs?tranTypeIn[0]=trade&tranTypeIn[1]=charter&tranTypeIn[2]=rental&includeOfferItem=true&offset=0&limit=10

응답 구조

{
  "localCode": "41465",
  "count": 684,
  "list": [
    {
            "areaHoId": 5328954,
            "tranType": "charter",
            "itemType": "self_ad",
            "areaDanjiId": 692,
            "areaDanjiName": "현대",
            "danjiRoomTypeId": 1813,
            "local2": "용인시 수지구",
            "local3": "풍덕천동",
            "isPriceRange": false,
            "depositMin": 48000,
            "rentMin": 0,
            "roomTypeTitle": {
                "m2": "104",
                "p": "31"
            },
            "sizeContractM2": 104.52,
            "sizeM2": 84.51,
            "dong": "104동",
            "floor": "15",
            "itemTitle": "9월4일 입주, 전망 트인 집, 깔끔 부분수리,신혼부부추천",
            "zzimCount": 1,
            "isZzim": false,
            "isActualItemChecked": false,
            "thumbnailUrl": "https://ic.zigbang.com/ic/floorplan/692/1813/078a77dd3666421195edddcc09adbad6.png",
            "isFloorPlanThumbnail": true,
            "itemCount": 1,
            "itemIdList": [
                {
                    "itemSource": "zigbang",
                    "itemId": 45089630
                }
            ],
            "agentThumbnailUrls": [
                "https://ic.zigbang.com/vp/profile/24490076/27b641c6-b8fb-47d2-987b-8e06b3520ef6.jpg"
            ]
        },
  ]
}

2. 아파트 상세 정보 조회

GET https://www.zigbang.com/_next/data/{buildId}/home/apt/item-catalog.json

파라미터

파라미터 예시값 설명
areaHoId 4147633 매물 ID
tranType trade 거래유형 (trade/charter/rental)

예시

https://www.zigbang.com/_next/data/e8RgCa5EGUpkJvbRFfX8x/home/apt/item-catalog.json?areaHoId=4147633&tranType=trade

응답 구조

{
  "query": {
    "areaHoId": "9047351",
    "tranType": "trade"
  },
  "pageProps": {
    "meta": {
      "ogTitle": "'동천마을동문굿모닝힐3차' 매매 6억 9,000",
      "ogDescription": "동천역 도보10분 막힘없는 전망좋은 집",
      "ogImage": null
    }, 
    "itemCatalogHoInfo": {
      "areaDanjiId": 5892,
      "areaDanjiName": "동천마을동문굿모닝힐3차",
      "bcode": "4146510300",
      "local1": "경기도",
      "local2": "용인시 수지구",
      "local3": "동천동",
      "areaBuildingId": 192919,
      "danjiRoomTypeId": 34167,
      "areaHoId": 9047351,
      "danjiInfo": {
        "parkingCount": null,
        "parkingCountByHousehold": 0,
        "oldAddress": "경기도 용인시 수지구 동천동 858",
        "newAddress": "경기 용인시 수지구 동천로 93",
        "approvalDate": "20011107",
        "household": 181,
        "realType": "아파트",
        "areaDanjiDivision": "입주2년후",
        "is후분양": false,
        "danjiImage": "https://ic.zigbang.com/vp/BigData/5892/aabe6459c0464f2bcddf5366d102ed2e75a007b2.jpg",
        "zedStatus": "enabled",
        "webZedStatus": "enabled",
        "lat": 37.33820017254762,
        "lng": 127.09364910901
      },
      "hoInfo": {
        "dong": "302동",
        "buildingFloor": 25,
        "roomTypeTitle": {
          "m2": "105",
          "p": "32"
        },
        "sizeContractM2": 105.59,
        "sizeM2": 84.72,
        "roomCount": 3,
        "bathroomCount": 2,
        "direction": "s",
        "LandRatio": "32.38/7392",
        "landArea": 32.38,
        "totalLandArea": 7392,
        "floorPlanImageUrl": "https://ic.zigbang.com/ic/floorplan/5892/34167/64abb934cfeb47feb90e276c5a8bb125.png",
        "manageCost": {
          "yearManageCost": 28,
          "summerManageCost": 22,
          "winterManageCost": 37,
          "isHeatInclude": null
        },
        "공급면적": {
          "m2": "105.59",
          "p": "31.9"
        },
        "전용면적": {
          "m2": "84.72",
          "p": "25.6"
        }
      },
      "vrItems": [
        {
          "vrHouseKey": "spNCQfy6",
          "thumbnail": "https://ic.zigbang.com/vr/ap-northeast-2/houses/spNCQfy6/cover/medium/cover.jpg",
          "areaDanjiId": 5892,
          "areaBuildingName": "302동",
          "areaHoName": "1704호"
        }
      ],
      "priceInfo": {
        "publicPrices": [
          {
            "year": 2024,
            "price": 397000000,
            "comparePriceRate": 8.2
          },
        ],
        "zigbangPrice": {
          "areahoId": 9047351,
          "trade": {
            "price": 72000,
            "pyeongPrice": 2254
          },
          "charter": {
            "price": 45000,
            "pyeongPrice": 1409
          }
        },
        "hasRtPrices": true
      }
    },
    "itemCatalog": {
      "areaHoId": 9047351,
      "tranType": "trade",
      "depositMin": 69000,
      "depositMax": 69000,
      "rentMin": 0,
      "rentMax": 0,
      "floor": "24",
      "itemCount": 1,
      "items": [
        {
          "itemSource": "coalition",
          "itemId": 166910,
          "areaDanjiId": 5892,
          "areaDanjiName": "동천마을동문굿모닝힐3차",
          "areaDanjiDivision": "입주2년후",
          "areaBuildingId": 192919,
          "areaBuildingName": "302동",
          "areaHoId": 9047351,
          "itemType": "partner",
          "tranType": "trade",
          "deposit": 69000,
          "rent": 0,
          "moveinDate": "즉시입주가능",
          "floor": "24",
          "buildingFloor": 25,
          "direction": "s",
          "directionBase": "거실기준",
          "roomCount": 3,
          "bathroomCount": 2,
          "sizeContractM2": 105.59,
          "sizeM2": 84.72,
          "notificationComment": "고객이 집 내놓기 한 매물",
          "itemTitle": "동천역 도보10분 막힘없는 전망좋은 집",
          "itemDescription": "수리.필요해요",
          "effectivenessUpdatedAt": "2025-06-08T15:02:38+09:00",
          "tags": [],
          "imageUrls": [
            "https://ic.zigbang.com/vp/coalition-realestate/image/customers/3516752/789089b279422c1bdd02399d3ddd7b6f2bc0687edcf3e3b0072174ae9707526b",
            "https://ic.zigbang.com/vp/coalition-realestate/image/customers/3516752/ba5d309c6965e40716c6671b66c2c9f4f35c71d8df7a4ca733e63c4a09e4f623"
          ],
          "manageCost": {
            "type": "unconfirmed",
            "unconfirmedReason": "해당 매물은 고객이 관리비 내역을 확인 중입니다."
          },
          "zzimCount": 0,
          "isActualItemChecked": true,
          "agent": {
            "agentType": "partners",
            "userNo": 1251,
            "name": "박재선",
            "profileUrl": "https://ic.zigbang.com/vp/coalition-realestate/user/profile/danji/1251/31a1b2d74bf481b99d1d7821eb7cf21ac8edb037deb6cc1dab10ad41d244b69e.jpeg",
            "phone": "01041042203",
            "itemCount": 0,
            "itemCountPerTranType": {
              "charter": 0,
              "rental": 0,
              "trade": 0
            }
          },
          "acceptedLocalAgents": [
            {
              "name": "삼성타운 공인중개사사무소",
              "nsdiOfficeId": 33016,
              "status": "영업중",
              "distance": 0.28860112833507645,
              "ownerName": "유현주",
              "address": "경기도 용인시 수지구 동천로113번길 10 ,상가동 23호(동천동, 한빛마을래미안이스트팰리스2단지아파트)"
            },
          ],
          "roomTypeInfo": {
            "danjiRoomTypeId": 34167,
            "floorPlanImageUrl": "https://ic.zigbang.com/ic/floorplan/5892/34167/64abb934cfeb47feb90e276c5a8bb125.png",
            "roomTypeTitle": {
              "m2": "105",
              "p": "32"
            }
          }
        }
      ],
      "acceptedLocalItemId": 166910,
      "acceptedLocalAgents": [
        {
          "name": "삼성타운 공인중개사사무소",
          "nsdiOfficeId": 33016,
          "status": "영업중",
          "distance": 0.28860112833507645,
          "ownerName": "홍길동",
          "address": "경기도 용인시 수지구 동천로113번길 10 ,상가동 23호(동천동, 한빛마을래미안이스트팰리스2단지아파트)"
        },
      ]
    }
  },
  "__N_SSP": true
}

🏘️ 빌라 검색 API (2단계 방식)

1단계: 지역별 매물 ID 수집

GET https://apis.zigbang.com/v2/items/villa

파라미터

파라미터 예시값 설명
geohash wydk 지역 해시코드
salesTypes[0] %EC%A0%84%EC%84%B8 전세 (URL 인코딩)
salesTypes[1] %EC%9B%94%EC%84%B8 월세 (URL 인코딩)
salesTypes[2] %EB%A7%A4%EB%A7%A4 매매 (URL 인코딩)
lngEast 127.1521063223339 동쪽 경도
lngWest 127.0354714009278 서쪽 경도
latSouth 37.322114258081115 남쪽 위도
latNorth 37.33283419206626 북쪽 위도
domain zigbang 도메인

Geohash 패턴

wydk    # 기본 지역
wydkk   # 세분화된 지역 1
wydk6   # 세분화된 지역 2
wydkm   # 세분화된 지역 3
wydk7   # 세분화된 지역 4

예시 URL

https://apis.zigbang.com/v2/items/villa?geohash=wydk&depositMin=0&rentMin=0&salesTypes[0]=%EC%A0%84%EC%84%B8&salesTypes[1]=%EC%9B%94%EC%84%B8&salesTypes[2]=%EB%A7%A4%EB%A7%A4&salesPriceMin=0&lngEast=127.1521063223339&lngWest=127.0354714009278&latSouth=37.322114258081115&latNorth=37.33283419206626&domain=zigbang&checkAnyItemWithoutFilter=true

응답 구조

{
  "items": [
    {
      "lat": 37.324127197265625,
      "lng": 127.09873962402344,
      "itemId": 45080972,
      "itemBmType": "ZIGBANG"
    }
  ]
}

2단계: 매물 상세 정보 일괄 조회

POST https://apis.zigbang.com/v2/items/list
Content-Type: application/json

요청 Body

{
  "item_ids": [
    45020839,
    45077032,
    45076194,
    44892715,
    45107584
  ],
  "domain": "zigbang"
}

응답 구조

{
  "items": [
    {
      "item_id": 45080972,
      "sales_type": "월세",
      "deposit": 4000,
      "rent": 30,
      "size_m2": 56.2,
      "title": "수지구청역5분거리의 넓고 깔끔한 투룸",
      "address": "용인시 수지구 풍덕천동"
    }
  ]
}

🏠 원룸 검색 API (2단계 방식)

1단계: 지역별 매물 ID 수집

GET https://apis.zigbang.com/v2/items/oneroom

파라미터

파라미터 예시값 설명
geohash wydjr 지역 해시코드
roomTypes[0] %EB%B3%B5%EC%B8%B5%ED%98%95%EC%9B%90%EB%A3%B8 복층형원룸 (URL 인코딩)
salesTypes[0] %EC%A0%84%EC%84%B8 전세 (URL 인코딩)
salesTypes[1] %EC%9B%94%EC%84%B8 월세 (URL 인코딩)
rentMax 250 월세 상한
lngEast 126.90536809798569 동쪽 경도
lngWest 126.8760163604908 서쪽 경도
latSouth 37.495284634588394 남쪽 위도
latNorth 37.49882571686236 북쪽 위도
domain zigbang 도메인

예시 URL

https://apis.zigbang.com/v2/items/oneroom?geohash=wydjr&depositMin=0&rentMin=0&rentMax=250&roomTypes[0]=%EB%B3%B5%EC%B8%B5%ED%98%95%EC%9B%90%EB%A3%B8&salesTypes[0]=%EC%A0%84%EC%84%B8&salesTypes[1]=%EC%9B%94%EC%84%B8&lngEast=126.90536809798569&lngWest=126.8760163604908&latSouth=37.495284634588394&latNorth=37.49882571686236&domain=zigbang&checkAnyItemWithoutFilter=true

응답 구조

{
  "items": [
    {
      "lat": 37.496131896972656,
      "lng": 126.88968658447266,
      "itemId": 45010031,
      "itemBmType": "ZIGBANG"
    }
  ]
}

2단계: 매물 상세 정보 일괄 조회

POST https://apis.zigbang.com/v2/items/list
Content-Type: application/json

요청 Body

{
  "item_ids": [45010031, 45075818],
  "domain": "zigbang"
}

응답 구조 (원룸)

{
  "items": [
    {
      "item_id": 45010031,
      "sales_type": "월세",
      "deposit": 1000,
      "rent": 60,
      "size_m2": 56.33,
      "전용면적": {"m2": 29.4, "p": "8.9"},
      "floor": "8",
      "building_floor": "15",
      "title": "깔끔복층오피ㅁ 방크기 최고ㅁ 빌트인냉장고 완비ㅁ",
      "room_type": "03",
      "service_type": "오피스텔",
      "address": "구로구 구로동"
    }
  ]
}

🏢 오피스텔 검색 API (2단계 방식)

1단계: 지역별 매물 ID 수집

GET https://apis.zigbang.com/v2/items/officetel

파라미터

파라미터 예시값 설명
geohash wydjr 지역 해시코드
salesTypes[0] %EC%A0%84%EC%84%B8 전세 (URL 인코딩)
salesTypes[1] %EC%9B%94%EC%84%B8 월세 (URL 인코딩)
salesTypes[2] %EB%A7%A4%EB%A7%A4 매매 (URL 인코딩)
lngEast 126.90563245553034 동쪽 경도
lngWest 126.87629854615957 서쪽 경도
latSouth 37.48874362105286 남쪽 위도
latNorth 37.5044301828988 북쪽 위도
domain zigbang 도메인
checkAnyItemWithoutFilter true 필터 없이 전체 매물 확인

예시 URL

https://apis.zigbang.com/v2/items/officetel?depositMin=0&rentMin=0&salesTypes%5B0%5D=%EC%A0%84%EC%84%B8&salesTypes%5B1%5D=%EC%9B%94%EC%84%B8&salesTypes%5B2%5D=%EB%A7%A4%EB%A7%A4&salesPriceMin=0&lngEast=126.90563245553034&lngWest=126.87629854615957&latSouth=37.48874362105286&latNorth=37.5044301828988&geohash=wydjr&domain=zigbang&checkAnyItemWithoutFilter=true

응답 구조

{
  "items": [
    {
      "lat": 37.4971733093262,
      "lng": 126.891380310059,
      "itemId": 45112255,
      "itemBmType": "ZIGBANG"
    }
  ]
}

2단계: 매물 상세 정보 일괄 조회

POST https://apis.zigbang.com/v2/items/list
Content-Type: application/json

요청 Body

{
  "item_ids": [
    45112255,
    45032411,
    45083239,
    45114697,
    44988995
  ],
  "domain": "zigbang"
}

응답 구조 (오피스텔)

{
  "items": [
    {
      "item_id": 45112255,
      "sales_type": "월세",
      "deposit": 1000,
      "rent": 55,
      "size_m2": 21,
      "공급면적": {"m2": 21, "p": "6.4"},
      "전용면적": {"m2": 17.19, "p": "5.2"},
      "floor": "중",
      "building_floor": "16",
      "title": "1000에55 채광좋음 전입가능",
      "room_type": "01",
      "service_type": "오피스텔",
      "address": "구로구 구로동",
      "manage_cost": "8"
    }
  ]
}