Facebook Marketplace Item
Facebook Marketplace 상품은 제목, 설명, 판매자 정보, 가격, 위치, 사진, 속성, 배송 옵션, 판매 가능 여부 신호를 담은 공개 판매 상품입니다. 이러한 필드는 선택한 판매 상품의 정보 보강, 가격·상태 확인, 상품 비교, 특정 시점 기록 보관에 활용할 수 있습니다.
Facebook Marketplace Item API 주요 기능
- 알고 있는 상품 URL 입력facebook.com, www.facebook.com, m.facebook.com, web.facebook.com 중 한 곳의 /marketplace/item/{numeric_id}로 시작하는 공개 경로를 처리하며, 제출한 판매 상품으로만 수집 범위를 한정합니다.
- 정규화된 판매 상품 상세판매 상품 식별 정보, 제목, 설명, 판매자 정보, 가격, 위치, 이미지, 속성, 배송 값, 타임스탬프, 공개되는 경우 판매 가능 여부 필드를 반환합니다.
- 독립적인 배치 처리유효한 URL을 각각 독립적으로 처리하고 URL당 최대 1건의 판매 상품을 반환하므로, 조회할 수 없는 상품이 있어도 나머지 입력의 처리는 중단되지 않습니다.
- 공개 데이터 범위 명시공개된 판매 상품에 노출되지 않는 필드는 임의의 값을 만들어 채우지 않고, 출처에 따라 달라지는 판매자, 위치, 미디어, 속성, 배송, 상태 값을 null 가능 값으로 유지합니다.
Facebook Marketplace Item API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
urls | 필수 | 공개 Facebook Marketplace 상품 URL의 목록으로, 비어 있지 않아야 하는 필수 값입니다. 허용되는 호스트는 facebook.com, www.facebook.com, m.facebook.com, web.facebook.com이며, 각 경로는 /marketplace/item/{numeric_id}로 시작해야 합니다. |
Facebook Marketplace Item API 사용 방법
알고 있는 공개 Marketplace 상품 URL을 제출하고, 비동기 작업을 추적한 뒤, 정규화된 판매 상품 레코드를 커서 페이지네이션으로 읽습니다.
- 경로가 /marketplace/item/{numeric_id}로 시작하는 공개 Facebook Marketplace URL을 하나 이상 준비합니다.
- 링크를 urls로 /v1/facebook-marketplace/item에 제출하고, task_id를 확보합니다.
- 처리가 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽고, has_more가 true인 동안에는 next_cursor로 다음 페이지를 요청합니다.
curl -X POST "https://api.socq.ai/v1/facebook-marketplace/item" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.facebook.com/marketplace/item/1656586118821988/"]}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueFacebook Marketplace Item API 추천 활용 사례
- 선택한 검색 결과 정보 보강: 판매 상품 설명, 판매자 필드, 추가 미디어, 속성, 배송 값, 정밀한 위치 정보로 선택한 Marketplace 검색 결과를 보강합니다.
- 가격·판매 가능 여부 재확인: 알고 있는 판매 상품 URL을 대상으로 정규화된 가격, 취소선 가격, 판매 가능 여부 텍스트, 판매 중·예약 중·판매 완료·배송·바로 구매·메시지 플래그를 비교합니다.
- 선택한 상품 속성 비교: 정해 둔 공개 상품 목록에 대해 제목, 카테고리, 상태 속성, 위치, 배송 유형, 가격, 미디어를 한눈에 정리합니다.
- 판매 상품 스냅샷 보존: 판매 상품 식별 정보, 원본 URL, 공개 콘텐츠, 상태 필드, created_at, collected_at을 특정 시점의 기록으로 저장해 나중에 비교합니다.
Facebook Marketplace Item API 활용 팁
- URL이 하나라도 유효하지 않으면 요청 전체가 거부되고 완전히 같은 URL 문자열은 한 번만 처리되므로, 제출 전에 모든 호스트와 /marketplace/item/{numeric_id} 경로를 검증하고 중복 URL을 제거하세요.
- 조회할 수 없거나 찾을 수 없는 상품은 임의의 판매 상품이 만들어지지 않고 건너뛰므로, 제출한 URL 수보다 반환된 레코드가 적은 것도 정상 결과로 취급하세요.
- 판매자 정보, 좌표, 설명, 미디어, 속성, 배송 값, 생성 시각, 공개 상태 플래그는 출처에 따라 없을 수 있는 선택 필드로 처리하세요.
- 반환된 판매 상품이 제출한 URL과 관측 시점에 계속 연결되도록 extra.input_url을 collected_at과 함께 저장하세요.
- 성공한 결과가 현재 결과 페이지를 넘는 배치에서는 첫 페이지가 전부라고 가정하지 말고, has_more가 true인 동안 next_cursor를 따라가세요.
관련 API
Facebook Marketplace Item API 외에 Facebook Marketplace의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Facebook Marketplace Location Search API — 도시, 지역, 동네, 장소 이름 검색어를 Marketplace 위치 후보와 좌표로 변환합니다.
- Facebook Marketplace Search API — 키워드와 좌표로 공개 Marketplace 판매 상품을 검색하며, 가격, 위치, 미디어, 카테고리, 배송, 재고 맥락을 포함합니다.