facebook-marketplace/
search

キーワードと座標で公開Facebook Marketplaceの出品を検索し、タイトル、価格、所在地、画像、ステータスフィールド、取得元URLを正規化レコードとして返します。

Facebook Marketplace Search API

キーワードと座標で指定
地理・出品条件のフィルター
取得件数1〜2,000件
正規化された公開出品
結果1件あたり0.7クレジット
準備完了
準備完了

パラメータを入力してリクエストを送信してください。タスクのステータスと正規化された結果がここに表示されます。

README

SocQ 編集 · 更新

Facebook Marketplace Search

Facebook Marketplaceの検索結果に表示される出品は、タイトル、価格、所在地、画像、出品者の情報、配送オプション、販売状況のシグナルを含む、地域の個人間取引向けの公開出品です。これらのフィールドは、地域の在庫調査、希望価格の比較、カテゴリ分析、繰り返し取得できる市場スナップショットに活用できます。

Facebook Marketplace Search API の主な機能

  • キーワードと地域による出品検索空でないクエリ1件と必須の緯度・経度を組み合わせ、半径、価格、並び順、配送、状態、出品日、販売状況の条件で公開出品を絞り込みます。
  • 構造化された出品・価格レコード出品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任意任意。出品価格の下限です。0以上で、max_price を超えることはできません。
max_price任意任意。出品価格の上限です。0以上で、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より大きく、価格は0以上とし、min_price が max_price を超えないようにしてください。
  • 保存された結果が最初のレスポンスページに収まらない場合は、has_more が false になるまで next_cursor をたどってください。results_limit が制御するのは収集件数であり、タスクレスポンスのページサイズではありません。
  • 同じIDの出品はタスクごとに1回だけ保存され、公開出品は変更・削除されることがあるため、繰り返し取得するスナップショットは出品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です。正規化された出品ID、タイトル、価格、所在地、画像、公開されている出品者の情報、ステータスフィールド、取得元URL、取得日時を返します。

リクエストには query、latitude、longitude が必須です。任意の条件として、results_limit、radius_km、価格の下限と上限、並び順、配送方法、商品の状態、出品からの経過期間、販売状況を、ドキュメントに記載された列挙値で指定できます。

results_limit は取得する最大件数の指定であり、件数を保証するものではありません。取得元に追加のページがなくなった時点で収集は終了し、同じ出品IDのレコードは1回だけ保存されます。

検索カードには、説明文、出品者の情報、詳細な座標、属性、作成日時が含まれない場合があります。クライアント側では、欠けている任意フィールドをリクエストの失敗として扱わず、省略するか安全に処理してください。

結果が空の場合、キーワードと座標に一致する公開出品が返されなかった、フィルターが厳しすぎた、地域によって利用状況が異なっていた、または公開ソースがレスポンスの区切りで停止した、などの可能性があります。再試行する前に、所在地を見直し、任意のフィルターを緩めてください。

都市名、地域名、地区名、場所の名前はあるものの、確認済みの座標がない場合はLocation Searchを使用してください。検索カードより詳しい公開情報が必要な場合は、既知の出品URLでMarketplace Itemを使用してください。

返された出品レコード1件につき0.7 SocQクレジットです。リクエストの見積もりには results_limit(省略時は100)が使われ、結果が0件の場合は結果に対する課金は発生しません。