{ "openapi": "3.0.0", "info": { "title": "Marketplace Insights API", "description": "Note: This is a (Limited Release) API available only to select developers approved by business units. For information on how to obtain access to this API in production, see the Buy APIs Requirements.
The Marketplace Insights API provides the ability to search for sold items on eBay by keyword, GTIN, category, and product and returns the of sales history of those items.
", "contact": { "name": "eBay Inc," }, "license": { "name": "eBay API License Agreement", "url": "https://go.developer.ebay.com/api-license-agreement" }, "version": "v1_beta.2.2" }, "servers": [ { "url": "https://api.ebay.com{basePath}", "description": "Production", "variables": { "basePath": { "default": "/buy/marketplace_insights/v1_beta" } } } ], "paths": { "/item_sales/search": { "get": { "tags": [ "item_sales" ], "description": "Note: This is a (Limited Release) API available only to select developers approved by business units. For information on how to obtain access to this API in production, see the Buy APIs Requirements.This method searches for sold eBay items by various URI query parameters and retrieves the sales history of the items for the last 90 days. You can search by keyword, category, eBay product ID (ePID), or GTIN, or a combination of these.
This method also supports the following:
For details and examples of these capabilities, see Browse API in the Buying Integration Guide.
There are pagination controls (limit and offset fields) and sort query parameters that control/sort the data that is returned. By default, the results are sorted by "Best Match". For more information about Best Match, see the eBay help page Best Match.
Query parameter values need to be URL encoded. For details, see URL encoding query parameter values.
This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see API Restrictions.
", "operationId": "search", "parameters": [ { "name": "aspect_filter", "in": "query", "description": "This query parameter lets you filter by item aspects. The aspect name/value pairs and category, which is required, is used to limit the results to specific aspects of the item. For example, in a clothing category one aspect pair would be Color/Red. The results are returned in the refinement container./buy/marketplace_insights/v1_beta/item_sales/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red|Blue}
ASPECT_REFINEMENTS
. /buy/marketplace_insights/v1_beta/item_sales/search?q=shirt&category_ids=15724&fieldgroups=ASPECT_REFINEMENTS
aspectName:{value1|value2}
137084
, the results will be limited to 'Men's Athletic Apparel'. For example: /buy/marketplace-insights/v1_beta/item_sales/search?q=shirt&category_ids=137084
The list of eBay category IDs is not published and category IDs are not the same across all the eBay marketplaces. You can use the following techniques to find a category by site:
/buy/marketplace-insights/v1_beta/item_sales/search?epid=241986085&category_ids=168058
/buy/marketplace-insights/v1_beta/item_sales/search?q=iphone&category_ids=15724&filter=price:[50..500],priceCurrency:USD
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/marketplace_insights/types/cos:FilterField",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "gtin",
"in": "query",
"description": "This query parameter lets you search by the Global Trade Item Number of the item as defined by https://www.gtin.info. This can be a UPC (Universal Product Code), EAN (European Article Number), or an ISBN (International Standard Book Number) value. /buy/marketplace-insights/v1_beta/item_sales/search?gtin=241986085&category_ids=9355
/buy/marketplace-insights/v1_beta/item_sales/search?q=iphone,ipad&category_ids=15724
/buy/marketplace-insights/v1_beta/item_sales/search?q=iphone&category_ids=15724 ipad
/buy/marketplace-insights/v1_beta/item_sales/search?q=iphone, ipad&category_ids=15724
*
wildcard character is not allowed in this field. -
before the field name. Currently, you can only sort by price (in ascending or descending order). Sort | Result |
---|---|
&sort=price | Sorts by price in ascending order (lowest price first) |
&sort=-price | Sorts by price in descending order (highest price first) |
affiliateCampaignId=ePNCampaignId,affiliateReferenceId=referenceId
in the header in order to be paid for selling eBay items on your site.ASPECT_REFINEMENTS
or FULL
in the request."
},
"BuyingOptionDistribution": {
"type": "object",
"properties": {
"buyingOption": {
"type": "string"
},
"matchCount": {
"type": "integer",
"description": "The number of items having this buying option.",
"format": "int32"
},
"refinementHref": {
"type": "string",
"description": "The HATEOAS reference for this buying option."
}
},
"description": "The container that defines the fields for the buying options refinements. This container is returned when fieldgroups is set to BUYING_OPTION_REFINEMENTS
or FULL
in the request."
},
"Category": {
"type": "object",
"properties": {
"categoryId": {
"type": "string",
"description": "The unique identifier of the primary item category of the item, as well as the secondary item category if item was listed in two categories."
}
},
"description": "This type is used by the categories container in the response of the search method, and contains the primary item category ID of the item, as well as the secondary item category if the item was listed in two categories."
},
"CategoryDistribution": {
"type": "object",
"properties": {
"categoryId": {
"type": "string",
"description": "The identifier of the category."
},
"categoryName": {
"type": "string",
"description": "The name of the category, such as Baby & Toddler Clothing."
},
"matchCount": {
"type": "integer",
"description": "The number of items in this category.",
"format": "int32"
},
"refinementHref": {
"type": "string",
"description": "The HATEOAS reference of this category."
}
},
"description": "The container that defines the fields for the category refinements. This container is returned when fieldgroups is set to CATEGORY_REFINEMENTS
or FULL
in the request."
},
"ConditionDistribution": {
"type": "object",
"properties": {
"condition": {
"type": "string",
"description": "The text describing the condition of the item, such as New or Used. For a list of condition names, see ConditionEnum. CONDITION_REFINEMENTS
or FULL
in the request."
},
"ConvertedAmount": {
"type": "object",
"properties": {
"convertedFromCurrency": {
"type": "string",
"description": "A three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value represents the pre-conversion currency. For implementation help, refer to eBay API documentation"
},
"convertedFromValue": {
"type": "string",
"description": "The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. The value field contains the converted amount of this value, in the currency specified by the currency field."
},
"currency": {
"type": "string",
"description": "A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This value represents the post-conversion currency of the amount in the value field. For implementation help, refer to eBay API documentation"
},
"value": {
"type": "string",
"description": "The monetary value in the currency specified in the currency field."
}
}
},
"Error": {
"type": "object",
"properties": {
"category": {
"type": "string",
"description": "Identifies the type of erro."
},
"domain": {
"type": "string",
"description": "Name for the primary system where the error occurred. This is relevant for application errors."
},
"errorId": {
"type": "integer",
"description": "A unique number to identify the error.",
"format": "int32"
},
"inputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"longMessage": {
"type": "string",
"description": "A more detailed explanation of the error."
},
"message": {
"type": "string",
"description": "Information on how to correct the problem, in the end user's terms and language where applicable."
},
"outputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
"description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.",
"items": {
"$ref": "#/components/schemas/ErrorParameter"
}
},
"subdomain": {
"type": "string",
"description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc."
}
},
"description": "This type defines the fields that can be returned in an error."
},
"ErrorParameter": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The object of the error."
},
"value": {
"type": "string",
"description": "The value of the object."
}
}
},
"Image": {
"type": "object",
"properties": {
"height": {
"type": "integer",
"description": " Reserved for future use. ",
"format": "int32"
},
"imageUrl": {
"type": "string",
"description": "The URL of the image."
},
"width": {
"type": "integer",
"description": " Reserved for future use. ",
"format": "int32"
}
},
"description": "Type the defines the details of an image, such as size and image URL. Currently only imageUrl is populated. The height and width were added for future use."
},
"ItemLocation": {
"type": "object",
"properties": {
"addressLine1": {
"type": "string",
"description": "The first line of the street address."
},
"addressLine2": {
"type": "string",
"description": "The second line of the street address. This field may contain such values as an apartment or suite number."
},
"city": {
"type": "string",
"description": "The city in which the item is located. "
},
"country": {
"type": "string",
"description": "The two-letter ISO 3166 standard code that indicates the country in which the item is located. For implementation help, refer to eBay API documentation"
},
"county": {
"type": "string",
"description": "The county in which the item is located."
},
"postalCode": {
"type": "string",
"description": "The postal code (or zip code in US) where the item is located.951**
."
},
"stateOrProvince": {
"type": "string",
"description": "The state or province in which the item is located."
}
},
"description": "The type that defines the fields for the locaton of an item, including postal code, county, state/province, street address, city, and country (2-digit ISO code)."
},
"ItemSales": {
"type": "object",
"properties": {
"additionalImages": {
"type": "array",
"description": "An array of containers with the URLs for the images that are in addition to the primary image. The primary image is returned in the image.imageUrl field.",
"items": {
"$ref": "#/components/schemas/Image"
}
},
"adultOnly": {
"type": "boolean",
"description": "This indicates if the item is for adults only. For more information about adult-only items on eBay, see Adult items policy for sellers and Adult-Only items on eBay for buyers."
},
"bidCount": {
"type": "integer",
"description": "This integer value indicates the total number of bids that have been placed for an auction item. This field is only returned for auction items.",
"format": "int32"
},
"buyingOptions": {
"type": "array",
"description": "A comma separated list of the purchase options available for the item, such as FIXED_PRICE, AUCTION. FIXED_PRICE
- Returned for fixed-price items (non-auction)AUCTION
- Returned for auction items without Buy It Now featureFIXED_PRICE
and AUCTION
- Returned for auction items enabled with the Buy It Now featureX-EBAY-C-ENDUSERCTX
request header in the method."
},
"itemGroupHref": {
"type": "string",
"description": "The HATEOAS reference of the parent page of the item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. SELLER_DEFINED_VARIATIONS
group type is supported and indicates that this is an item group created by the seller.X-EBAY-C-MARKETPLACE-ID
request header specifying the supported marketplace (such as EBAY_GB
) to see VAT-inclusive pricing. For more information on VAT, refer to VAT Obligations in the EU.",
"$ref": "#/components/schemas/ConvertedAmount"
},
"seller": {
"description": "This container returns basic information about the seller of the item, such as name, feedback score, etc.",
"$ref": "#/components/schemas/Seller"
},
"thumbnailImages": {
"type": "array",
"description": "An array of thumbnail images for the item. ",
"items": {
"$ref": "#/components/schemas/Image"
}
},
"title": {
"type": "string",
"description": "The seller-created title of the item. https://api.ebay.com/buy/marketplace_insights/v1_beta/item_sales/search?q=shirt&&limit=5&offset=0
"
},
"itemSales": {
"type": "array",
"description": "The type that defines the fields for a paginated result set of the sold items. The response consists of 0 or more sequenced result sets where each result sets has 0 or more items.SELLER_DEFINED_VARIATIONS
group type that might result in multiple transactions, only one deduped transaction is returned in the search results.",
"items": {
"$ref": "#/components/schemas/ItemSales"
}
},
"limit": {
"type": "integer",
"description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
"format": "int32"
},
"next": {
"type": "string",
"description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set. 0
.total
is just an indicator of the number of listings for a given query. It could vary based on the number of listings with variations included in the result. It is strongly recommended that total
not be used in pagination use cases. Instead, use next to determine the results on the next page.",
"format": "int32"
}
}
},
"Seller": {
"type": "object",
"properties": {
"feedbackPercentage": {
"type": "string",
"description": "The percentage of the total positive feedback."
},
"feedbackScore": {
"type": "integer",
"description": "The feedback score of the seller. This value is based on the ratings from eBay members that bought items from this seller.",
"format": "int32"
},
"username": {
"type": "string",
"description": "The username created by the seller for use on eBay."
}
},
"description": "The type that defines the fields for basic information about the seller of the item."
}
},
"securitySchemes": {
"api_auth": {
"type": "oauth2",
"description": "The security definitions for this API. Please check individual operations for applicable scopes.",
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
"scopes": {
"https://api.ebay.com/oauth/api_scope/buy.marketplace.insights": "View historical sales data to help buyers make informed purchasing decisions"
}
}
}
}
}
}
}