Feed Beta API ドキュメント
アイテムフィードサービス API（Buy Feed API v1_beta）
限定リリース! これは限定リリース API であり、ビジネスユニットによって承認された一部の開発者のみが利用できます。本番環境でのアクセス取得については、Buy APIs の要件を参照してください。
Feed API は、eBay アイテムを含む TSV_GZIP（タブ区切り値 gzip）フィードファイルと、特定のカテゴリ、日付、マーケットプレイスの 1 時間以内に変更されたアイテムの時間別スナップショットファイルをダウンロードする機能を提供します。
API に加えて、フィードファイルのダウンロード、複数ファイルの結合、解凍を行うオープンソースの Feed SDK（Java）も利用可能です。フィールドフィルターを指定して、ファイル内のアイテムをキュレートすることもできます。
バージョン: v1_beta.35.2
ベースURL: https://api.ebay.com/buy/feed/v1_beta
認証（OAuth スコープ）
この API は OAuth 2.0 認証を使用します。
| スコープ | 説明 |
|---|---|
https://api.ebay.com/oauth/api_scope/buy.item.feed | アイテムフィードへのアクセス |
リソース一覧
Buy Feed API (v1_beta) は以下の 4 リソース、各 1 GET エンドポイント、合計 4 エンドポイントで構成されています。
| リソース | 説明 | 数 |
|---|---|---|
| item | 日次/週次アイテムフィードファイルのダウンロード | 1 |
| item_group | アイテムグループ（バリエーション）フィードファイルのダウンロード | 1 |
| item_snapshot | 時間別スナップショットフィードファイルのダウンロード | 1 |
| item_priority | アイテムプライオリティ（デルタ）フィードファイルのダウンロード | 1 |
フィードファイルの共通事項
- フィードファイルはバイナリ gzip ファイルです。ファイルが 100 MB を超える場合、
Rangeヘッダーを使用してチャンクでストリーミングする必要があります。 - ダウンロードされたファイルは自動的に gzip 圧縮されるため、
Accept-Encoding:gzipヘッダーを指定する必要はありません。 - フィルターがフィードファイルに適用されます。将来変更される可能性があるため、フィルターが適用されていないかのようにコーディングしてください。
- レスポンスヘッダー
Content-rangeはデータチャンクの位置を示し、Last-Modifiedはファイル生成日を示します。
item — アイテムフィード（1 エンドポイント）
GET /item
getItemFeed — TSV_GZIP アイテムフィードファイルをダウンロードします。指定されたカテゴリのすべての子カテゴリのアイテムが含まれます。
2 種類のフィードファイルが生成されます：
- 日次アイテムフィード（
feed_scope=NEWLY_LISTED）: 特定の日に出品されたすべての Good 'Til Cancelled アイテム - 週次アイテムブートストラップフィード（
feed_scope=ALL_ACTIVE）: カテゴリ内のすべての Good 'Til Cancelled アイテム
注: ブートストラップファイルは毎週火曜日に生成され、水曜日に利用可能。木曜日のダウンロードを推奨。日次フィードは MST 9AM 以降に利用可能（48〜72 時間の遅延あり）。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
Accept | ヘッダー | 必須 | レスポンス形式。デフォルト: application/json,text/tab-separated-values |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 必須 | eBay マーケットプレイス ID（大文字小文字区別）。例: EBAY_US |
Range | ヘッダー | 必須 | gzip ファイルのバイト範囲。形式: bytes=startpos-endpos。最大: 100 MB |
feed_scope | クエリ | 必須 | フィードタイプ。有効値: NEWLY_LISTED、ALL_ACTIVE |
category_id | クエリ | 必須 | eBay トップレベル（L1）カテゴリ ID。不動産カテゴリは除外。 |
date | クエリ | 条件付き | 日次フィードの日付（NEWLY_LISTED 時は必須）。形式: yyyyMMdd。3〜14 日前。 |
レスポンス: 200 / 204 / 206 / 400 / 403 / 404 / 409 / 416 / 500
item_group — アイテムグループフィード（1 エンドポイント）
GET /item_group
getItemGroupFeed — TSV_GZIP アイテムグループフィードファイルをダウンロードします。アイテムグループは、色、サイズ、容量などのアスペクトが異なるアイテムです。
対応する日次/週次のアイテムフィードファイルのコンテンツに基づいて生成されます。アイテムフィード内のアイテムに primaryItemGroupId 値がある場合、その値を使用してアイテムグループ情報が返されます。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
Accept | ヘッダー | 必須 | レスポンス形式。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 必須 | マーケットプレイス ID。 |
Range | ヘッダー | 任意 | バイト範囲。最大: 100 MB。 |
feed_scope | クエリ | 必須 | フィードタイプ。有効値: NEWLY_LISTED、ALL_ACTIVE |
category_id | クエリ | 必須 | トップレベルカテゴリ ID。 |
date | クエリ | 条件付き | 日次フィードの日付（NEWLY_LISTED 時は必須）。形式: yyyyMMdd |
レスポンス: 200 / 204 / 206 / 400 / 403 / 404 / 409 / 416 / 500
item_snapshot — 時間別スナップショットフィード（1 エンドポイント）
GET /item_snapshot
getItemSnapshotFeed — 時間別スナップショット TSV_GZIP フィードファイルをダウンロードします。指定された日と時間内に変更されたすべてのアイテムの詳細が含まれます。
スナップショットフィードには新規出品も含まれます。itemCreationDate で識別可能。
重要! availability 列が UNAVAILABLE の場合、itemId と availability 列のみが入力されます。
スナップショットファイルの生成には 2 時間かかります（例: 9AM のファイルは 11AM 以降に取得可能）。7 日間分のファイルが利用可能。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
Accept | ヘッダー | 必須 | レスポンス形式。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 必須 | マーケットプレイス ID。 |
Range | ヘッダー | 必須 | バイト範囲。最大: 100 MB。 |
category_id | クエリ | 必須 | トップレベルカテゴリ ID。 |
snapshot_date | クエリ | 必須 | スナップショットの日時（UTC）。形式: yyyy-MM-ddThh:00:00.000Z。Feed API は GMT を使用。 |
レスポンス: 200 / 204 / 206 / 400 / 403 / 404 / 409 / 416 / 500
item_priority — アイテムプライオリティフィード（1 エンドポイント）
GET /item_priority
getItemPriorityFeed — TSV_GZIP アイテムプライオリティフィードファイルをダウンロードします。キャンペーンへのアイテムの追加・削除など、優先アイテムのステータス変更（デルタ）を追跡できます。
重要! 日次フィード（アイテム、アイテムグループ）を消費してからアイテムプライオリティフィードを消費する必要があります。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
Accept | ヘッダー | 必須 | レスポンス形式。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 必須 | マーケットプレイス ID。 |
Range | ヘッダー | 必須 | バイト範囲。 |
category_id | クエリ | 必須 | トップレベルカテゴリ ID。 |
date | クエリ | 必須 | フィードの日付。形式: yyyyMMdd。14 日前まで。 |
レスポンス: 200 / 204 / 206 / 400 / 403 / 404 / 409 / 416 / 500
主要スキーマ
Buy Feed API (v1_beta) は以下の主要なレスポンススキーマを定義しています。フィードファイルは TSV 形式で返されるため、スキーマはフィールド（列）の定義として機能します。
Item（アイテムフィードの列定義）
アイテムフィードファイルの各行に含まれる主要フィールド：
| フィールド | 型 | 説明 |
|---|---|---|
itemId | string | アイテムの一意の識別子（RESTful 形式） |
title | string | セラーが作成したアイテムのタイトル |
imageUrl | string | アイテムのプライマリ画像 URL |
category | string | カテゴリのラベル（例: Toys & Hobbies|Action Figures） |
categoryId | string | カテゴリ ID |
sellerUsername | string | セラーの eBay ユーザー名 |
sellerFeedbackPercentage | string | セラーのポジティブフィードバック率 |
sellerFeedbackScore | string | セラーのフィードバックスコア |
gtin | string | GTIN（UPC/EAN/ISBN） |
brand | string | ブランド名 |
mpn | string | メーカー部品番号 |
epid | string | eBay 製品 ID |
conditionId | string | コンディション ID（例: 1000 = 新品） |
condition | string | コンディションのテキスト説明 |
priceValue | string | アイテム価格（割引後の場合あり） |
priceCurrency | string | 価格の通貨コード |
primaryItemGroupId | string | アイテムグループの一意の識別子 |
availability | string | アイテムの利用可能状態: AVAILABLE、TEMPORARILY_UNAVAILABLE、UNAVAILABLE |
estimatedAvailableQuantity | integer | 推定利用可能数量 |
deliveryOptions | string | 利用可能な配送オプション |
shippingCost | string | 最終送料 |
originalPriceValue | string | 元の販売価格（取消線価格用） |
discountAmount | string | 割引額 |
discountPercentage | string | 割引率 |
qualifiedPrograms | string | 対象プログラム（eBay Plus、Authenticity Guarantee 等） |
※ 上記は主要フィールドの抜粋です。完全なフィールド一覧は OpenAPI 仕様を参照してください。
エンドポイント一覧（全 4 エンドポイント）
| メソッド | エンドポイント | operationId | 説明 |
|---|---|---|---|
| GET | /item | getItemFeed | アイテムフィードダウンロード |
| GET | /item_group | getItemGroupFeed | アイテムグループフィードダウンロード |
| GET | /item_snapshot | getItemSnapshotFeed | 時間別スナップショットダウンロード |
| GET | /item_priority | getItemPriorityFeed | アイテムプライオリティフィードダウンロード |