# Marketplace Metadata Guide **Guide Group:** Marketplace Metadata --- ## Overview This guide provides an overview of essential APIs to enhance the eBay marketplace experience for buyers. The [Taxonomy API](/api-docs/buy/taxonomy/overview.html) facilitates browsing by retrieving full and partial eBay category trees, suggested leaf categories based on keywords, and item aspects for leaf categories. The [Catalog API](/api-docs/buy/catalog/overview.html) helps buyers make informed decisions by providing complete and detailed product definitions. The [Charity API](/api-docs/buy/charity/overview.html) gives data on charitable organizations linked to eBay for Charity. The [GetItemShipping](/Devzone/XML/docs/Reference/eBay/GetItemShipping.html) API can be used to estimate the buyer's shipping cost for an item based on the buyer's location and quantity purchased. ## API Use Case [Retrieving eBay category information with Taxonomy API](#categoryinformation) [Searching for eBay catalog products](#catalogproducts) [Retrieving charity information](#charityinformation) [Utilizing GetItemShipping to estimate shipping costs](#estimateshippingcosts) ##### Retrieving eBay category information with Taxonomy API The Taxonomy API can be used to retrieve full and partial category trees. Begin with [getDefaultCategoryTreeId](/api-docs/buy/taxonomy/resources/category_tree/methods/getDefaultCategoryTreeId) to obtain the unique identifier of marketplace [categoryTreeId](/api-docs/buy/taxonomy/resources/category_tree/methods/getCategoryTree#response.categoryTreeId). Use [getCategoryTree](/api-docs/buy/taxonomy/resources/category_tree/methods/getCategorySubtree) to access the complete category taxonomy for a marketplace or [getCategorySubtree](/api-docs/buy/taxonomy/resources/category_tree/methods/getCategorySubtree) to retrieve a specific category at any level and its descendants. Improve your search experience by using [getCategorySuggestions](/api-docs/buy/taxonomy/resources/category_tree/methods/getCategorySuggestions) to find recommendations based on keywords related to product features. This helps buyers find the most suitable categories, making it easier to locate the products they want. The [getItemAspectsForCategory](/api-docs/buy/taxonomy/resources/category_tree/methods/getItemAspectsForCategory) and [fetchItemAspects](/api-docs/buy/taxonomy/resources/category_tree/methods/fetchItemAspects) retrieve required, recommended, and optional product aspects. The key difference is that [getItemAspectsForCategory](/api-docs/buy/taxonomy/resources/category_tree/methods/getItemAspectsForCategory) targets a single leaf category, while [fetchItemAspects](/api-docs/buy/taxonomy/resources/category_tree/methods/fetchItemAspects) downloads a file that covers metadata for all leaf categories. Additionally, the Taxonomy SDK can be used with [fetchItemAspects](/api-docs/buy/taxonomy/resources/category_tree/methods/fetchItemAspects) to notify users of any changes to product aspect metadata. ##### Searching for eBay catalog products The [Catalog API](/api-docs/buy/catalog/overview.html) enables buyers to efficiently discover eBay products that align with their desired items, ensuring a seamless shopping experience. ![Banner image](/cms/img/marketplacemetadata/ebay-catalog-products.png) To find detailed information about catalog products on eBay, you can use the [search](/api-docs/buy/catalog/resources/product_summary/methods/search) method, which allows you to locate multiple items using various filters. You can search for products using category IDs, keywords, aspect filters, GTIN (Global Trade Item Number), and MPN (Manufacturer Part Number). These filters help you find specific products by narrowing down the search criteria. The [search](/api-docs/buy/catalog/resources/product_summary/methods/search) method also includes options for fieldgroups, which let you choose the amount of detail you want in your search results. Additionally, pagination is available to manage large sets of results, letting you decide how many items to display per page and easily navigate through them. After identifying a product using the [search](/api-docs/buy/catalog/resources/product_summary/methods/search) method, you can use the [getProduct](/api-docs/buy/catalog/resources/product/methods/getProduct) method to get detailed information about a specific catalog product using its eBay Product ID (ePID). ##### Retrieving charity information The [Charity API](/api-docs/buy/charity/overview.html) helps buyers find charitable organizations on the eBay for Charity platform that they can support by purchasing items, offering information such as mission statements, registration IDs, and geographical locations. ![Banner image](/cms/img/marketplacemetadata/retrieving-charity-information.png) To find information about charitable organizations, you can use the [getCharityOrgs](/api-docs/buy/charity/resources/charity_org/methods/getCharityOrgs) method. This method allows you to search for organizations using keywords or registration IDs, providing results that include registration IDs and locations. It also features pagination, which helps you manage large lists of organizations by controlling how many results appear per page and making it easier to navigate through them. Use the [getCharityOrg](/api-docs/buy/charity/resources/charity_org/methods/getCharityOrg) method to get detailed information about a specific organization. This requires the charityOrgId, which is included in the search results from [getCharityOrgs](/api-docs/buy/charity/resources/charity_org/methods/getCharityOrgs). Using this ID, you can access detailed information about the organization, such as its mission and contact details. The [charity\_ids](/api-docs/buy/browse/resources/item_summary/methods/search#uri.charity_ids) query parameter of Browse API's [search](/api-docs/buy/browse/resources/item_summary/methods/search) method can be used to retrieve items that benefit a specific charity. ##### Utilizing GetItemShipping to estimate shipping costs The [GetItemShipping](/Devzone/XML/docs/Reference/eBay/GetItemShipping.html) API enables users to retrieve shipping cost estimates for items, supporting both flat and calculated shipping services based on the item's location and the buyer's location. This process is essential for helping buyers understand the expenses associated with the shipping services offered in a listing. The information sent with the API call includes the [DestinationPostalCode](/Devzone/XML/docs/Reference/eBay/GetItemShipping.html#Request.DestinationPostalCode), which indicates where the shipment is headed, and the [ItemID](/Devzone/XML/docs/Reference/eBay/GetItemShipping.html#Request.ItemID), which specifies the listing involved. These details are essential for providing precise and relevant shipping cost data for both international and domestic destinations. ## Code samples ## Error handling * Use precise keywords for [getCategorySuggestions](/api-docs/buy/taxonomy/resources/category_tree/methods/getCategorySuggestions) to match product attributes effectively, avoiding mismatched category selections. * Confirm the accuracy of ePID when using [getProduct](/api-docs/buy/catalog/resources/product/methods/getProduct) to ensure correct product information retrieval. * Validate syntax and accuracy when using [search](/api-docs/buy/catalog/resources/product_summary/methods/search) for catalog products to prevent retrieval errors. * Double-check registration IDs when using [getCharityOrgs](/api-docs/buy/charity/resources/charity_org/methods/getCharityOrgs). * Verify [DestinationPostalCode](/Devzone/XML/docs/Reference/eBay/GetItemShipping.html#Request.DestinationPostalCode), [ItemID](/Devzone/XML/docs/Reference/eBay/GetItemShipping.html#Request.ItemID), and [QuantitySold](/Devzone/XML/docs/Reference/eBay/GetItemShipping.html#Request.QuantitySold) to prevent inaccuracies in shipping cost retrieval. ## Best practices * Use [getItemAspectsForCategory](/api-docs/buy/taxonomy/resources/category_tree/methods/getItemAspectsForCategory) and [fetchItemAspects](/api-docs/buy/taxonomy/resources/category_tree/methods/fetchItemAspects) to enhance searches based on specific aspects. * Utilize [GetItemShipping](/Devzone/XML/docs/Reference/eBay/GetItemShipping.html) with accurate [DestinationPostalCode](/Devzone/XML/docs/Reference/eBay/GetItemShipping.html#Request.DestinationPostalCode) identifiers to improve shipping cost estimates for buyers. ## Code Samples ### Retrieve a category subtree for the eBay Australia marketplace **Label:** Retrieve a category subtree for the eBay Australia marketplace #### Bash Sample ```bash curl -X GET "https://api.ebay.com/commerce/taxonomy/v1/category_tree/15/get_category_subtree?category_id=3197" -H "Authorization:Bearer OAUTH_token" ``` ### Retrieve a specific charitable organization **Label:** Retrieve a specific charitable organization #### Bash Sample ```bash curl -X GET "https://api.ebay.com/commerce/charity/v1/charity_org/302" -H "Authorization:Bearer OAUTH_token" -H "X-EBAY-C-MARKETPLACE-ID:EBAY_US" ``` ## Related Topics - [Taxonomy API](/api-docs/buy/taxonomy/overview.html) - [Catalog API ](/api-docs/buy/catalog/overview.html) - [Charity API](/api-docs/buy/charity/overview.html) - [More Guides](/develop/guides)