홈디포 API로 상품 검색부터 매장 재고까지 받아 보세요

홈디포 상품 데이터가 필요하면 /v1/home_depot/의 GET 엔드포인트 네 개로 받아요. 키워드 검색, UPC와 매장별 재고가 담긴 상품 상세, 리뷰, 우편번호로 찾는 매장 조회예요. API 키 하나로 부르고 응답 형식도 다른 /v1 엔드포인트와 같아요.

요청 헤더에는 x-api-key를 넣어요. 파라미터 전체는 Home Depot 플랫폼 문서에 있어요.

홈디포 상품은 키워드로 어떻게 검색하나요?

GET /v1/home_depot/search에 query를 넣으면 한 페이지에 24개씩 와요. 행마다 상품 id, 제목, 브랜드, 가격, 평점, 리뷰 수, 이미지, 재고 상태가 들어 있어요. total은 실제 검색 결과 수예요. 더 넘기려면 page(1부터 30까지)를 쓰세요. 재고를 매장 기준으로 보려면 store_id를 붙여요.

curl -sS "https://www.socialcrawl.dev/v1/home_depot/search?query=paver" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

{
  "product": {
    "id": "100333077",
    "title": "12 in. x 12 in. x 1.5 in. Pewter Square Concrete Step Stone",
    "url": "https://www.homedepot.com/p/.../100333077",
    "price": { "current": 1.87, "original": 1.87, "currency": "USD" },
    "rating": { "average": 4.6, "count": 12904 },
    "reviews_count": 12904,
    "availability": "InStock"
  }
}

상품 id는 홈디포 상품 주소 끝의 숫자예요. 이 id를 상세와 리뷰 엔드포인트에 넣어요. 다음 페이지는 pagination.has_more가 true인 동안 넘기면 돼요.

검색에는 정렬이나 필터 파라미터가 없어요. sort_by, items_per_page, brand, min_price, max_price, in_stock, zipcode를 붙이면 파라미터 이름을 짚어서 400을 돌려주고 크레딧은 0이에요. 정렬과 필터는 받은 행에서 직접 하세요. 모든 행에 price.current, brand, rating, availability가 있어요.

홈디포 상품 상세에서 UPC와 매장 재고도 오나요?

와요. GET /v1/home_depot/product에 item_id나 상품 url을 넣으면 제목, 브랜드, 모델 번호, UPC, 설명, 특징, 현재가와 정가, 평점, 이미지, 재고가 한 번에 와요. 재고는 product.ext.store_inventory에 있어요. 상품을 내줄 위치마다 수량이 한 행씩 들어 있어요.

curl -sS "https://www.socialcrawl.dev/v1/home_depot/product?item_id=326680222&store_id=0256" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

{
  "product": {
    "id": "326680222",
    "brand": "RYOBI",
    "price": { "current": 49.97, "original": 49.97, "currency": "USD" },
    "availability": "InStock",
    "ext": {
      "store_inventory": [
        {
          "store_id": "0256",
          "store_name": "Stadium",
          "state": "FL",
          "in_stock": true,
          "quantity": 34,
          "fulfillment": "pickup",
          "service": "bopis",
          "location_type": "store",
          "is_selected_store": true
        },
        {
          "store_id": "0121",
          "in_stock": true,
          "quantity": 79,
          "fulfillment": "delivery",
          "service": "express delivery",
          "is_selected_store": false
        }
      ]
    }
  }
}

store_inventory의 한 행이 꼭 매장 하나는 아니에요. 수령 방식마다 행이 따로 있어요. 수량을 매장 재고로 읽기 전에 fulfillment(pickup 또는 delivery)와 location_type(store 또는 online)부터 보세요. is_selected_store가 true인 행이 store_id로 넘긴 매장이에요. 매장 번호는 문자열로 비교하세요. 배송 거점 번호가 매장 번호와 겹칠 때가 있어서 0121은 121번 매장이 아니에요.

가격은 홈디포 온라인 가격이라 매장마다 달라지지 않아요. 매장에서만 붙는 할인도 데이터에 없어요. 홈디포가 온라인에 공개한 할인은 ext.promotion에 라벨, amount_off, percent_off로 들어와요. 가격을 홈디포가 감춘 상품은 price.current가 null이고 이유가 ext.price_note에 있어요.

응답은 다른 쇼핑몰 상품 엔드포인트와 같은 통합 Product 형식이에요. 아마존 상품 데이터 API 비교(영문)에 나온 응답과 같은 파서로 읽어요.

홈디포 리뷰 API는 한 번에 무엇을 주나요?

GET /v1/home_depot/reviews는 item_id를 받아서 관련도 높은 리뷰 10개를 5크레딧에 줘요. 한 페이지가 전부라서 넘길 커서는 없어요. total에는 상품의 전체 리뷰 수가 들어 있어요. 여기서 열 개를 뺀 만큼이 받지 못한 리뷰예요.

curl -sS "https://www.socialcrawl.dev/v1/home_depot/reviews?item_id=100333077" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

{
  "review": {
    "id": "306350952",
    "text": "The majority of the 70 pavers were good but two had concrete bumps on their surfaces.",
    "rating": { "value": 4, "max": 5 },
    "author": { "name": "KIP", "location": null },
    "helpful_votes": 0,
    "verified": true,
    "language": "en_US",
    "published_at": "2026-09-04T01:04:17.000Z"
  }
}

리뷰마다 본문, 5점 만점 평점, 작성자, 도움이 됐다는 투표 수, 구매 인증 여부, 작성 시각이 있어요. computed.labels에는 감정과 이슈 유형 라벨도 기본으로 붙고 추가 크레딧은 없어요. 채점 방식은 라벨 문서에 있어요.

리뷰 응답의 전체 수와 상품 행의 reviews_count는 조금 다르기도 해요. 서로 다른 응답에서 온 숫자니까 각각 그 응답의 기준으로 읽으세요.

우편번호로 홈디포 store id를 어떻게 찾나요?

GET /v1/home_depot/stores?query=95032처럼 다섯 자리 미국 우편번호를 넣으면 가까운 순으로 매장이 와요. 1크레딧이에요. 매장마다 id, 이름, 주소, 전화번호, 좌표, 매장 페이지 주소가 들어 있어요. 이 id가 검색과 상세에 넣는 store_id예요.

curl -sS "https://www.socialcrawl.dev/v1/home_depot/stores?query=95032" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

{
  "place": {
    "id": "1009",
    "name": "Hillsdale",
    "address": "1855 Hillsdale Ave, San Jose, CA 95124",
    "phone": "(408)978-6807",
    "latitude": 37.263343,
    "longitude": -121.921355,
    "url": "https://www.homedepot.com/l/Hillsdale/CA/San-Jose/95124/1009"
  }
}

특정 지역의 재고를 보는 순서는 세 단계예요. 우편번호로 store_id를 받고 상세에 item_id와 store_id를 같이 넣은 다음 is_selected_store가 true인 행을 읽어요. store_id에는 매장 조회가 준 문자열을 앞의 0까지 그대로 넣으세요. 없는 매장 번호는 거절돼요.

홈디포 API가 못 하는 것은 무엇인가요?

• 카테고리 탐색은 안 돼요. GET /v1/home_depot/category는 데이터 소스를 다시 연결하는 동안 내려 둔 상태라서 503을 돌려주고 크레딧은 0이에요. item id는 키워드 검색으로 찾으세요.
• 서버 쪽 정렬과 필터는 없어요. 받은 행에서 직접 거르세요.
• 매장별 가격은 없어요. 재고는 store_id로 좁혀지지만 가격은 온라인 가격이에요.
• 리뷰는 한 번에 10개예요. 관련도가 높은 순서의 한 페이지가 전부예요.

오류 응답에는 오류 문서로 가는 doc_url이 들어 있어요. 우리 쪽 문제로 실패한 호출은 크레딧이 환불돼요.

어떻게 시작하나요?

가입해서 API 키를 받으세요. 무료 크레딧이 같이 들어와요. 위의 검색 호출로 data 구조를 눈으로 확인하고 나서 파서를 쓰세요. 결과에서 item_id를 하나 골라 상세와 리뷰를 부르면 돼요. 코드를 쓰기 전에 응답 모양을 보고 싶다면 익스플로러를 열어 보세요.

자주 묻는 질문

홈디포 공식 상품 API가 있나요?

누구나 가입해서 쓰는 공개 API는 찾지 못했어요. SocialCrawl은 홈디포와 관계없는 독립 서비스이고 홈디포 파트너 프로그램에도 속해 있지 않아요. /v1/home_depot/는 검색, 상품 상세, 리뷰, 매장 조회를 따로 쓰는 셀프서비스 API예요.

홈디포 API 호출은 크레딧이 얼마인가요?

검색, 상품 상세, 리뷰는 호출당 5크레딧이에요. 매장 조회는 1크레딧이에요. 지원하지 않는 필터처럼 가져오기 전에 거절된 요청은 0크레딧이에요. 전체 표는 엔드포인트별 크레딧에 있어요.

매장별 재고와 현지 구매 가능 여부도 나오나요?

나와요. 매장 조회 엔드포인트에서 store_id를 받아 상세에 넣으세요. 재고는 product.ext.store_inventory에 있어요. is_selected_store가 true인 행이 지정한 매장이에요. 가격은 매장마다 다르지 않아요.

우편번호로 홈디포 store id를 어떻게 찾나요?

GET /v1/home_depot/stores?query=<우편번호>를 1크레딧에 호출하세요. 돌아온 매장의 id가 검색과 상세에 넣는 store_id예요.

브랜드, 가격, 정렬 필터는 왜 400이 나오나요?

검색 소스가 지원하지 않는 파라미터는 조용히 무시하지 않고 이름을 짚어 거절해요. 거절되는 건 sort_by, items_per_page, brand, min_price, max_price, in_stock, zipcode예요. 검색이 받는 건 query, page, store_id뿐이에요. price.current, brand, rating, availability로 받은 행을 직접 거르세요.

홈디포 카테고리 탐색도 API로 되나요?

안 돼요. GET /v1/home_depot/category는 데이터 소스를 다시 연결하는 동안 내려 둔 상태라서 503을 돌려주고 크레딧은 0이에요. 대신 /v1/home_depot/search의 키워드 검색을 쓰세요.