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 の使い方
キーワードと地理的な中心地点に任意の出品フィルターを加えて送信し、非同期タスクを追跡して、正規化された出品をカーソルページネーションで読み取ります。
- 空でない 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より大きく、価格は0以上とし、min_price が max_price を超えないようにしてください。
- 保存された結果が最初のレスポンスページに収まらない場合は、has_more が false になるまで next_cursor をたどってください。results_limit が制御するのは収集件数であり、タスクレスポンスのページサイズではありません。
- 同じIDの出品はタスクごとに1回だけ保存され、公開出品は変更・削除されることがあるため、繰り返し取得するスナップショットは出品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の出品詳細を取得し、出品者、価格、場所、メディア、属性、配送、在庫状況の各フィールドを返します。