This page includes some of the most common questions asked about the API. If your question is not answered here, you can ask it in a comment below or send us an email.

General

Q: What is the API? What can I do with it and who is it for?

A: The VinTank API provides a RESTful application programming interface to allow partner applications to integrate with VinTank to access detailed data on entities such as wineries, wines, regions, (wine grape) varieties, and more.

Any application, service, or site that needs access to winery and wine data can integrate with the API. Be sure to tell us about your business and how you anticipate using the API.

VinTank will also be releasing a premium set of APIs that provide sophisticated processing and business functions. The premium APIs will be fee based. Please contact VinTank for more information on these APIs.

Q: What is the status of the API? What does “beta” mean?

A: The API is currently in beta. This means the API is still under development and is subject to change. Feedback from beta users is critical to resolving issues and making improvements.

Q: Do I need to sign up for the API?

A: Yes, API credentials are needed for all API requests. See getting started for details on how to sign up.

Q: Do I have any obligations by using the APIs?

A: If you cache or persist any data obtained from the APIs and provide services on your site or in your application based on that data, you must capture usage statistics for that data and report those statistics back to VinTank. These statistics can be aggregated and should be anonymous (i.e. no user information should be included). Please see the API Cross Data License Agreement for more details.

If you do NOT cache or persist data obtained from the APIs, you have no obligations to report usage statistics since the API has built-in usage tracking.

Q: Are there any rate limits imposed by the API?

A: Yes, rate limiting is implemented at the client (i.e. IP address) and application (i.e. AppId) levels. You will know that you are being rate limited when you receive a HTTP 440 response from an API call. The response will also include the Retry-After HTTP header with a value indicating the number of seconds you should wait before submitting API requests again.

See the Response Codes and Errors page for more information.

If you feel that your application needs a higher rate limit, contact us.

Q: How does authentication work?

A: There are a few different authentication models supported by the API. Since we wanted the API to be easily explorable by developers using only their web browser, HTTP Digest authentication is transparently supported. When prompted for a user name and password by your browser, just paste in your AppId as the user name and Secret as the password. Of course you can also use HTTP Digest in your integration code but we support alternative authentication options which will be easier to implement.

See the Authentication page for details.

The Partner Link API has its own authentication requirements. Please see the the Partner Link documentation for details.

Q: When I do a search using one of the API entry points, only a small number of data elements are returned for each item. I was expecting more. What gives?

A: Since most entities include a large number of data elements, the search results only include what we have determined are the most useful subset of all possible data elements for each entity. To get all data elements for an entity, perform a detail request. The URL for for the details is included in the search results as the <h1> link (POSH) or the JSONLink value (JSON).

Q: Are there any libraries, wrappers, or sample code I can look at?

A: Yes, please see the Tools / Libraries page. We also welcome developer community submissions of sample code or libraries/wrappers.

Wineries, Winery Locations & Winery Brands

Q: What is the relationship of a winery to a winery brand?

A: In the VinTank data model we have separated the business aspect of a winery from the merchandising of one or more brands that it may produce. This distinction allows us to separate business/legal information of a winery such as its official business name from the brand name that it may use on its labels. Often the winery name and brand name are the same but that is not always the case. In addition since a winery can have multiple brands, the wines of several brands can be independently identified but still connect back to the “owning” winery.

When using the API, most of the time you’ll want to search brands since that is how wines are represented.

Q: How about enterprise wine companies that own several distinct wineries?

A: The wineries of enterprise wine companies are most often represented as separate wineries rather than brands. This is one of the more difficult aspects of the wine industry to model but the general rule of thumb is that if the wines for multiple “labels” are produced under one roof (i.e. the same winemaking facility), those are brands. On the other hand, if the wines are made in separate facilities, in separate locations, with separate tasting rooms and winemakers, and/or are mostly run independent, those would be separate wineries.

Q: Can I search for winery locations?

A: Yes! See the Winery Location section on the Search API page. Not only will you be able to search based on physical location but you’ll also be able to combine location attributes such as the “open to the public” setting, picnic policies, tasting policies, hours of operation, and lots more in your queries.

In addition to the base location search parameters, you can also specify a geographic point (i.e. latitude/longitude) and a radius to constrain your search. Please contact VinTank to enable geographic searching for your AppId.

Q: What winery brand information is available through the API?

A: The VinTank data model is very comprehensive and supports lots of details for wineries and winery brands. For example, varieties produced, wine products produced, online identities (email, website, storefront, blog, Facebook page, Twitter handle, and so on). Of course, the wines themselves are also related to brands (covered in more detail below).

Q: What about digital media such as logos and tasting room photographs?

A: Digital media is fully supported in the data model at the winery brand level. For image types hosted/managed by VinTank, multiple sizes are available (thumbnail, small, medium, large). Non-image media such as PDFs and audio/video are also supported. Media can be hosted/managed by VinTank or indirectly linked to an external location. It all depends on how the media was added to the system.

For winery brands, media are categorized by type and include logo, photograph, audio & video (i.e. reviews, tours, …), QR Code images, winery owner photographs, winemaker photographs, and viticulturist photographs.

Note that links to all digital media, including multiple sizes per media asset, for a brand or location are available on detail results only. The search results only include a link to the thumbnail for the brand’s logo.

Wines

Q: How are wines related to a winery?

A: Wines are related to a winery through a winery brand. That’s another reason why it’s important to use the brand API when, say, looking for wines for a brand. Of course, as described above in the winery section, winery brands are related to wineries so the connection to a winery can also be made.

Q: How is wine information related to actual wine products/SKUs?

A: Wine information is separated from SKU information in the data model such that a single wine can have one or more SKUs. Think of the “wine” as the liquid itself and the SKU as a packaged representation of the wine. Attributes of a wine would therefore include information such as the vintage, brand, variety(ies), region, winemaker, pH, and ABV where a SKU would include the container type (750 mL bottle, magnum, Tetra Pak, …), closure (cork, screwcap, …), bottle date, release date, suggested retail price, buy URL and so on.

There are several more data points available in the data model. It’s best to explore the API.

Q: What about digital media such as label images and bottle shots?

A: Digital media is fully supported in the data model for wines. For image types hosted/managed by VinTank, multiple sizes are available (thumbnail, small, medium, large). Non-image media such as PDFs and audio/video are also supported. Media can be hosted/managed by VinTank or indirectly linked to an external location. It all depends on how the media was added to the system.

For wines, media are categorized by type and include front label, back label, bottle shot, shelf talker, QR Code image, photographs, audio (i.e. podcast review), and video.

Note that links to all digital media, including multiple sizes, for a wine are available on detail results only. The search results only include a link to the thumbnail for the wine’s front label.

Q: How can I get all wines for a winery or brand?

A: All you need is the ynpid for the winery or ynbid for the brand. Then call the wine search endpoint specifying the ynpid/ynbid on your query. You can discover the ynpid or ynbid for a winery or brand via API search or manually from the Wine Directory (i.e. for one-off situations).

Q: Can I query wines by price?

A: Yes, the Find Wines by Query endpoint allows you to search by suggested retail price including by currency code and container/bottle size.

Q: Can I query wines by UPC/GTIN?

A: Yes, the Find All Wines endpoint of the Search API supports searching for wines by UPC/GTIN. Your UPC/GTIN must be valid (i.e. numeric and including check digit).

Regions

Q: What are regions?

A: Wine regions in the VinTank data model are used to represent both geographic and regulated appellations. Regions are organized into a hierarchical or nested set structure. This allows for arbitrary depth in the structure for each country and ultimately a more accurate representation. Accurately and completely mapping wine industry meta data such as regions and appellations is a daunting task and can often be open to interpretation. Although we have taken every effort to ensure all regions and appellations are represented, we know we have missed some. Please let us know if you see a discrepancy in the region data and we’ll get it captured. Ultimately we hope that we can all benefit from a comprehensive region/appellation model. It takes a village!

Varieties

Q: How are varieties represented in the system?

A: Similar to wine regions, we have organized a fairly comprehensive collection of wine grape varieties. The data model supports relating multiple variety names to a base variety where each name can even have locale-specific preference. For example, it’s Mourvèdre in France but it’s Mataró in Portugal and Monastrell in Spain; all are still related to the same base variety. Of course, it’s common (especially in New World wines) to break from regional variety naming customs so the system separates the specific variety name for a wine (or compositional element for a wine). Since names are all connected behind the scenes, though, we still know that wine with Mourvèdre on the label is the same grape as one with Mataro on the label.

For appellations with regulated varieties, the connection back to the variety can also be made. For example, the Barolo appellation requires wines to be made of 100% Nebiollo so we know a wine labeled as a Nebiollo is made from the same grapes as a Barolo.

---

If your question is still not answered, please contact us or leave a comment below.