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} から始まる公開パスを処理し、収集対象を送信した出品のみに限定します。
- 正規化された出品詳細公開されている場合、出品ID、タイトル、説明文、出品者の情報、価格、所在地、画像、属性、配送の値、タイムスタンプ、公開されている販売状況フィールドを返します。
- URLごとの独立したバッチ処理有効な各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を1つ以上用意します。
- リンクを 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について、正規化された価格、取り消し線付き価格、販売状況のテキスト、および公開中・取引中・売却済み・配送・今すぐ購入・メッセージ可否の各フラグを比較します。
- 選定した商品属性の比較: 指定した公開出品のリストについて、タイトル、カテゴリ、状態の属性、所在地、配送タイプ、価格、メディアを整理します。
- 出品スナップショットの保存: 出品ID、取得元URL、公開コンテンツ、ステータスフィールド、created_at、collected_at を特定時点のレコードとして保存し、後で比較できるようにします。
Facebook Marketplace Item API 活用のヒント
- 無効なURLが1つでもあるとリクエスト全体が拒否され、完全に同一のURLは1回しか処理されないため、送信前にすべてのホストと /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の出品を検索し、価格、場所、メディア、カテゴリ、配送、在庫状況の情報を返します。