facebook-marketplace/
search

키워드와 좌표로 공개 Facebook Marketplace 판매 상품을 검색하고, 제목, 가격, 위치, 이미지, 상태 필드, 원본 URL을 정규화된 레코드로 반환합니다.

Facebook Marketplace Search API

키워드·좌표 입력
지역·판매 상품 필터
1~2,000건 결과 요청
정규화된 공개 판매 상품
결과당 0.7 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

Facebook Marketplace Search

Facebook Marketplace Search 결과는 제목, 가격, 위치, 이미지, 판매자 정보, 배송 옵션, 판매 가능 여부 신호를 담은 공개 지역 거래 상품입니다. 이러한 필드는 지역 재고 조사, 희망 판매가 비교, 카테고리 분석, 반복 가능한 시장 스냅샷에 활용할 수 있습니다.

Facebook Marketplace Search API 주요 기능

  • 키워드·지역 기반 판매 상품 검색비어 있지 않은 query 하나와 필수 위도·경도 좌표를 조합하고, 반경, 가격, 정렬, 배송, 상태, 등록일, 판매 가능 여부 조건으로 공개 판매 상품을 좁힙니다.
  • 구조화된 판매 상품·가격 레코드판매 상품 ID, 공개 URL, 제목, 확인 가능한 설명, 가격, 통화, 표시용 가격, 취소선 가격을 일관된 형태로 반환합니다.
  • 위치·미디어·분류 정보결과마다 확인 가능한 위치 표기, 도시·주 값, 이미지 참조, 카테고리 ID, 속성, 배송 유형, 등록일 텍스트를 함께 보존합니다.
  • 공개 검색 카드 수준의 정보공개된 판매자 필드와 판매 중·예약 중·판매 완료·배송·바로 구매·메시지 플래그를 보존하며, 공개 결과에서 제공되지 않는 검색 카드 정보는 비워 둡니다.

Facebook Marketplace Search API 매개변수

매개변수필수설명
query필수판매 상품 검색 키워드로, 비어 있지 않아야 하는 필수 값입니다. 앞뒤 공백은 제출 전에 제거됩니다.
latitude필수검색 중심지의 위도로, -90에서 90 사이의 숫자로 지정하는 필수 값입니다.
longitude필수검색 중심지의 경도로, -180에서 180 사이의 숫자로 지정하는 필수 값입니다.
results_limit선택검색 페이지 전체에서 저장할 판매 상품의 최대 개수입니다. 기본값은 100이며 1에서 2,000 사이의 정수를 지정할 수 있습니다.
radius_km선택검색 반경(킬로미터)으로, 선택 값입니다. 지정할 때는 0보다 큰 숫자여야 합니다.
min_price선택판매 상품 최소 가격으로, 선택 값입니다. 음수일 수 없고 max_price를 초과할 수 없습니다.
max_price선택판매 상품 최대 가격으로, 선택 값입니다. 음수일 수 없고 min_price보다 낮을 수 없습니다.
sort_by선택정렬 순서로, 선택 값입니다. suggested, distance_ascend, creation_time_descend, price_ascend, price_descend 중에서 지정합니다.
delivery_method선택배송 방식 필터로, 선택 값입니다. all, local_pickup, shipping 중에서 지정합니다.
condition선택상품 상태 필터로, 선택 값입니다. new, used_like_new, used_good, used_fair 중에서 지정합니다.
date_listed선택등록 시점 필터로, 선택 값입니다. all, 1, 7, 30, last_24_hours, last_7_days, last_30_days 중에서 지정합니다.
availability선택판매 가능 여부 필터로, 선택 값입니다. available, sold, all 중에서 지정합니다.

Facebook Marketplace Search API 사용 방법

키워드와 지리적 중심지를 선택 필터와 함께 제출하고, 비동기 작업을 추적한 뒤, 정규화된 판매 상품을 커서 페이지네이션으로 읽습니다.

  1. 비어 있지 않은 query, -90에서 90 사이의 latitude, -180에서 180 사이의 longitude와 선택 필터를 준비합니다.
  2. 요청을 /v1/facebook-marketplace/search로 POST하고, 반환된 task_id를 저장합니다.
  3. 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. data.results.items를 읽고, has_more가 true인 동안에는 반환된 next_cursor를 전달해 다음 결과를 요청합니다.
curl -X POST "https://api.socq.ai/v1/facebook-marketplace/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"bike","latitude":30.2677,"longitude":-97.7475,"results_limit":100}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Facebook Marketplace Search API 추천 활용 사례

  • 지역별 희망 판매가 비교: 정해 둔 검색 지역 안에서 비슷한 공개 판매 상품의 정규화된 가격, 통화, 제목, 검색어 맥락, 위치를 비교합니다.
  • 지역 재고·카테고리 조사: 카테고리 ID, 속성, 배송 유형, 판매 가능 여부 필드, 이미지, 위치 정보로 범위가 정해진 지역 판매 상품 데이터셋을 구성합니다.
  • 반복 가능한 시장 스냅샷: 판매 상품 ID, 가격, 상태 필드, search_query, collected_at을 보존해, 같은 검색을 따로 수집한 결과를 시간순으로 비교합니다.
  • 판매 상품 후보 목록 준비: 공개 판매 상품 URL, 제목, 가격, 이미지, 판매 가능 여부 정보로 상품 단위 후속 조사 대상 레코드를 고릅니다.

Facebook Marketplace Search API 활용 팁

  • 좌표 대신 장소 이름으로 검색을 시작한다면, latitude와 longitude를 제출하기 전에 Location Search 후보를 조회해 확인하세요.
  • 제출 전에 좌표 범위를 검증하고, radius_km는 0보다 크게, 가격은 음수가 아니게 하며, min_price가 max_price를 넘지 않도록 하세요.
  • 저장된 결과가 첫 응답 페이지를 넘으면 has_more가 false가 될 때까지 next_cursor를 따라가세요. results_limit 값은 수집 상한이며 작업 응답의 페이지 크기가 아닙니다.
  • 작업마다 중복 ID는 한 번만 저장되고 공개 판매 상품은 바뀌거나 사라질 수 있으므로, 반복 스냅샷은 판매 상품 ID를 키로 삼고 collected_at을 함께 보존하세요.
  • 설명, 판매자 필드, 정밀한 좌표, 속성, 생성 시각은 선택 값으로 취급하고, 더 자세한 공개 정보가 필요하면 반환된 판매 상품 URL을 Marketplace Item에 사용하세요.

Facebook Marketplace Search API 외에 Facebook Marketplace의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • Facebook Marketplace Location Search API — 도시, 지역, 동네, 장소 이름 검색어를 Marketplace 위치 후보와 좌표로 변환합니다.
  • Facebook Marketplace Item API — 알고 있는 상품 URL에서 공개 Marketplace 판매 상품 상세를 수집하며, 판매자, 가격, 위치, 미디어, 속성, 배송, 재고 필드를 포함합니다.

다른 플랫폼 둘러보기

Facebook Marketplace 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

Facebook Marketplace Search API — 자주 묻는 질문

Facebook Marketplace Search API는 비어 있지 않은 키워드와 필수 위도·경도 좌표를 기준으로 공개 Marketplace 판매 상품을 가져오는 API입니다. 정규화된 판매 상품 식별 정보, 제목, 가격, 위치, 이미지, 공개된 판매자 정보, 상태 필드, 원본 URL, 수집 시각을 반환합니다.

요청에는 query, latitude, longitude가 필요합니다. 선택 항목으로 results_limit, radius_km, 최소·최대 가격, 정렬 순서, 배송 방식, 상품 상태, 등록 시점, 판매 가능 여부를 문서에 명시된 열거형 값으로 지정할 수 있습니다.

results_limit 값은 요청한 최대 개수이며 보장되는 개수가 아닙니다. 가져올 수 있는 출처 페이지가 더 없으면 수집이 멈추고, 공개된 판매 상품 ID가 같은 레코드는 한 번만 저장됩니다.

검색 카드에는 설명, 판매자 식별 정보, 정밀한 좌표, 속성, 생성 시각이 없을 수 있습니다. 클라이언트는 없는 선택 필드를 요청 실패로 보지 말고, 생략하거나 안전하게 처리해야 합니다.

키워드와 좌표에 일치하는 공개 결과가 없었거나, 필터가 지나치게 좁았거나, 지역별 제공 여부가 달랐거나, 공개 출처가 응답 경계에서 멈췄을 수 있습니다. 재시도하기 전에 위치를 확인하고 선택 필터를 넓혀 보세요.

도시, 지역, 동네 또는 장소 이름은 알지만 확인된 좌표가 없을 때는 Location Search를 사용하세요. 검색 카드보다 자세한 공개 정보가 필요하고 판매 상품 URL을 알고 있다면 Marketplace Item을 사용하세요.

반환된 판매 상품 레코드 1건마다 0.7 SocQ 크레딧이 차감됩니다. 요청 견적은 results_limit 값을 기준으로 하며 생략하면 100을 사용하고, 결과가 비어 있으면 결과 요금이 발생하지 않습니다.