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.
|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|
|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).
|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.actor.id||Unique identifier for actor for this item/event.|
|items.actor.name||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.serviceProvider.name||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.
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.