Wine Search API
There are a number of service endpoints used to search across resources in the VinTank API v1.
There are six searchable entity types in the VinTank API at this time.
Varieties:
Regions:
Wineries:
Winery Brands:
Winery Locations:
Wines:
All URLs are relative to the VinTank API site http://apiv1.cruvee.com/
Unless otherwise noted a search query is passed to an endpoint via the parameter q.
IMPORTANT: Parameter names are case-sensitive. Also be sure to URL-encode all query string parameter values.
Authentication
Be sure to review and understand the API’s authentication requirements before coding against the API.
Forming a Request
All of these search resources use HTTP requests with a GET method. Therefore creating a request to the search api is as simple as forming a string value. The following is an example of a request:
http://apiv1.cruvee.com/search/varieties/all?commonality=common%2Cvery_common&orderby=name+desc
This request consists of two query parameters named commonality and orderby. These parameters are being passed to the endpoint /search/varietals/all. Notice too that the comma in the commonality parameter value is escaped as “%2C”.
All parameters listed within this document are case sensitive. This means that when forming a request URL you must use the same exact letter casing as documented here.
Getting Results That You Can Use
When using the VinTank Search API you can have your results in either JSON or XHTML formats. The JSON is of course most useful in applications for mobile and javascript heavy web applications but also works very well in server-side implementations. The XHTML format leverages applicable microformats and microformat design patterns. This allows the XHTML responses to be parsed as XML or embedded directly into a website (and styled with CSS) or as an XML document. An additional benefit of this format is that it is easily digested by search engine web crawlers and requires very little work to be useful in a site. It is also not entirely difficult to apply an XSLT transform to alter the XHTML document’s format or to use a XML parser to remove the data itself (though JSON will likely be a better choice for the latter).
Note that the fields/datapoints returned by each format should be consistent but there may be some differences. In general, though, JSON is the most complete format.
See the ‘fmt’ query parameter in the next section for details on requesting a given format.
Compact vs. Full Response Format
An important aspect of the API to keep in mind is that entity listing and search results use a compact response format. That is, only a subset of all possible data points are returned for each entity in a listing or search response. Therefore, it’s possible that a field you need is not in the compact form. To get the full response format for an entity (i.e. all possible data points), you will have to make a detail request for each entity. The listing/search response includes URLs for accessing each entity (see the “JSONLink” field/element for JSON and the link within the <h1> element for POSH responses).
This approach reflects the 80-20 rule where the fields included in the compact form satisfy the needs of the vast majority of requests. This also results in smaller overall response size for listing and search results. Since our data model supports so many fields (and at variable depths), including all possible fields would dramatically increase listing and search results sizes and response times.
If you feel that a field should be included in the compact form, please let us know. We are always willing to make changes when it makes sense.
Common query parameters
These go in the URL of a request to the API and are common across all of the endpoints here unless noted in an endpoint’s description.
| Name | Description | Required |
|---|---|---|
| page | The page number in the search results to return | false |
| rpp | Number of results per page to display (max is 50) | false |
| q | The query for the search. Ex. ‘marsanne’. | true |
| fmt | response format, value is either ‘html’ or ‘json’. Default response format is html (POSH). | false |
Field Group Statistics
Several of the endpoints below support field group statistics. For each group field specified in your request, your response will include counts for the top 20 unique values for the grouped field ordered descending by count. All counts are constrained based on your query and filter parameters on your request. For example, if you search all wines in Napa Valley (i.e. specifying “ynrid” as a filter) and group by “variety”, your response will include group statistics for up to the top 20 varieties for all wines in Napa Valley. Grouping statistics are very helpful when building a faceted search implementation. See below for each endpoint for details.
Field grouping statistics are currently only returned when using the JSON response format.
Find Varieties by Query
Given the name of a variety/grape, search for matching varieties. Results are ordered by relevance.
| Name | Description | Required |
|---|---|---|
| groupFields | a value of wineType will provide field group counts for the wine types of the matching varieties | false |
URL: /search/varieties
Find All Varieties
Returns all of the varieties. Can be filtered down by passing applicable parameters. NOTE the query parameter q is not used in this endpoint.
| Name | Description | Required |
|---|---|---|
| orderby | either name or commonality followed by an optional +desc or +asc | false |
| commonality | any one of the following, or a comma separated list of one or more. common, uncommon, very_common, most_common. IMPORTANT: if specifying multiple values, be sure to escape your comma(s) in your request URL as %2C. | false |
Find Region(s) by Query
Given a query search for matching regions.
URL: /search/regions
| Name | Description | Required |
|---|---|---|
| ynrid | a VinTank ynrid that specifies a region to search within. For example, to restrict your search to regions/appellations within France, use the ynrid value for France here. | false |
| groupFields | Group counts are supported for region, winery, and/or brand | false |
Find All Regions
Return all of the regions. Can be filtered down by passing applicable parameters. NOTE the query parameter q is not used in this endpoint.
URL: /search/regions/all
| Name | Description | Required |
|---|---|---|
| ynrid | a VinTank ynrid that specifies a region to constrain results within. For example, to only return the regions/appellations within California, use the ynrid for California here. | false |
Find Wineries by Query
Given a query search for matching wineries. Be sure that you understand the relationship between wineries and brands in the data model (i.e. the Winery Brand search may be more appropriate depending on what you are interested in).
URL: /search/wineries
| Name | Description | Required |
|---|---|---|
| ynrid | a VinTank ynrid that specifies a region to search within. | false |
| groupFields | Group counts are supported for region | false |
Find All Wineries
Return all of the wineries. Be sure that you understand the relationship between wineries and brands in the data model (i.e. the Winery Brand search may be more appropriate depending on what you are interested in). Can be filtered down by passing applicable parameters. NOTE the query parameter q is not used in this endpoint.
URL: /search/wineries/all
| Name | Description | Required |
|---|---|---|
| ynrid | a VinTank ynrid that specifies a region to constrain results within | false |
Find Winery Brand(s) by Query
Given a query search for matching winery brands.
URL: /search/brands
| Name | Description | Required |
|---|---|---|
| ynrid | a VinTank ynrid that specifies a region to search within | false |
| ynpid | a VinTank ynpid that specifies a winery parent to a brand to search within | false |
| ynvid | a VinTank ynvid that specifies a variety produced by the brand to filter results. Note that this filter applies to the varieties as defined at the brand level and is NOT derived based on wines for the brand | false |
| groupFields | Group counts are supported for wineType, variety, region, and winery | false |
Find All Winery Brand(s)
Return all of the brands. Can be filtered down by passing applicable parameters. NOTE the query parameter q is not used in this endpoint.
URL: /search/brands/all
| Name | Description | Required |
|---|---|---|
| ynrid | a VinTank ynrid that specifies a region to search within | false |
| ynpid | a VinTank ynpid that specifies a winery parent to a brand to search within | false |
Find Winery Brand(s) by Variety
Given a query which identifies one or more wine varieties, find wineries that produce given variety(s).
| Name | Description | Required |
|---|---|---|
| ynrid | a VinTank ynrid that specifies a region to search within | false |
| ynpid | a VinTank ynpid that specifies a winery parent to a brand to search within | false |
| wineType | One of the following: red, white, rose, sparkling_white, sparkling_red, port, dessert, fruit_berry, mead, other | false |
Find Wine by Query
Given a query search for matching wines.
URL: /search/wines
Also see, Sample JSON response and overview of Wine Names.
| Name | Description | Required |
|---|---|---|
| ynrid | a VinTank ynrid that specifies a region to search within | false |
| ynbid | a VinTank ynbid that specifies a winery brand to search within | false |
| ynpid | a VinTank ynpid that specifies a winery parent to a brand to search within | false |
| ynvid | a comma separated list of VinTank ynvid’s representing the varieties that must be declared or included as a component of each returned wine (see declaredVariety and disjunctVariety for how this filter is applied). A maximum of 5 varieties may be specified. | false |
| declaredVariety | indicates how the ynvid parameter should be interpreted. If true, the ynvid(s) will be matched against the declared variety for the wine. Otherwise the ynvid(s) will be matched against the varieties in the wine’s composition. Default is true. | false |
| disjunctVariety | if multiple varieties are specified for the ynvid parameter, this parameter indicates whether “OR” or “AND” logic should be used to match wines. Use true for “OR” and false for “AND”. Default is true. | false |
| wineType | one of the following: red, white, rose, sparkling_white, sparkling_red, port, dessert, fruit_berry, mead, other. Only wines for this type are returned. | false |
| gtin | a GTIN-14, UPC-A/UPC-E, or EAN-13. Include the check-digit if you have it. Otherwise the API will attempt to coerce a code without a check-digit if possible. | false |
| vintage | required vintage for returned wines. For example, “2008″. Use “NV” to return wines declared as non-vintage. Note that wines without a vintage are NOT considered non-vintage. In other words, they must be declared as non-vintage. | false |
| soldOut | indicates if only sold out wines (that is, sold out at winery) should be returned. A wine is marked as sold out iff the wine has one or more products/SKUs defined and all of those products/SKUs are declared as sold out. Use true to return sold out wines. Default is to return all wines regardless of sold out value. | false |
| currRelease | indicates if only wines declared as current releases should be returned. Use true to return current releases. Default is to return all wines regardless of current release value. | false |
| priceLow | indicates low end of price range to return wines. For example, “20″ or “19.99″. If specified and priceHigh is not specified, all wines at priceLow and above are returned. Learn more | false |
| priceHigh | indicates high end of price range to return wines. For example, “20″ or “19.99″. If specified and priceLow is not specified, all wines at priceHigh and below are returned. Learn more | false |
| priceCode | indicates the ISO 4217 3-letter currency code required for products/SKUs for price range queries. For example, “USD” or United States dollars. Since every product/SKU price includes the currency code and filtering by the numeric value along can be misleading, you can use this parameter to focus results on a particular currency. Note that price values are NOT converted to multiple currencies in VinTank. The price and currency we have is what was entered/imported. Learn more | false |
| priceSize | indicates the container size, in milliliters, required for products/SKUs for price range queries. For example, “750″ for 750mL containers (i.e. the typical wine bottle size). A Container Type constant can also be specified (i.e. “BOTTLE_1500ML” for 1500mL/magnum size). Note that if a Container Type constant is specified, only the size is used in the query and not the container’s material or shape. Learn more | false |
| groupFields | Group counts are supported for wineType, vintage, containerType, price, priceSize, priceSizeCurrCode, priceCurrCode, declaredVariety, variety, region, brand, and winery | false |
| orderby | either name, wineType, vintage, price, or winery followed by an optional +desc or +asc. The default sort order is by relevance to your query. | false |
About Searching Wines by Price
When searching wines by price, it is important to understand a bit more about the VinTank data model. In VinTank, a “wine” represents a finished wine but does NOT represent a packaged wine. Since a finished wine can be released in multiple container types/sizes, each wine in VinTank can have zero or more products or SKUs. Therefore a wine product/SKU is a packaged representation of a wine. For example, if a wine is released in 750mL bottles and 1.5L bottles, it will have two products. Now, when it comes to price, the price is an attribute of the product/SKU and not the wine. So when you search by price but do not specify a priceSize, you will get back wines of all sizes/containers that match your price range. Similarly, when you do not specify priceCode (for the currency code), you will get back wines for all currencies based just on the numeric value of the price.
IMPORTANT: Since wine products/SKUs and price are not required by the data model, filtering by price will reduce your results to wines with products/SKUs with prices specified.
Find All Wines
Return all of the wines. Can be filtered down by passing applicable parameters. NOTE the query parameter q is not used in this endpoint.
URL: /search/wines/all
| Name | Description | Required |
|---|---|---|
| gtin | a GTIN-14, UPC-A/UPC-E, or EAN-13. Include the check-digit if you have it. Otherwise the API will attempt to coerce a code without a check-digit if possible. | false |
| ynrid | a VinTank ynrid that specifies a region to search within | false |
| ynbid | a VinTank ynbid that specifies a winery brand to search within | false |
| ynpid | a VinTank ynpid that specifies a winery parent to a brand to search within | false |
Find Winery Locations
Given a query search for matching winery locations.
URL: /search/locations
| Name | Description | Required |
|---|---|---|
| ynrid | a VinTank ynrid that specifies a region to search within | false |
| openToPublic | Is this location designated as open to the public (either as walk-in or by appointment)? For example, tasting rooms are typically marked as open to the public while mailing addresses and administrative locations are not. Values can be true, false, yes, no. | false |
| familyFriendly | does this location allow/welcome children? Values can be true, false, yes, no. | false |
| dogok | does this location allow dogs? Values can be true, false, yes, no. | false |
| caves | does this location have caves? Values can be true, false, yes, no. | false |
| historic | is the location a historic one? Values can be true, false, yes, no. | false |
| gardens | are there gardens at the location? Values can be true, false, yes, no. | false |
| weddingSpace | does this location host weddings? Values can be true, false, yes, no. | false |
| meetingSpace | does this location host meetings? Values can be true, false, yes, no. | false |
| artExhibit | does this location host art work? Values can be true, false, yes, no. | false |
| type | the location’s type. Value can be mailing, tasting, production. | false |
| tasting | does this location do wine tastings? Values can be yes, no, by_appointment. | false |
| tastingCharge | does this location charge for tastings? Values can be yes, no, refunded_with_purchase. | false |
| tours | does this location host tours? Values can be yes, no, by_appointment, self_guided. | false |
| picnicPolicy | Picnic policy at this location. Values can be yes, no, onsite_food_only. | false |
| setting | does this location host art work? Values can be rural, town, city, urban. | false |
| limos | does this location allow limosines? Values can be yes, no, by_appointment. | false |
| buses | does this location allow buses? Values can be yes, no, by_appointment. | false |
Geographic Location Searches
Winery locations can also be filtered based on geographic coordinates (i.e. latitude/longitude) and a search radius to limit to locations returned. The geographic point can be combined with any of the parameters described above. By default, locations are returned ordered by distance from the queried point.
Please contact VinTank to request enabling geographic searches for your AppId..
| Name | Description | Required |
|---|---|---|
| lat | Must be a valid latitude value of -90 to 90 in decimal notation. | true (for geographic searches) |
| lng | Must be a valid longitude value of -180 to 180 in decimal notation. | true (for geographic searches) |
| radius | Must be a value greater than 0 and less than or equal to 50. This is optional and will default to 15 if not specified. | false |
| unit | Must be either km or miles and is used to interpret the value for the radius parameter. This is optional and will default to ‘km’ if not specified. | false |
Find all Winery Locations
Return all of the winery locations. Can be filtered down by passing applicable parameters. NOTE the query parameter q is not used in this endpoint.
| Name | Description | Required |
|---|---|---|
| ynrid | a VinTank ynrid that specifies a region to search within | false |
| openToPublic | Is this location designated as open to the public (either as walk-in or by appointment)? For example, tasting rooms are typically marked as open to the public while mailing addresses and administrative locations are not. Values can be true, false, yes, no. | false |
| familyFriendly | does this location allow/welcome children? Values can be true, false, yes, no. | false |
| caves | does this location have caves? Values can be true, false, yes, no. | false |
| historic | is the location a historic one? Values can be true, false, yes, no. | false |
| gardens | are there gardens at the location? Values can be true, false, yes, no. | false |
| dogok | does this location allow dogs? Values can be true, false, yes, no. | false |
| weddingSpace | does this location host weddings? Values can be true, false, yes, no. | false |
| meetingSpace | does this location host meetings? Values can be true, false, yes, no. | false |
| artExhibit | does this location host art work? Values can be true, false, yes, no. | false |
| type | the location’s type. Value can be mailing, tasting, production. | false |
| tasting | does this location do wine tastings? Values can be yes, no, by_appointment. | false |
| tastingCharge | does this location charge for tastings? Values can be yes, no, refunded_with_purchase. | false |
| tours | does this location host tours? Values can be yes, no, by_appointment, self_guided. | false |
| picnicPolicy | Picnic policy at this location. Values can be yes, no, onsite_food_only. | false |
| setting | does this location host art work? Values can be rural, town, city, urban. | false |
| limos | does this location allow limosines? Values can be yes, no, by_appointment. | false |
| buses | does this location allow buses? Values can be yes, no, by_appointment. | false |
Response Codes
See the response codes and errors page for details on API responses codes.
Hi! I am trying to grab json data from the /search/varieties/all endpoint using the URL: http://apiv1.cruvee.com/search/varieties/all?fmt=json but the response I get is in HTML. Does this endpoint have a json format available? Thanks!
Hi Kyle.
This is a bug on our side. It’s been fixed.
Thank you for bringing this to our attention!
Compact vs Full: not so helpful.
Couldn’t we at least specify in the search results whether we need all the fields or not? Currently, the search results return things like accolades, but not vastly more important data like the entire “text” part, which contains the description and winemakers notes.
In fact, near as I can tell, the *only* thing that the search results exclude is the description and winemaker’s notes. Forcing my script to make an extra call for just those two fields seems kinda pointless – why not just return those as well, and be done with it?
Equally, if compact is an important format, maybe it should be a lot more compact – just the wine name, description, and a link to the JSON page.
Thank you for the feedback, Rob. Sorry that the response forms are not working for you. There are in fact several fields that are in the full form that are not in the compact form, including accolades. Can you provide the API search URL that is returning accolades? They shouldn’t be in the compact form.
Since some of the full-only fields can increase the response size considerably (potentially into MBs per wine), always returning the full form will cause issues for clients calling directly from mobile apps over slow network connections.
Allowing the caller to indicate the level of detail included in the response is a great idea and something we have considered supporting. I also like your idea of an ulta-compact form. Perhaps allowing the caller pass a list of field names is another option to consider. Thoughts?