Facebook Marketplace API
장소를 검색용 좌표로 확인하고, 키워드와 위치로 공개 Marketplace 판매 상품을 찾거나, 알고 있는 상품 URL에서 가격·판매자·미디어·속성·구매 가능 여부의 상세 데이터를 가져옵니다.
사용할 수 있는 Facebook Marketplace API
장소를 확인할 때는 Location Search, 좌표 주변의 판매 상품을 찾을 때는 Search, 알고 있는 Marketplace 상품 URL의 상세 레코드를 가져올 때는 Item을 사용합니다.
어떤 Facebook Marketplace 데이터를 가져올 수 있나요?
SocQ는 지역 시장 조사, 가격 분석, 재고 추적, 판매 상품 정보 보강에 쓸 수 있는 정규화된 공개 지역 후보, 판매 상품 검색 결과, 상품 상세 정보를 반환합니다.
Marketplace 지역 후보
도시, 지역, 동네 또는 장소 이름을 Facebook 지역 ID, 라벨, 주소 정보, 위도, 경도로 확인합니다.
공개 판매 상품 식별 정보
제공되는 경우 판매 상품 ID, 제목, 설명, 출처 URL, 카테고리, 등록일 텍스트, 수집 타임스탬프를 가져옵니다.
가격과 통화
제공되는 가격 금액, 통화 코드, 서식이 적용된 가격, 취소선 가격을 정규화된 판매 상품마다 함께 보관합니다.
위치·배송 데이터
제공되는 장소 라벨, 도시·주 값, 좌표, 배송 유형, 배송 신호, 직거래 정보를 가져옵니다.
미디어, 속성, 판매자 정보
원본이 노출하는 경우 공개 판매 상품 이미지, 상품 속성, 상태 값, 판매자 신원 필드를 수집합니다.
구매 가능 여부와 판매 상품 상태
특정 시점의 판매 상품 분석을 위해 구매 가능, 판매 완료, 보류, 숨김, 게시 중, 메시지, 바로 구매 신호를 보관합니다.
SocQ vs Meta Graph API
SocQ는 지원되는 공개 Marketplace 수집에 집중합니다. Meta의 Graph API는 권한이 부여된 Meta 자산을 위해 설계되었으며, 일반적인 공개 Marketplace 검색 API는 제공하지 않습니다.
| 기능 | SocQ | Meta Graph API |
|---|---|---|
| 주요 용도 | 공개 Marketplace 지역·검색·상품 수집 | 사용자나 비즈니스가 권한을 부여한 지원 자산 관리 |
| 고객 OAuth | SocQ API 키, 고객의 Facebook OAuth 불필요 | Meta 앱, 권한, 액세스 토큰 |
| 공개 판매 상품 검색 | 키워드와 확인된 지역으로 지원 | 일반적인 공개 Marketplace 판매 상품 검색 엔드포인트 없음 |
| 판매 상품 생성·수정 | 지원하지 않음 | 일반 소비자용 Marketplace 게시 엔드포인트 없음 |
| 응답 형식 | 정규화된 SocQ 레코드 | 지원 제품별 Graph API 고유 객체 |
Facebook Marketplace API 작동 방식
필요하면 검색 중심 지점을 먼저 확인하고, 판매 상품 검색이나 알고 있는 상품 URL을 제출한 뒤, 공통 비동기 작업 흐름으로 정규화된 레코드를 읽습니다.
1. 시작 입력 준비
장소 이름을 좌표로 확인하거나, 이미 알고 있는 좌표를 사용하거나, 공개 Marketplace 상품 URL에서 바로 시작합니다.
2. 작업 제출 및 추적
알맞은 POST 요청을 보내고 반환된 task_id를 저장한 뒤, 처리가 끝날 때까지 /v1/tasks/{task_id}를 폴링합니다.
3. 정규화된 결과 읽기
data.results.items를 처리하고, has_more가 true인 동안 next_cursor를 따라갑니다.
먼저 장소 이름을 확인한 뒤, 선택한 후보의 좌표로 공개 Marketplace 판매 상품을 검색합니다.
# Resolve a place name
curl -X POST "https://api.socq.ai/v1/facebook-marketplace/location-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"Austin"}'
# Search listings around the selected coordinates
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 API 주요 활용 사례
지역 판매 상품 탐색
시장 지역을 확인한 뒤 키워드, 좌표, 반경, 가격, 상태, 배송 방법, 날짜, 구매 가능 여부로 공개 판매 상품을 검색합니다.
지역 가격 비교
비슷한 공개 판매 상품끼리 정규화된 판매 희망 가격, 통화, 제목, 카테고리, 상태, 위치를 비교합니다.
지역별 재고 모니터링
선택한 시장의 범위가 정해진 판매 상품 스냅샷을 수집하고, 공개 재고, 배송 옵션, 구매 가능 여부를 시간에 따라 비교합니다.
알고 있는 판매 상품 정보 보강
알고 있는 상품 URL을 설명, 판매자 정보, 가격, 위치, 미디어, 속성, 상태 필드가 담긴 상세 레코드로 변환합니다.
제한 사항과 공개 데이터 정책
Marketplace 결과는 특정 시점의 공개 레코드입니다. 이 API들은 소비자용 Marketplace 화면을 그대로 재현하지 않으며, 판매 상품과 계정도 관리하지 않습니다.
- Location Search에는 비어 있지 않은 장소 이름 쿼리 하나가 필요하며 results_limit은 받지 않고, 이름이 비슷한 후보가 여러 개 반환될 수 있습니다.
- 지역 후보를 판매 상품 검색의 중심 지점으로 사용하기 전에 주소 정보와 좌표를 확인하세요.
- Search에는 비어 있지 않은 키워드, 위도, 경도가 필요합니다. results_limit의 기본값은 100이고 1부터 2,000까지의 정수를 받습니다.
- Search 결과에는 설명, 판매자 정보, 정확한 좌표, 속성, 생성 시각이 빠져 있을 수 있으며, 중복된 판매 상품 ID는 한 번만 저장됩니다.
- Item에는 지원되는 /marketplace/item/{numeric_id} URL이 필요합니다. 유효한 URL마다 레코드를 최대 1건 반환하며, 사용할 수 없는 상품은 건너뛸 수 있습니다.
- 빈 결과는 공개 항목 없음, 엄격한 필터, 지역별 제공 여부, 사용할 수 없는 판매 상품, 공개 원본의 한계 중 하나를 반영할 수 있습니다.
Facebook Marketplace API 자주 묻는 질문
Facebook Marketplace API란 무엇인가요?
Facebook Marketplace API는 Marketplace 지역 확인, 공개 판매 상품 검색, 알고 있는 상품 URL의 상세 레코드 조회를 위한 SocQ 엔드포인트 모음입니다.
어떤 Facebook Marketplace API를 사용해야 하나요?
장소를 확인할 때는 Location Search, 좌표 주변의 판매 상품을 찾을 때는 Search, 공개 Marketplace 상품 URL을 이미 알고 있을 때는 Item을 사용하세요.
Facebook Marketplace를 지역으로 검색하려면 어떻게 하나요?
도시, 지역, 동네 또는 장소 이름을 Location Search에 제출해 알맞은 후보를 고른 다음, 해당 후보의 위도와 경도를 Search에 전달하세요.
Facebook Marketplace Search는 무엇을 반환하나요?
Search는 판매 상품 식별 정보, 제목, 설명, 가격, 위치, 이미지, 판매자 정보, 카테고리, 배송 옵션, 상태 필드, 출처 URL, 수집 시각을 반환할 수 있습니다.
Facebook Marketplace Item은 언제 사용하나요?
상세 설명, 판매자, 가격, 위치, 미디어, 속성, 배송, 구매 가능 여부 필드가 필요하고 공개 상품 URL을 알고 있을 때 Item을 사용하세요.
결과 수가 results_limit보다 적은 이유는 무엇인가요?
제한은 요청한 최댓값입니다. 더 가져올 공개 페이지가 없거나, 필터가 레코드를 제외했거나, 중복된 판매 상품 ID가 제거되면 수집이 멈출 수 있습니다.
Facebook Marketplace 결과의 요금은 어떻게 되나요?
지역 후보는 반환된 결과 1건당 0.3 크레딧, Search 판매 상품은 0.7 크레딧, Item 레코드는 0.6 크레딧입니다. 빈 결과에는 결과 요금이 없습니다.
여러 플랫폼의 데이터를 결합해 더 폭넓은 비즈니스 인사이트를 얻으세요
여러 플랫폼의 공개 프로필, 콘텐츠, 참여도 데이터를 하나의 워크플로로 모으면 브랜드, 크리에이터, 주제를 추적하고 플랫폼 간 모니터링과 분석을 더 효율적으로 진행할 수 있습니다.
X API
공개 프로필, 팔로워·팔로잉 관계, 게시물, 답글, 인용, 리포스트한 사용자, 검색 결과, 현재 트렌드를 수집합니다. 일관된 결과를 리서치와 모니터링에 활용하세요.
LinkedIn API
알고 있는 URL에서 공개 LinkedIn 프로필, 기업, 게시물, 채용 공고 데이터를 가져옵니다. 식별 정보, 경력, 기업, 콘텐츠, 참여도, 채용 공고 필드가 정규화되어 제공됩니다.
Reddit API
알고 있는 URL에서 공개 Reddit 게시물과 댓글을 가져오고, 서브레딧의 새 글·인기 글·핫 게시물을 둘러보거나, 키워드와 게시 기간으로 토론을 검색합니다.
Pinterest API
공개 Pinterest 프로필 데이터를 가져오고, 알고 있는 핀을 확인하고, 선택한 프로필의 핀을 수집하거나 키워드로 검색해 크리에이터, 콘텐츠, 비주얼 트렌드를 리서치합니다.
Threads API
공개 Threads 프로필을 가져오고, 알고 있는 게시물을 확인하거나, 선택한 프로필의 게시물을 수집합니다. 식별 정보, 콘텐츠, 미디어, 참여도, 타임스탬프 필드가 정규화되어 제공됩니다.
Bluesky API
공개 Bluesky 프로필을 가져오고, 알고 있는 게시물 URL을 확인하거나, 계정 게시물 한 페이지를 수집해 정규화된 신원 정보, 콘텐츠, 미디어, 타임스탬프, 공개된 참여 필드로 받아 봅니다.


