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. |
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. |
