Wine.com Public API

Some Intro Text

Status Object

This object is returned with every query. It contains a status code, and any debugging information that might accompany an error.

Property Type Description
ReturnCode Numeric A numerical code that identifies the status. A number of 0 means everything worked correctly.
Messages String[] Returns a list of messages that contain debugging information to assist with correcting the issue.

The return codes are defined as:

Code Description
0 Everything worked, no problems.
100 A critical error was encountered. This is due to a bug in the service. Please notify wine.com ASAP to correct this issue.
200 Unable to Authorize. We cannot authorize this account.
300 No Access. Account does not have access to this service.

Return Objects

For each API query, there is a corresponding return object that contains data relevant to that query.

Catalog

This object is returned when a call is made to the Catalog API.

Property Type Description
Status Status Contains status and debugging information.
Products Products This object contains products that match the catalog query.

CategoryMap

This object is returned when a call is made to the Category Map API. It returns possible category matches based off a provided query.

Property Type Description
Status Status Contains status and debugging information.
Categories Category[] A list of categories that match the provided query.

Reference

This object is returned when a call is made to the Reference Library API.

Property Type Description
Status Status Contains status and debugging information.
Books Book[] A list of reference sections, or books.

Catalog Objects

These are objects that are returned with a Catalog API query. These objects may be used with other API queries, but they are primarily used when querying product catalog.

Products

This is a list of products.

Property Type Description
Total Numeric The total number of products that match the query. Not all products will be returned.
Offset Numeric The starting position in the entire list.
Url String The url to the list of wines.
List Product[] The actual list of products.

Product

This is the actual product object. When in a list format some of these values will be null. A full object will only be populated when the product identifier is specified in the query.

Property Type Description
Id Numeric A unique identifier for the product.
Name String The product name.
*Description String Additional information that may accompany the product.
*GeoLocation GeoLocation The location of the grapes, or winery, that produced this wine.
Url String The url to the product detail.
PriceMin Decimal The starting point for the price. Prices could be higher in certain markets, but they will never be lower than this price.
PriceMax Decimal The maximum price point across all markets for this product.
PriceRetail Decimal The suggested retail price for the product.
Type String Identifies the type of product that is being described. See the list of possible product type options.
Year String The year, or vintage of the product. If the product is not a bottle of wine, then the string will be empty. If the product is a bottle of wine, but has no vintage, it will have a designation of "Non-Vintage".
Appellation Appellation The appellation that the product belongs. Note, not all products have appellations. This can be null.
Varietal Varietal The varietal that the product belongs to. Note, not all products have a varietal. This can be null.
Vineyard Vineyard The vineyard that the product belongs to. Note, not all products have a vineyard. This can be null.
ProductAttributes ProductAttribute[] A collection of additional attributes that define the product.
Labels Label[] A collection of labels that go with the product.
Ratings Ratings A collection of ratings that have been given to the product.
Retail Retail Retail properties for the product. This is only available when the state is specified, otherwise it is null.
*Vintages Vintages A list of other vintages of this wine.
Community Community Wine.com community information.

* The items marked with an asterix are only available with "partner" access.

The Type property can be any of the following values. It is not defined as an enum because these values could change. Using a string value allows us to change the value without breaking code.

Type Description
Wine A bottle of wine.
WineSet A collection, or set, of wine.
Basket A gift basket.
Glassware A type of glassware used to serve wine (could be wine glass or a decanter).
Accessory A wine accessory, just as a corkscrew.

GeoLocation

Identifies a latitude and longitude for the location of the grapes, or winery, that produced the wine.

Property Type Description
Latitude Numeric The latitude of the location. If this data does not exist (or you do not have access to it), the value returned will be -360.
Longitude Numeric The longitude of the location. If this data does not exist (or you do not have access to it), the value returned will be -360.
Url String The url to a map of the wine.

Appellation

Property Type Description
Id Numeric A unique (Endeca) identifier for the appellation.
Name String The name of the appellation.
Url String The url to the other products in the same appellation.
Region Region The region that corresponds to the appellation.

Region

Property Type Description
Id Numeric A unique (Endeca) identifier for the region.
Name String The name of the region.
Url String The url to the other products in the same region.
Area Area The area that the region belongs to. This could be null.

Area

This defines a high level area that the wine belongs to. An example would be "New World", or "France".

Property Type Description
Id Numeric A unique (Endeca) identifier for the area.
Name String The name of the area.
Url String The url to the other products in the same area.
Parent Area If there is a higher area classification, this will be populated with the parent. An example could be an area called "Old World" which would be the parent of an area called "France". This could be null.

Varietal

Property Type Description
Id Numeric A unique (Endeca) identifier for the varietal.
Name String The name of the varietal.
Url String The url to other products that have the same varietal.
WineType WineType The type of wine that the varietal corresponds to.

WineType

Property Type Description
Id Numeric A unique (Endeca) identifier for the type of wine.
Name String The name of the type of wine.
Url String The url to other products that have the same wine type.

Vineyard

Property Type Description
Id Numeric A unique identifier for the vineyard.
Name String The name of the vineyard.
*GeoLocation GeoLocation The location of the vineyard.
Url String The url to the description of the vineyard.

* The items marked with an asterix are only available with "partner" access.

Label

Property Type Description
Id String A unique identifier for the label.
Name String The name, or description, of the label.
Url String The url to the label.

Ratings

Property Type Description
HighestScore Numeric The highest score given to the product.
*List Rating[] A collection of ratings that have been given to the product.

* The items marked with an asterix are only available with "partner" access.

Rating

Property Type Description
Id Numeric The unique (Endeca) id for the publication.
Name String The name, or description, of the review or publication.
Score Numeric The score given to the product.
Url String A url to other products that have been reviewed by the same publication.

ProductAttribute

This identifies other attributes that describe the product. Some examples would be "Kosher" or "Collectible" or "Screw Cap".

Property Type Description
Id Numeric The unique (Endeca) id for the attribute.
Name String The name, or description, of the attribute.
Url String A url to other products that have the same attribute.

Retail

This identifies retail values for the purchase of this product. Only available when the destination state is specified using the "state" url value.

Property Type Description
Sku String The unique sku for the product.
InStock Bool Indicates whether or not the product is in stock.
Price Decimal Wine.com sales price for the product.
Url String The url for purchasing this product.

Vintages

This is also referred to as pedigree. This is a list of past vintages of the selected product.

Property Type Description
List Vintage[] A specific vintage that the product is related to.

Vintage

This links a product to other vintages, and lists some additional attributes of these products.

Property Type Description
Id Numeric The product id of the related vintage.
Name String The year, or vintage, of the related product.
Ratings Ratings A collection of ratings that have been given to this specific vintage.
Url String The url to the product detail for this vintage.

Community

This object contains summaries the community content, as well as access to the more detailed community information.

Property Type Description
Reviews CommunityReviews A collection of reviews that community members have written.
*Lists CommunityLists A collection of lists that the product belongs to.
Url String The url to the product detail page that contains the community notes.

* The items marked with an asterix are only available with "partner" access.

CommunityReviews

Summaries all of the community reviews.

Property Type Description
HighestScore Numeric The highest review score given to the product.
*List CommunityReview[] A collection of reviews that have been given to the product.
Url String The url to the full list of reviews.

* The items marked with an asterix are only available with "partner" access.

CommunityReview

Property Type Description
Id Numeric The unique (Endeca) id for the publication.
Name String The name, or description, of the review or publication.
Score Numeric The score given to the product.
Description String The full description of the review.
Url String A url to other products that have been reviewed by the same publication.

Category Objects

Category

Property Type Description
Id Numeric The category identifier (Endeca Dimension Id).
Name String Descriptive name for the category.
Refinements Refinement[] The category options.

Refinement

A refinement is the actual category value.

Property Type Description
Id Numeric The refinement identifier (Endeca Dimension Value Id).
Name String Describe name for the refinement. "Red Wine" for example.
Url String A url to products that map to this category refinement. This includes the original filter. For example, if you are looking for all child categories for the category Red Wines, the Merlot value will include the Red Wine value.

Reference Objects

Book

A book is defined as a section of the Wine.com reference library. An example would be "Wine Basics" or "Selecting Wines".

Property Type Description
Id String The book identifier.
Name String Descriptive name for the book.
Articles Article[] The articles that make up the book.

Article

Property Type Description
Id String The article identifier.
Title String Descriptive name for the article.
Abstract String A short description, or abstract, for the article.
*Content String The article content. This is only populated when the article identifier is specified in the filter.
Url String A url to the article on the wine.com website.
Footnotes Footnote[] Footnotes to other articles that are related to this article.

* The items marked with an asterix are only available with "partner" access.

Footnote

Property Type Description
Id String The article identifier.
Title String Descriptive name for the article.
Url String A url to the article on the wine.com website.


Powered by 3Scale
Terms and Conditions | Privacy Policy | Contact Us