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.
URL: http://apiv1.cruvee.com/search/social
| 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 |
Response
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[].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. |
Examples
There are several ways that the social API can be accessed from your code. Here are just a couple examples.
JavaScript
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.
<script> function loadSocialWidget(socialGoo) { ... } </script> <script defer type="text/javascript" src="http://apiv1.cruvee.com/search/social?q=[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.
Server
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.
[...] peeps, wanna use the API and build these or better mash-ups? Check out the developer specs here: http://developer.cruvee.com/social-api/ Posted in [...]
[...] 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 VinPass.com) – we have the API for you: http://developer.cruvee.com/social-api/. [...]