出品のメタデータ

出品メタデータガイド (Listing Metadata Guide)

概要

セラー（販売者）は、商品を出品するeBayマーケットプレイスやカテゴリに応じて、出品時に特定のメタデータ情報の指定を求められることがよくあります。Selling Metadata APIを使用することで、セラーは特定のマーケットプレイスやカテゴリにおいて、特定の機能がサポートされているか、あるいは必須であるかを判断できます。セラーはこれらのAPIを利用して情報を取得し、出品データに追加することで、eBayの各種ポリシーを遵守し、出品を最適化することができます。

APIのユースケース

  • カテゴリ分類（タクソノミー）および適切な出品カテゴリの取得
  • カテゴリレベルのメタデータの取得
  • マーケットプレイスレベルのメタデータの取得
  • 規制関連メタデータの取得
  • eBayカタログ製品および慈善団体の取得

カテゴリ分類（タクソノミー）および適切な出品カテゴリの取得

すべてのeBay出品は、eBayのリーフカテゴリ（最下層カテゴリ）に関連付ける必要があります。最も適切なカテゴリを選択することで、バイヤーが検索を通じて商品を発見する可能性が高まり、閲覧数の増加や売上の向上につながります。

eBayのカテゴリ分類（タクソノミー）とリーフカテゴリを取得するためのAPIメソッドは以下の通りです。

  • getDefaultCategoryTreeId を使用して、特定のeBayマーケットプレイスの categoryTreeId（別名：eBayサイトID）を取得します。
  • 取得した categoryTreeId の値を参照し、以下のいずれかのメソッドを使用します。
    • getCategoryTree を使用してeBayマーケットプレイスのカテゴリツリー全体を取得するか、getCategorySubtree を使用して任意のレベルの特定カテゴリとそのすべての子孫カテゴリを取得します。leafCategoryTreeNode というブール値フィールドが true であることを確認し、対象のカテゴリがリーフカテゴリであることを確認してください。
    • getCategorySuggestions を使用して、指定した商品関連キーワードに基づき、最も関連性の高いeBayリーフカテゴリを取得します。
    • getExpiredCategories を使用して、廃止されたカテゴリIDと、それらがマッピングされた新しいカテゴリIDを取得します。

カテゴリレベルのメタデータの取得

特定のeBayカテゴリに関するメタデータを取得することで、セラーはそのリーフカテゴリに適用される機能や要件を把握し、出品データに反映させることができます。取得したメタデータは、Trading APIまたはInventory APIを通じて出品を作成・修正する際に使用します。

カテゴリレベルのメタデータを取得するAPIメソッドは以下の通りです。

  • 特定のeBayマーケットプレイスの1つまたは複数のリーフカテゴリでサポートされている、標準および整備済み（Refurbished）の商品の状態（Item Condition）、および状態説明（Condition Descriptor）のメタデータを取得するには、以下のいずれかのメソッドを使用します。
    • getItemConditionPolicies を使用して、指定されたeBayマーケットプレイス上の単一、複数、またはすべてのeBayリーフカテゴリに関連付けられたサポート済みの conditionId の値を取得します。なお、整備済み商品の状態を取得するには、OAuthユーザートークンが必要です。
    • GetCategoryFeatures を使用し、FeatureID の値を ConditionValues に設定して、指定されたeBayマーケットプレイスでサポートされている標準および整備済みの状態ID（Condition ID）の値を取得します。
  • 以下のいずれかのメソッドを使用して、指定されたリーフカテゴリに関連付けられた商品アスペクト（特性）の名前と値のペアを取得します。
    • getItemAspectsForCategory を使用して、指定されたカテゴリの必須、推奨、およびオプションの商品アスペクトを取得します。
    • fetchItemAspects を使用して、eBayマーケットプレイスに属するすべてのリーフカテゴリのアスペクトの完全なリストを取得します。このレスポンスで返されるアスペクトメタデータを比較するために、eBay Taxonomy SDKを使用できます。
  • getReturnPolicies または GetCategoryFeatures を使用して、返品期間や返品送料の負担者など、返品ポリシーに必要なメタデータを取得します。
  • GetCategoryFeatures で FeatureID フィルタを使用して、自動車カテゴリの以下のメタデータを取得します。
    • Motors Local Market listings: LocalMarketAdFormatEnabled を使用して、指定されたカテゴリが自動車ローカルマーケット出品をサポートしているかどうかを判断します。
    • eBay Motors Pro Listings: LocalMarketAdFormatEnabled を使用して、指定されたカテゴリが自動車ローカルマーケット出品をサポートしているかどうかを判断します。
    • Vehicle Deposits: DepositSupported を使用して、指定されたカテゴリが自動車出品の頭金（手付金）をサポートしているかどうかを判断します。
  • 以下の方法で、部品互換性（Parts Compatibility）のメタデータを取得します。
    • getAutomotivePartsCompatibilityPolicies または GetCategoryFeatures を使用して、リーフカテゴリが「自動車・トラック部品互換性」および/または「ボート・オートバイ部品互換性」をサポートしているかどうかを判断します。
    • getCompatibilityProperties または GetCompatibilitySearchNames を使用して、リーフカテゴリに必要な車両アスペクトを取得します。
    • getCompatibilityPropertyValues または GetCompatibilitySearchValues を使用して、車両アスペクトでサポートされている値を取得します。
  • 以下の方法で、クラシファイドアド（案内広告）出品のメタデータを取得します。
    • GetCategoryFeatures で FeatureID フィルタを AdFormatEnabled に設定し、カテゴリがクラシファイドアド出品をサポートしているかどうかを判断します。
    • サポートされている場合、以下のフィールドは、指定されたカテゴリのクラシファイドアド出品でベストオファー（Best Offer）とその機能が利用可能かどうかを示します。
      ClassifiedAdBestOfferEnabled, ClassifiedAdCounterOfferEnabled, ClassifiedAdAutoAcceptEnabled, ClassifiedAdAutoDeclineEnabled
    • 以下のフィールドは、指定されたカテゴリが出品にセラーの連絡先情報を含めることをサポートしているかどうかを示します。
      ClassifiedAdCompanyNameEnabled, ClassifiedAdContactByAddressEnabled, ClassifiedAdContactByEmailEnabled, ClassifiedAdContactByPhoneEnabled
  • ベストオファー機能をサポートするカテゴリを判断するには、以下のいずれかのメソッドを使用します。
    • getNegotiatedPricePolicies を使用して、ベストオファー機能をサポートするリーフカテゴリを取得します。
    • GetCategoryFeatures で FeatureID フィルタを BestOfferEnabled に設定し、ベストオファーをサポートするカテゴリのリストを取得します。
  • カテゴリがまとめ売り出品（Lot listings）をサポートしているかどうかを判断するには、getCategories を使用します。カテゴリがまとめ売り出品をサポートしていない場合、CategoryArray.Category.LSD ブール値は true として返されます。
  • カテゴリでサポートされているCBT（越境取引）の対象地域（Corridor）を取得するには、GetCategoryFeatures を使用し、FeatureID を CrossBorderTradeEnabled に設定します。以下の値がサポートされています。
    CrossBorderTradeNorthAmericaEnabled, CrossBorderTradeGBEnabled, CrossBorderTradeAustraliaEnabled

マーケットプレイスレベルのメタデータの取得

特定のeBayサイトのマーケットプレイスレベルのメタデータを取得することで、セラーはそのサイトでサポートされている機能や値を把握し、出品に適用することができます。Trading APIの GeteBayDetails コールには、サポートされている機能、要件、および特定のマーケットプレイスの値など、各種情報を取得するための様々な DetailName フィルタが用意されています。取得したメタデータは、Trading APIまたはInventory APIを通じて出品を作成・修正する際に使用します。

マーケットプレイスレベルのメタデータを取得するために使用される DetailName フィルタは以下の通りです。

  • SiteDetails: サポートされているすべてのeBayサイトの名前と識別子を取得します。
  • CurrencyDetails: eBayでサポートされている3文字の通貨コードのリストを取得します。
  • CountryDetails: eBayでサポートされている2文字の国コードのリストを取得します。
  • ShippingServiceDetails: 指定されたeBayサイトでサポートされている配送サービス情報を取得します。各配送サービスオプションについて、以下の情報が返されます。
    • サポートされている各配送サービスオプションに対して、個別の ShippingServiceDetails.ShippingService フィールドが返されます。各オプションについて、対応する ValidForSellingFlow フィールドの値が true であることを確認してください。また、すべての国際配送サービスオプションには、値が true の InternationalService ブール値フィールドが含まれます。
    • 以下は、各配送サービスオプションの ShippingServiceDetails コンテナの下に返される可能性のあるその他の主要なフィールドの一部です。
      SurchargeApplicable, ShippingServiceDetails.ServiceType, ShippingServiceDetails.ShippingPackage, ShippingServiceDetails.WeightRequired
  • RegionOfOriginDetails および ExcludeShippingLocationDetails: それぞれ発送元として指定できる地理的地域と国、および発送除外地域として指定できる地理的地域と国を取得します。
  • DispatchTimeMaxDetails: eBayサイトが許可するハンドリングタイム（出荷までの日数）のサポートされている営業日数を取得します。
  • ItemSpecificDetails、VariationDetails、および ListingStartPriceDetails: 商品スペック（Item Specifics）、バリエーション、および出品開始価格の最小・最大閾値データを取得します。
  • ShippingCarrierDetails: 指定されたサイトでサポートされている配送業者のリストを取得します。
  • ProductDetails: eBayリーフカテゴリで製品識別子が必須であるものの、製品に存在しないか適用されない場合に、関連する製品識別子フィールド（EAN, ISBN, UPC, Brand/MPN）に渡すべき ProductIdentifierUnavailableText を取得します。
  • ListingFeatureDetails: 指定されたeBayサイトでサポートされている出品機能を取得します。機能がサポートされている場合、対応する列挙値（enum value）を出品コールで使用して、その機能を有効にすることができます。
  • TimeZoneDetails: すべてのグローバルタイムゾーンのリストと、各タイムゾーンに関する詳細情報を取得します。

規制関連メタデータの取得

EU加盟国や北アイルランド内でビジネスを行うセラー、またはその他の地域に拠点を置きながらこれらの地域に発送するセラーは、eBay出品において規制情報の提供が義務付けられています。eBayでは、カテゴリごとに様々な種類の規制情報がサポート、推奨、または必須とされているかを判断するためのAPIを提供しています。サポートまたは必須の場合、Trading APIまたはInventory APIを通じて出品を作成・修正する際に、規制メタデータを指定できます。

規制メタデータを取得するAPIメソッドは以下の通りです。

  • getRegulatoryPolicies を使用して、カテゴリがいずれかの規制ポリシーをサポート、推奨、または必須としているかを判断します。
    • 危険物（hazmat）情報が必要な場合は、getHazardousMaterialLabels を使用して、特定のマーケットプレイスで適用される危険物ピクトグラム、ステートメント、または注意喚起語（signal words）の数値IDを取得します。
    • 製品安全ラベル情報が必要な場合は、getProductSafetyLabels を使用して、特定のマーケットプレイスで適用される製品安全ピクトグラムおよびステートメントの数値IDを取得します。
  • getExtendedPolicyProducerResponsibilityPolicies を使用して、カテゴリがいずれかの拡大生産者責任（EPR）ポリシーをサポート、推奨、または必須としているかを判断します。
    • 回収（テイクバック）ポリシーが必要な場合は、getCustomPolicies を使用して、セラーのアカウントに定義されている回収ポリシーのIDを取得します。
    • マルチバリエーション出品のバリエーションレベルでエコ参加費（eco-participation fee）を適用できるかどうかを確認するには、値が true の enabledForVariations ブール値フィールドを確認してください。

eBayカタログ製品および慈善団体の取得

eBay製品カタログは、eBayが出品を標準化するために使用する製品情報の構造化データベースです。eBayカタログ内の各製品は、eBayプロダクトID（ePID）によって一意に識別されます。eBay APIを通じて出品を作成する際、セラーは製品のePID値を使用して、その製品に関するeBayカタログの詳細情報を出品に自動的に入力できます。セラーが出品にカタログ情報を採用すればするほど、出品の一貫性と信頼性が向上します。

eBayカタログ製品を取得するAPIメソッドは以下の通りです。

  • Catalog API の search メソッドを使用して、在庫アイテムに最も一致するeBayカタログ製品（および関連する ePID 値）を検索および取得します。
  • getProduct を使用して、製品の詳細情報を取得し、製品が完全に一致することを確認します。

eBay Charity APIを使用することで、セラーは慈善寄付をビジネスプロセスに直接統合し、売上の一定割合を指定された非営利団体に寄付することができます。これは支援を必要とする人々を助けるだけでなく、セラーの評判を高め、特定の非営利団体の支援に関心のあるバイヤーにアピールすることにもつながります。

セラーはCharity APIの getCharityOrgs メソッドを使用して、サポートされている慈善団体の固有識別子を取得できます。この慈善団体IDの値と、セラーが寄付することを選択した購入価格の割合は、Trading APIまたはInventory APIを通じて出品を作成・修正する際に指定できます。

ワークフローの概要

listing-metadata

コードサンプル

米国マーケットプレイスのカテゴリツリーIDの取得 

curl -X GET "https://api.ebay.com/commerce/taxonomy/v1/get_default_category_tree_id?marketplace_id=EBAY_US"
-H "Authorization: Bearer OAUTH_token"

米国マーケットプレイスの「本・雑誌」カテゴリのカテゴリサブツリーの取得 

curl -X GET "https://api.ebay.com/commerce/taxonomy/v1/category_tree/0/get_category_subtree?category_id=267"
-H "Authorization: Bearer OAUTH_token"

エラーハンドリング

  • 無効なカテゴリツリーIDが原因でTaxonomy APIコールが失敗している場合は、getDefaultCategoryTreeId エンドポイントを使用して、そのマーケットプレイスの正しいツリーIDを取得してください。
  • 「無効なカテゴリ」エラーを受け取った場合は、カテゴリIDの値を確認してください。一部のメタデータエンドポイントは、リーフカテゴリのみを受け入れます。カテゴリIDは、getCategorySuggestions やTrading APIの GetCategories から取得したものかもしれません。必要に応じて、getCategorySubtree メソッドを使用し、leafCategoryTreeNode フィールドのブール値が true であることをチェックして、カテゴリがリーフカテゴリであることを確認してください。
  • 無効な marketplaceId が原因でAPIコールが失敗している場合は、eBayのMarketplace Idsリストで正しい値を参照し、APIリクエストに適切な marketplaceId を渡していることを確認してください。
  • 参照されたカテゴリが非推奨になったか、置き換えられた場合は、getExpiredCategories エンドポイントを使用して、古いカテゴリIDを新しいカテゴリIDにマッピングしてください。その後、APIによって返された新しいカテゴリIDで出品を更新してください。
  • getCompatibilityPropertyValues メソッドで不正な形式のエラーが発生した場合は、compatibility_property および/または filter クエリパラメータを確認し、構文が有効かどうかチェックしてください。
  • フィルタとして1つ以上のリーフカテゴリIDをサポートするMetadata APIメソッドの場合、それらのカテゴリは指定されたマーケットプレイスに属している必要があり、そうでない場合はメタデータは返されません。
  • Catalog APIの search メソッドで不正な形式のエラーが発生した場合は、クエリパラメータを確認し、構文が有効かどうかチェックしてください。

ベストプラクティス

  • categoryTreeVersion を使用して、カテゴリツリーの変更を監視してください。新しいバージョンが検出された場合は、getCategoryTree または getCategorySubTree を呼び出して、更新されたカテゴリを取得してください。
  • fetchItemAspects を使用して、マーケットプレイスのリーフカテゴリのすべてのアスペクトメタデータをダウンロードしてください。これは、大量の在庫や複数のカテゴリを管理する場合に特に役立ちます。なお、このfetchコールは非常に大きなGzip圧縮されたバイナリファイルを返すため、効率的な処理とストレージを確保できるよう適切に実装する必要があります。
  • getItemConditionPolicies、getReturnPolicies、または getAutomotivePartsCompatibilityPolicies などのメソッドを使用して、商品の状態、返品ポリシー、互換性アスペクトなどのカテゴリメタデータを定期的に更新し、マーケットプレイスの要件に準拠するようにしてください。
  • fetchItemAspects や getItemAspectsForCategory などのメソッドから取得したアスペクトメタデータを比較・検証するには、Taxonomy SDKを使用してください。
  • 使用するOAuthトークンのタイプ、メソッドの使用に必要なOAuthスコープ、必須/サポートされているHTTPヘッダー、および発生する可能性のあるエラーなどを確認するために、使用前に各メソッドのリファレンスドキュメントを読むことをお勧めします。
  • getItemConditionPolicies メソッドは通常、アプリケーショントークンのみを必要としますが、整備済み（Refurbished）商品の状態を取得するにはユーザートークンを使用する必要があります。
トップに戻る