Social Search API

The VinTank Social API allows partners to tap into VinTank Social Connect event stream and historical index for wine conversations.

This is a premium API. Contact VinTank to learn more about enabling this API for your application.


Name Description Required
q Your query. Can be any wine related term or phrase including brand name, varietal name, region/appellation name, descriptor, … true
fmt Response format. Can be “json” or “html”. Note that “json” is currently the only response format that is fully implemented for this API. The default response format is “html”. false
callback JavaScript callback function to wrap around JSON response. This is useful when calling the API as a JavaScript URL to get around the same origin security policy. See examples below. Only relevant with the “json” response format. false
rpp Results per page between 0 and 50. Use a value of 0 if you just want event category totals. The default value is 10. false
page Results page number. The default value is 1. false
orderby How to order responses. Can be “publishDate” or “relevance”. When ordering by publishDate, events are ordered in reverse chronological order. Default value is “relevance”. false
hl Flag indicating whether each event’s title and post should be highlighted. That is, the matching term/phrase is wrapped in <em> tags. Default value is 1 (highlighting enabled). false
evtCategory Limit searching within a specific event category. Category names are “blog”, “microblog”, “forum”, “tasting_note”, “media”, and “check_in”. Multiple event categories can be specified by repeating this parameter multiple times. The default behavior is to search across all categories. false


The response format for the social API (JSON format) includes the following properties. It loosely follows the Activity Stream specification for JSON (still a moving target).

Property Description
id URI uniquely identifying the the search.
title Title for search results
page Page number of results. Echoed from request.
rpp Results per page. Echoed from request.
total Total number of matches for this query across all event categories that were searched.
blogMentions Total number of matches for the blog category.
microBlogMentions Total number of matches for the microblog category.
forumMentions Total number of matches for the forum category.
tastingNoteMentions Total number of matches for the tasting note category.
mediaMentions Total number of matches for the media category.
checkIns Total number of matches for the check-in category.
items Array of matches ordered by the “orderby” parameter from the request. See above.
items[].id Unique identifier for this item/event.
items[].postedTime Date/time when this item/event was published.
items[].title Title for this item/event. If you enabled highlighting, matching terms/phrases will be wrapped in <em> tags. Not all events have titles (i.e. tweets) so this property can be null.
items[].category Event category for this item/event.
items[].verb Activity Stream verb for this item/event.
items[].content The content of the item/event (i.e. the post). For larger posts, the API will return fragments of the post where your query matched terms/phrases. If you enabled highlighting, the matching terms/phrases will be wrapped in <em> tags. This may be null for some event types.
items[].actor Object representing the user that published the item/event.
items[] Unique identifier for actor for this item/event.
items[] Name/handle for the actor.
items[].actor.url URLL to actor’s page on service provider site.
items[].actor.icon URL to actor’s avatar/photo.
items[].serviceProvider The service provider represents the site where the item/event was published.
items[].serviceProvider.permalinkUrl URL to service provider site.
items[] Name of service provider.
items[].serviceProvider.type VinTank type for this service provider.
items[].serviceProvider.icon URL to icon representing this service provider.


There are several ways that the social API can be accessed from your code. Here are just a couple examples.


To load social mentions on a webpage using JavaScript (i.e. page widget), you can build a script block that calls the API and have the API automatically call your JavaScript function where you can load the results into the page.

function loadSocialWidget(socialGoo) {
<script defer type="text/javascript" src="[your query]&fmt=json&appId=[your appId]&callback=loadSocialWidget"></script>

The important parameters here are “fmt=json” and “callback=loadSocialWidget”.

Before this approach can be used, VinTank must know the domain name(s) of the web pages that will be calling the API. Contact VinTank to configure your application for this approach.


Of course, you can also call the API from your server (whether proxied from your own JavaScript or when building your page on your server). Just follow the authentication model of choice.

2 Responses to “Social Search API”

  1. [...] peeps, wanna use the API and build these or better mash-ups?  Check out the developer specs here: Posted in [...]

  2. [...] Imagine adding a widget showing all the comments from Twitter and other social networks related to a wine under each wine on a web page (think a running stream like on – we have the API for you: [...]