Browse API ドキュメント
ブラウズ API（Browse API）
Browse API は、eBay マーケットプレイスのアイテムを検索・閲覧するための API です。キーワード、GTIN、カテゴリ、慈善団体、製品、画像などでアイテムを検索し、特定のアイテムの詳細情報を取得できます。また、製品の互換性チェック（自動車部品など）もサポートしています。
バージョン: v1.20.4
ベースURL: https://api.ebay.com/buy/browse/v1
認証（OAuth スコープ）
この API は クライアント資格情報（Client Credentials） フローを使用します。アプリケーショントークンのみで呼び出し可能です。
| スコープ | 説明 |
|---|---|
https://api.ebay.com/oauth/api_scope |
eBay の公開データを表示 |
https://api.ebay.com/oauth/api_scope/buy.item.bulk |
eBay アイテムを一括取得 |
リソース一覧
Browse API は以下の 2 リソース、合計 7 エンドポイント（5 GET + 2 POST）で構成されています。
| リソース | 説明 | 数 |
|---|---|---|
| item | アイテムの詳細取得、レガシー ID 変換、アイテムグループ取得、互換性チェック | 5 |
| item_summary | キーワード・カテゴリ・画像によるアイテム検索 | 2 |
item — アイテム詳細（5 エンドポイント）
GET /item/
getItems — 複数のアイテムの詳細を一括取得します（最大 20 アイテム ID または最大 10 アイテムグループ ID）。購入者が購入を決定するために必要な情報を提供します。
注: これは一部のパートナーのみが利用できる限定リリースです。返されるフィールドは制限されています。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
item_ids | クエリ | 条件付 | アイテム ID のカンマ区切りリスト（最大 20）。item_group_ids と同時使用不可。形式: v1|#|# |
item_group_ids | クエリ | 条件付 | アイテムグループ ID のカンマ区切りリスト（最大 10）。item_ids と同時使用不可。 |
quantity_for_shipping_estimate | クエリ | 任意 | 配送見積計算に使用するアイテム数量。 |
X-EBAY-C-ENDUSERCTX | ヘッダー | 任意 | アフィリエイト資格情報、または配送先の国/郵便番号を提供。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 条件付 | eBay マーケットプレイス ID。米国以外は必須。デフォルト: EBAY_US |
Accept-Language | ヘッダー | 任意 | 応答の自然言語とロケール。 |
レスポンス: 200 / 400 / 404 / 409 / 500
GET /item/get_item_by_legacy_id
getItemByLegacyId — レガシー API（Shopping、Finding 等）のアイテム ID を使用してアイテムの詳細を取得し、RESTful item_id も返します。レガシー API と Buy API の橋渡しとなるメソッドです。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
legacy_item_id | クエリ | 必須 | 取得するアイテムのレガシー ID。マルチバリエーションの場合は legacy_variation_id も必要。 |
legacy_variation_id | クエリ | 任意 | マルチバリエーション内の特定アイテムのレガシー ID。legacy_item_id と併用必須。 |
legacy_variation_sku | クエリ | 任意 | アイテムのレガシー SKU。legacy_item_id と併用必須。 |
fieldgroups | クエリ | 任意 | 応答の内容を制御。値: PRODUCT、ADDITIONAL_SELLER_DETAILS |
quantity_for_shipping_estimate | クエリ | 任意 | 配送見積計算に使用するアイテム数量。 |
X-EBAY-C-ENDUSERCTX | ヘッダー | 任意 | アフィリエイト資格情報 / 配送先情報。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 条件付 | eBay マーケットプレイス ID。米国以外は必須。 |
Accept-Language | ヘッダー | 任意 | 応答の自然言語とロケール。 |
レスポンス: 200 / 400 / 404 / 409 / 500
GET /item/get_items_by_item_group
getItemsByItemGroup — アイテムグループ（色、サイズ、容量などのバリエーション）内の個々のアイテムの詳細を取得します。items コンテナと commonDescriptions コンテナを返します。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
item_group_id | クエリ | 必須 | アイテムグループの一意の識別子。search や getItem の itemGroupHref から取得。 |
fieldgroups | クエリ | 任意 | 値: ADDITIONAL_SELLER_DETAILS（セラーの userId を追加） |
quantity_for_shipping_estimate | クエリ | 任意 | 配送見積計算に使用するアイテム数量。 |
X-EBAY-C-ENDUSERCTX | ヘッダー | 任意 | アフィリエイト資格情報 / 配送先情報。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 条件付 | eBay マーケットプレイス ID。米国以外は必須。 |
Accept-Language | ヘッダー | 任意 | 応答の自然言語とロケール。 |
レスポンス: 200 / 400 / 404 / 409 / 500
GET /item/{item_id}
getItem — 特定のアイテムの詳細（説明、価格、カテゴリ、状態、返品ポリシー、販売者フィードバック、配送オプション、推定配達日数など）を取得します。
fieldgroups パラメータで応答内容を制御できます:
COMPACT— 在庫状況や価格の変更確認に必要なフィールドのみ（単独使用）PRODUCT— 製品情報を追加ADDITIONAL_SELLER_DETAILS— セラーの userId を追加
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
item_id | パス | 必須 | アイテムの RESTful 識別子。形式: v1|#|# |
fieldgroups | クエリ | 任意 | 値: COMPACT、PRODUCT、ADDITIONAL_SELLER_DETAILS。COMPACT は単独使用。 |
quantity_for_shipping_estimate | クエリ | 任意 | 配送見積計算に使用するアイテム数量。 |
X-EBAY-C-ENDUSERCTX | ヘッダー | 任意 | アフィリエイト資格情報 / 配送先情報。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 条件付 | eBay マーケットプレイス ID。米国以外は必須。 |
Accept-Language | ヘッダー | 任意 | 応答の自然言語とロケール。 |
レスポンス: 200 / 400 / 404 / 409 / 500
POST /item/{item_id}/check_compatibility
checkCompatibility — 製品が指定されたアイテムと互換性があるかどうかを確認します。自動車、トラック、オートバイの部品互換性をサポートします。応答は COMPATIBLE、NOT_COMPATIBLE、または UNDETERMINED です。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
item_id | パス | 必須 | アイテムの RESTful 識別子。 |
Content-Type | ヘッダー | 必須 | application/json |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 条件付 | eBay マーケットプレイス ID。米国以外は必須。 |
Accept-Language | ヘッダー | 任意 | 応答の自然言語とロケール。 |
リクエストボディ: CompatibilityPayload（compatibilityProperties で車両属性を指定）
レスポンス: 200 → CompatibilityResponse / 400 / 404 / 409 / 500
item_summary — アイテム検索（2 エンドポイント）
GET /item_summary/search
search — さまざまなクエリパラメータで eBay アイテムを検索し、アイテムの概要を取得します。キーワード、カテゴリ、ePID、GTIN、慈善団体 ID、互換性フィルター等で検索できます。
注: デフォルトでは FIXED_PRICE（今すぐ購入）の出品のみが返されます。オークション出品を取得するには buyingOptions フィルターを使用してください。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
q | クエリ | 条件付 | 検索キーワード。スペース区切り = AND、カンマ+括弧 = OR。epid / gtin と同時使用不可。 |
category_ids | クエリ | 条件付 | カテゴリ ID（カンマ区切り）。現在は 1 つのみ。q や epid/gtin と組み合わせ可能。 |
epid | クエリ | 条件付 | eBay 製品 ID。gtin と組み合わせ可能。q と同時使用不可。 |
gtin | クエリ | 条件付 | 国際貿易アイテム番号（UPC のみ）。epid と組み合わせ可能。q と同時使用不可。 |
charity_ids | クエリ | 任意 | 慈善団体 ID（カンマ区切り、最大 20）。EBAY_US と EBAY_GB のみ。 |
fieldgroups | クエリ | 任意 | 値: MATCHING_ITEMS（デフォルト）、ASPECT_REFINEMENTS、BUYING_OPTION_REFINEMENTS、CATEGORY_REFINEMENTS、CONDITION_REFINEMENTS、EXTENDED、FULL |
filter | クエリ | 任意 | フィールドフィルター。例: price:[10..50]、sellers:{seller1|seller2} |
aspect_filter | クエリ | 任意 | アスペクトフィルター。構文: categoryId:{id},Color:{Red|Blue} |
compatibility_filter | クエリ | 任意 | 互換性フィルター。例: Year:2018;Make:BMW。自動車/トラック/オートバイのみ。 |
auto_correct | クエリ | 任意 | 自動修正を有効化。値: KEYWORD |
sort | クエリ | 任意 | 並べ替え。値: price、-price、distance、newlyListed、endingSoonest |
limit | クエリ | 任意 | 1 ページのアイテム数。最小: 1、最大: 200、デフォルト: 50 |
offset | クエリ | 任意 | スキップ件数。最小: 0、最大: 9,999、デフォルト: 0。limit の倍数であること。 |
X-EBAY-C-ENDUSERCTX | ヘッダー | 任意 | アフィリエイト資格情報 / 配送先情報。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 条件付 | eBay マーケットプレイス ID。米国以外は必須。 |
Accept-Language | ヘッダー | 任意 | 応答の自然言語とロケール。 |
レスポンス: 200 → SearchPagedCollection / 400 / 409 / 500
POST /item_summary/search_by_image
searchByImage — 画像に基づいて eBay アイテムを検索し、アイテムの概要を取得します。リクエストペイロードで Base64 エンコードされた画像を渡します。カテゴリや他のフィルターで検索を絞り込めます。
注: このメソッドは最大 10,000 個のアイテムを返すことができます。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
Content-Type | ヘッダー | 必須 | application/json |
category_ids | クエリ | 任意 | カテゴリ ID（カンマ区切り）。現在は 1 つのみ。 |
charity_ids | クエリ | 任意 | 慈善団体 ID（カンマ区切り、最大 20）。 |
fieldgroups | クエリ | 任意 | 値: MATCHING_ITEMS（デフォルト）、ASPECT_REFINEMENTS、BUYING_OPTION_REFINEMENTS、CATEGORY_REFINEMENTS、CONDITION_REFINEMENTS、EXTENDED、FULL |
aspect_filter | クエリ | 任意 | アスペクトフィルター。 |
filter | クエリ | 任意 | フィールドフィルター。 |
sort | クエリ | 任意 | 並べ替え（現在は最も一致する順序のみ）。 |
limit | クエリ | 任意 | 1 ページのアイテム数。最小: 1、最大: 200、デフォルト: 50 |
offset | クエリ | 任意 | スキップ件数。最小: 0、最大: 9,999、デフォルト: 0 |
X-EBAY-C-ENDUSERCTX | ヘッダー | 任意 | アフィリエイト資格情報 / 配送先情報。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 条件付 | eBay マーケットプレイス ID。米国以外は必須。 |
Accept-Language | ヘッダー | 任意 | 応答の自然言語とロケール。 |
リクエストボディ: SearchByImageRequest（image フィールドに Base64 画像文字列）
レスポンス: 200 → SearchPagedCollection / 400 / 409 / 500
主要スキーマ定義（全 75 スキーマ中の主要型）
Browse API は 75 のスキーマを定義しています。以下は最も重要なレスポンス型です。
検索レスポンス
SearchPagedCollection
| フィールド | 型 | 説明 |
|---|---|---|
href | string | 現在の結果セットの URI |
total | integer | 一致するアイテムの総数 |
next | string | 次ページの URI |
prev | string | 前ページの URI |
offset | integer | オフセット |
limit | integer | 1 ページの最大件数 |
itemSummaries | array[ItemSummary] | アイテム概要の配列 |
refinement | Refinement | 絞り込み情報（アスペクト、カテゴリ、状態等の分布） |
autoCorrections | AutoCorrections | 自動修正情報 |
ItemSummary（主要フィールド）
| フィールド | 型 | 説明 |
|---|---|---|
itemId | string | RESTful アイテム ID |
title | string | アイテムタイトル |
price | ConvertedAmount | 価格 |
image | Image | メイン画像 |
condition | string | 商品の状態 |
itemWebUrl | string | eBay 上のアイテム URL |
itemAffiliateWebUrl | string | アフィリエイト URL |
seller | Seller | セラー情報 |
categories | array[Category] | カテゴリ |
shippingOptions | array[ShippingOptionSummary] | 配送オプション |
buyingOptions | array[string] | 購入オプション（FIXED_PRICE、AUCTION 等） |
itemGroupHref | string | アイテムグループの URI |
legacyItemId | string | レガシーアイテム ID |
compatibilityMatch | string | 互換性マッチ結果 |
アイテム詳細
Item（主要フィールド）
| フィールド | 型 | 説明 |
|---|---|---|
itemId | string | RESTful アイテム ID |
title | string | アイテムタイトル |
description | string | アイテム説明 |
price | ConvertedAmount | 現在の価格 |
condition | string | 商品の状態 |
image | Image | メイン画像 |
additionalImages | array[Image] | 追加画像 |
seller | SellerDetail | セラー詳細情報 |
returnTerms | ItemReturnTerms | 返品条件 |
shippingOptions | array[ShippingOption] | 配送オプション |
estimatedAvailabilities | array[EstimatedAvailability] | 在庫状況 |
categoryPath | string | カテゴリパス |
localizedAspects | array[TypedNameValue] | ローカライズされたアスペクト |
buyingOptions | array[string] | 購入オプション |
legacyItemId | string | レガシーアイテム ID |
product | Product | 製品情報（fieldgroups=PRODUCT 時） |
互換性
CompatibilityResponse
| フィールド | 型 | 説明 |
|---|---|---|
compatibilityStatus | string | 互換性ステータス: COMPATIBLE、NOT_COMPATIBLE、UNDETERMINED |
共通型
ConvertedAmount
| フィールド | 型 | 説明 |
|---|---|---|
value | string | 金額値 |
currency | string | 通貨コード（ISO 4217） |
convertedFromValue | string | 変換前の金額 |
convertedFromCurrency | string | 変換前の通貨 |
Image
| フィールド | 型 | 説明 |
|---|---|---|
imageUrl | string | 画像の URL |
height | integer | 高さ（ピクセル） |
width | integer | 幅（ピクセル） |
Error
| フィールド | 型 | 説明 |
|---|---|---|
category | string | エラーカテゴリ |
domain | string | エラードメイン |
errorId | integer | エラー ID |
message | string | 短いメッセージ |
longMessage | string | 詳細メッセージ |
inputRefIds | array[string] | 入力参照 ID |
outputRefIds | array[string] | 出力参照 ID |
parameters | array[ErrorParameter] | エラーパラメータ |
subdomain | string | エラーサブドメイン |
エンドポイント一覧（全 7 エンドポイント）
| メソッド | エンドポイント | operationId | 説明 |
|---|---|---|---|
| GET | /item/ | getItems | 複数アイテムの詳細を一括取得 |
| GET | /item/get_item_by_legacy_id | getItemByLegacyId | レガシー ID でアイテム詳細を取得 |
| GET | /item/get_items_by_item_group | getItemsByItemGroup | アイテムグループの詳細を取得 |
| GET | /item/{item_id} | getItem | 特定のアイテムの詳細を取得 |
| POST | /item/{item_id}/check_compatibility | checkCompatibility | 製品の互換性をチェック |
| GET | /item_summary/search | search | キーワード等でアイテムを検索 |
| POST | /item_summary/search_by_image | searchByImage | 画像でアイテムを検索 |