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 사용 방법
키워드와 지리적 중심지를 선택 필터와 함께 제출하고, 비동기 작업을 추적한 뒤, 정규화된 판매 상품을 커서 페이지네이션으로 읽습니다.
- 비어 있지 않은 query, -90에서 90 사이의 latitude, -180에서 180 사이의 longitude와 선택 필터를 준비합니다.
- 요청을 /v1/facebook-marketplace/search로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- 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 trueFacebook 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에 사용하세요.
관련 API
Facebook Marketplace Search API 외에 Facebook Marketplace의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Facebook Marketplace Location Search API — 도시, 지역, 동네, 장소 이름 검색어를 Marketplace 위치 후보와 좌표로 변환합니다.
- Facebook Marketplace Item API — 알고 있는 상품 URL에서 공개 Marketplace 판매 상품 상세를 수집하며, 판매자, 가격, 위치, 미디어, 속성, 배송, 재고 필드를 포함합니다.