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:

the grapes used in the making of wine.

Regions:

hierarchical structure of wine growing regions and appellations of the world.

Wineries:

wineries that produce wine (i.e. legal/business entities).

Winery Brands:

the labels or product lines of wineries.

Winery Locations:

tasting room and production locations including amenities, policies, GPS coordinates, contact information, hours, and more.

Wines:

the produced wine and its released products/SKUs.

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.

URL: /search/varieties/all

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

URL: /search/brands/byvariety

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.

URL: /search/locations/all

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.

4 Responses to “Wine Search API”

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

  2. James says:

    Hi Kyle.

    This is a bug on our side. It’s been fixed.

    Thank you for bringing this to our attention!

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

  4. James says:

    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?