VinPass API – Activities « VinTank Developer Resources & API Documentation

VinPass API – Activities

This page is related to the VinPass API.

An activity represents an action taken by an end-user in your application. The following activity types are currently supported.

Activity Types

Add Wine (to cellar)
Review/Score/Rate Wine (or write a tasting note)
Wishlist a wine
Favorite a wine
QR Code scan of wine(s) (can be from label, printed material, or digital/web)

Submitting an Activity

An activity is submitted to the VinPass API using the following entry point and method. Given the nature of the game, it is expected that you will submit activities to the API as they occur within your application.

URL: http://api.vinpass.com/v1/activities
Method: POST

Requests should be submitted using the Content-Type of “application/json” and UTF-8 encoding. To use a different encoding, specify the encoding on the end of the Content-Type request header. All responses will be in UTF-8 (and cannot be overridden).

Request Format

Your activity must be formatted in JSON using an array of the following structure. See the Examples below for sample JSON representations. Multiple activities may be submitted in multiple array elements.

Field Name	Required?	Type	Description
id	Yes	String	Immutable identifier for this activity generated by your application that must be unique across all other activities from your platform. This can be something as simple as a database ID or a hash of immutable values that you want to obfuscate from VinPass. This value is used by VinPass to match up activities that you re-submit to the API when something changes (i.e. user shares activity after it’s initially submitted). The API will also echo this ID back in the response so you can use it match back up to activities in your system (i.e. when submitting multiple activities). Maximum length is 40 characters.
type	Yes	Enum	Activity type. Wine added (“WINE_ADD”) to cellar, wine reviewed/scored (“WINE_REVIEW”), wine wishlisted (“WISHLIST”), wine favorited (“FAVORITE”), or wine QR code scanned (“QR_SCAN”).
publishDate	Yes	Datetime	Timestamp of when activity occurred represented in ISO 8601 format. Typically this is when the activity is saved/created on the partner platform.
url	No	URL	If the activity has been published to a publicly addressable page, specify the URL to that page here. Maximum length is 255 characters.
title	No	String	Title associated with the activity (if applicable). Maximum length is 200 characters.
post	No	String	Post or user-provided descriptive text for the activity. This should be used for the notes for a tasting note or review.
tags[]	No	Array	Array of tags associated with this activity. Simple and triple/machine tags are supported.
sharedOnTwitter	No	Boolean	Indicates if this activity has been shared on Twitter.
sharedOnTwitterStatusId	No	String	If shared on Twitter and the Twitter status ID is known, specify the status ID here.
sharedOnFacebook	No	Boolean	Indicates if this activity has been shared on Facebook.
sharedOnFacebookPostId	No	String	If shared on Facebook and the Facebook post ID is known, specify the post ID here.
photoTaken	No	Boolean	Indicates if a photo was taken and associated/uploaded for this activity.
photoScanMatch	No	Enum	If the photo for this activity was scanned and matched to the wine, indicate the type of match performed. Valid values are “LABEL” for a label image match and “BARCODE” for a UPC/EAN match. Leave this value blank or unspecified if no matching is performed.
photoURL	No	URL	If the photo associated with the activity is available on a publicly addressable page, specify the URL to the photo image here.
syndicateActivity	Yes	Boolean	Indicate whether this activity may be syndicated through VinTank’s Social Connect activity network. Note that all activities are processed by VinTank’s Social Connect monitoring service regardless of the value of this flag.
location.coordinates[]	No	Array	GPS coordinates of location where the activity occurred, represented as two floating-point numbers in latitude, longitude order.
location.name	No	String	Name of location (i.e. point of interest) where the activity occurred. The address can also be included, if available. Maximum length is 100 characters.
wines[]	Yes	Array	Array of one or more wines associated with this activity.
wines[].id	No	String	Unique identifier for this wine generated by your application that, if specified, must be unique across all other wines from your platform. This can be something as simple as a database ID or a hash of values that you want to obfuscate from VinPass. Maximum length is 40 characters.
wines[].type	No^*	Enum	Type of wine. Valid values are RED, WHITE, ROSE, SPARKLING_WHITE, SPARKLING_RED, PORT, DESSERT, FRUIT_BERRY, MEAD, OTHER. Although not a required field, you should include it if at all possible to maximize activity to pass matching.
wines[].ynId	No	YnId	VinTank wine YnId (if known). Note that a wine product YnId currently cannot be used.
wines[].fullName	No	String	Full wine name.
wines[].vintage	No	String	Vintage of the wine (if known). Use “NV” for non-vintage.
wines[].brandName	No	String	Winery brand name for wine (if known).
wines[].brandYnId	No	YnId	VinTank YnId for winery brand (if known).
wines[].varietalName (deprecated)	No	String	Declared varietal name (if known). Although this field is still supported, it is deprecated. Use the wines.varieties array to specify one or more grape varieties instead.
wines[].varietalYnId (deprecated)	No	YnId	VinTank YnId for the declared varietal (if known). Although this field is still supported, it is deprecated. Use the wines.varieties array to specify one or more grape varieties instead.
wines[].varieties[]	No	Array	Array of grape varieties present in this wine. For each variety the name and/or ynId, and percentage can be specified.
wines[].varieties[].ynId	No	YnId	VinTank YnId for this variety (if known).
wines[].varieties[].name	No	String	Name of grape variety (if known).
wines[].varieties[].percentage	No	Integer	Percentage of overall wine for this variety (if known).
wines[].countryName	No^*	String	Name of country of origin for the wine (if known). Be sure to include this field (or countryYnId) if you have it)
wines[].countryYnId	No^*	YnId	VinTank Region YnId for the country of origin for the wine (if known). Be sure to include this field (or countryName) if you have it.
wines[].regionName	No	String	Declared region/appellation for the wine (if known).
wines[].regionYnId	No	YnId	VinTank YnId for declared region for the wine (if known).
wines[].marketingDesignation	No	String	Portion of the wine name used for a proprietary or marketing designation (ex “The Prisoner”).
wines[].rating	No	Object	User-generated rating or score for the wine.
wines[].rating.like	No	Boolean	true if the user has “Liked” the wine, false if the user has “Disliked” the wine. If the user has not indicated a like/dislike for the wine, do not specify this property or set its value to null.
wines[].rating.score	No	String	If the user has given this wine a score, specify the score value here.
wines[].rating.range[]	No	Array	The worst & best possible score values, in that order, represented as two Strings for the user’s score. If your system uses a five star scale, the range would be ["0","5"] or ["","*****"]. For the traditional 100 point scale, use ["50","100"]. For an academic/grade scale, use ["A","F"]. And so on.
user.id	Yes	String	Unique and immutable identifier for this user within your application. This value is also used when retrieving the Scoreboard for a player. For mobile apps that support anonymous accounts, consider using the phone’s device ID (or hash of the device ID) for this value. Maximum length is 40 characters.
user.name	No	String	User’s real name, if available
user.screenName	No	String	User’s handle or screen name on the partner system. This value must be unique across all users on the partner platform. You can leave this field blank if users are not required to create accounts in your application or the user does not have an account.
user.profileImageURL	No	URL	URL to the user’s profile image (i.e. avatar)
user.profileURL	No	URL	URL to user’s profile page.

^* Although these fields are not required, including them in your activity submissions can significantly improve activity to pass matching accuracy. If you have them, include them.

Specifying wines in your request can be accomplished using a one of the following approaches.

VinTank Wine YnId – in the wines.ynId field, specify the YnId for a VinTank wine. This is the most efficient and accurate approach since the wine in the request can be directly related to a wine in VinTank but requires that you synchronize wines from VinTank to your system. You should also include the wines.name field if available.
Wine Name Components – populate the wines.type, wines.vintage, wines.brandName (or wines.brandYnId), wines.varieties, wines.countryName (or wines.countryYnId), wines.regionName (or wines.regionYnId), and/or wines.marketingDesignation. This is most appropriate for partner sites that already gather or normalize attributes of a wine in separate fields. Any combination of the component fields can be used. You should also include the wines.fullName field if available.
Full Wine Name (wines.fullName) – including only this field is the least ideal approach since the wine name must be interpreted before the VinPass rules can be applied.

Response Format

Responses will have the following format in an array where each array element matches/mirrors the activity elements from the request. Any errors encountered while processing an activity will be included the “errors” array field for that activity. This means that it is possible for a request with multiple activities that have some succeed and others fail with errors. The activity ID you include in your request will be echoed back in the response so you can use it to match back up in your system.

Field Name	Type	Description
id	String	Unique activity ID submitted for the activity in the request.
earnedPassCount	Integer	Count of the number of passes earned based on this activity.
inPlayPassCount	Integer	Count of the number of passes in-play based on this activity.
earnedPasses[]	Array	Array of zero or more passes earned as a result of this activity.
earnedPasses[].passId	String	Unique identifier for this pass.
earnedPasses[].passType	Enum	Game play type for pass: PROGRESSIVE or CHECK_LIST.
earnedPasses[].name	String	Name for this pass
earnedPasses[].howToEarn	String	Brief description of what is required to earn this pass.
earnedPasses[].description	String	Description for this pass.
earnedPasses[].rewards	String	Rewards association with this earned pass. May contain basic HTML elements such as paragraphs, bold, italics, and hyperlinks.
earnedPasses[].imageURL	URL	URL to pass image URL
earnedPasses[].sponsor.name	String	Name of the sponsor for this pass.
earnedPasses[].sponsor.description	String	Description of the sponsor for this pass.
earnedPasses[].sponsor.url	URL	URL for the sponsor.
earnedPasses[].sponsor.logoURL	URL	URL for the sponsor logo image.
inPlayPasses[]	Array	Array of zero or more passes that are in-play (i.e. started but not yet earned) as a result of this activity
inPlayPasses[].passId	String	Unique identifier for this pass.
inPlayPasses[].passType	Enum	Game play type for pass: PROGRESSIVE or CHECK_LIST.
inPlayPasses[].progressCurrent	Integer	Current count of activities counted against this pass for the user on the activity.
inPlayPasses[].progressToGo	Integer	Count of remaining activities needed to earn this pass for the user on the activity.
inPlayPasses[].name	String	Name for this pass
inPlayPasses[].howToEarn	String	Brief description of what is required to earn this pass.
inPlayPasses[].description	String	Description of this pass
inPlayPasses[].imageURL	URL	URL to pass image URL
inPlayPasses[].sponsor.name	String	Name of the sponsor for this pass.
inPlayPasses[].sponsor.description	String	Description of the sponsor for this pass.
inPlayPasses[].sponsor.url	URL	URL for the sponsor.
inPlayPasses[].sponsor.logoURL	URL	URL for the sponsor logo image.
errors[]	Array	If there were errors with this activity (such as validation errors), an array of error details will be specified here. This field and the earnedPasses and inPlayPasses fields are mutually exclusive.
errors[].code	String	Error code.
errors[].field	String	Field name that error applies to. This property will not be present for non-field (i.e. global) errors.
errors[].message	String	Error message.

A request with an activity that does not earn any passes or has no in-play passes will receive a response like:

[
  {
    "id": "xxxx",
    "earnedPassCount": 0,
    "inPlayPassCount": 0,
  }
]

The “id” field will always match the value passed in the request (i.e. it’s echo’d so you can match it back up to activities on your system as needed). Similarly, if multiple activities are submitted in a request, those activities with no earned or in-play passes will formatted the same.

Examples

The following examples show how the API may be used in a few use cases, using different approaches.

Example 1 – Wine Add With Wine Name

This example shows how a simple “wine add” activity may be submitted. The wine in this example is specified using just a wine name. The more complete the wine name and wine details included, the greater the chance that it will be matched to a pass. Therefore, this is the least ideal approach to specifying a wine.

Request:

[
  {
    "id": "activity-1235",
    "type": "WINE_ADD",
    "publishDate": "2010-11-12T12:01:00Z",
    "url": "http://yoursite.com/activities/activity-1235/",
    "sharedOnFacebook": true,
    "sharedOnFacebookPostId": "11223344556677",
    "photoTaken": true;
    "photoScanMatch": "LABEL",
    "photoURL": "http://yoursite.com/activities/activity-1235/photo.jpg",
    "syndicateActivity": true,
    "location": {
      "name": "Azzurro Pizzeria e Enoteca, 1260 Main St, Napa, CA"
    },
    "wines": [
      {
        "type": "RED",
        "fullName": "2007 Sorella Ridge Pinot Noir Anderson Valley",
      }
    ],
    "user": {
      "id": "user-4433",
      "screenName": "steviej",
      "profileURL": "http://yoursite.com/users/4433",
      "profileImageURL": "http://yoursite.com/users/4433.jpg"
    },
  }
]

Since the request only included one activity, the response array will also only have one activity response element. Also, the activity response includes the award of one pass.

Response:

[
  {
    "id": "activity-1235",
    "earnedPassCount": 1,
    "inPlayPassCount": 0,
    "earnedPasses": [
      {
        "passId": "1234-9876",
        "passType": "PROGRESSIVE",
        "name": "Sorella Ridge Ambassador",
        "howToEarn": "Collect and share 10 Sorella Ridge wines with your friends on Twitter or Facebook",
        "description": "Sorella Ridge wines offer terrific variety and outstanding value. Get to know our lineup of wines!",
        "rewards": "Show this pass at our tasting room to receive a complimentary tasting for 2",
        "imageURL" : "http://assets.vinpass.com/passes/1234-9876-earned.jpg",
        "sponsor": {
          "name": "Sorella Ridge Winery",
          "description": "A small family run winery located..."
        }
      }
    ]
  }
]

Example 2 – Wine Review With Wine Details

The following requests shows how a wine can be identified using separate wine details. This is appropriate for partner applications that already have all or part of a wine name broken up into separate fields. You will notice too that VinTank YnIds are used one of the varieties “ynId” and “regionYnId”. This assumes that you already know these ID values beforehand. For example, you’re using VinTank’s variety and region values in your system. In this case the YnId for “Cabernet Sauvignon” is “00101″. A second variety (Merlot) is specified by name. If percentage is known, it can be included too as shown but is not required.

This example also includes a user-score of 91 (for the 100 point scale) for the wine.

Request:

[
  {
    "id": "activity-1236",
    "type": "WINE_REVIEW",
    "publishDate": "2010-12-12T16:46:25Z",
    "url": "http://yoursite.com/activities/activity-1236/",
    "syndicateActivity": true,
    "wines": [
      {
        "type": "RED",
        "fullName": "Sorella Ridge Solidarity Cabernet Sauvignon 2004",
        "vintage" : "2004",
        "brandName": "Sorella Ridge",
        "varieties": [
          {
            "ynId": "00101",
            "percentage": 92
          },
          {
            "name": "Merlot",
            "percentage": 8
          }
        ],
        "regionYnId": "8400075",
        "marketingDesignation": "Solidartity",
        "url": "http://yoursite.com/wines/11111",
        "rating": 
          {
            "score": "91",
            "range": [ "50", "100" ]
          }
      }
    ],
    "user": {
      "id": "u-9898989",
      "screenName": "fcostanza"
    },
  }
]

For this activity, the user is still working on the Explorer pass so he has one “in-play” pass. The progressCurrent and progressToGo values tell us that he has met 2 out of the required 5 activities for this pass.

Response:

[
  {
    "id": "activity-1236",
    "earnedPassCount": 0,
    "inPlayPassCount": 1,
    "inPlayPasses": [
      {
        "passId": "1234-9885",
        "passType": "PROGRESSIVE",
        "progressCurrent": 2,
        "progressToGo": 3,
        "name": "Sorella Ridge Explorer",
        "howToEarn": "Taste any 5 of our wines",
        "description": "We have a big lineup of wines at Sorella Ridge and ...",
        "imageURL" : "http://assets.vinpass.com/passes/1234-9885-inplay.jpg",
        "sponsor": {
          "name": "Sorella Ridge Winery",
          "description": "A small family run winery located..."
        }
      }
    ]
  }
]

Example 3 – Multiple Wines Reviewed

The following example illustrates how multiple wines can be specified in a single activity. This time, VinTank YnIds are used to identify each wine.

Request:

[
  {
    "id": "activity-1234",
    "type": "WINE_REVIEW",
    "publishDate": "2010-11-12T12:00:00Z",
    "url": "http://yoursite.com/activities/activity-1234/",
    "title": "Thanksgiving Wines",
    "post": "Leading up to the Thankgiving holiday we sampled several wines from...",
    "tags": [ "Thanksgiving 2010", "wine", "pairings" ],
    "sharedOnTwitter": true,
    "sharedOnTwitterStatusId": "987654321",
    "syndicateActivity": true,
    "location": {
      "coordinates": [
        -122.286956,
        38.301088
      ]
    },
    "wines": [
      {
        "id": "wine-4567",
        "type": "WHITE",
        "ynId": "840007500873701200600001"
      },
      {
        "id": "wine-4568",
        "type": "RED",
        "ynId": "840002500556601200300001"
      },
      {
        "id": "wine-4569",
        "type": "DESSERT",
        "ynId": "840009100883501200810001"
      }
    ],
    "user": {
      "id": "user-778899",
      "name": "John Smith",
      "screenName": "j.smith",
      "profileURL": "http://yoursite.com/users/778899",
      "profileImageURL": "http://yoursite.com/users/778899.jpg"
    },
  }
]

For this response, the user has earned one pass and has 2 other passes in-play. Note that the in-play passes will always be sorted with the passes closest to being earned listed first.

Response:

[
  {
    "id": "activity-1234",
    "earnedPassCount": 1,
    "inPlayPassCount": 2,
    "earnedPasses": [
      {
        "passId": "2255-1111",
        "passType": "PROGRESSIVE",
        "name": "Welcome to Napa Valley",
        "howToEarn": "Taste any red or white wine from Napa Valley or any of its sub-regions",
        "description": "We're pleased to welcome you to exploring more about Napa Valley and our...",
        "imageURL" : "http://assets.vinpass.com/passes/2255-1111-earned.jpg",
        "sponsor": {
          "name": "Napa Valley Fake Consortium",
          "description": "We're a collection of wineries..."
        }
      }
    ]
    "inPlayPasses": [
      {
        "passId": "4444-1111",
        "progressCurrent": 9,
        "progressToGo": 2,
        "name": "Bank On It",
        "howToEarn": "Taste a wine from each of the regions from the left and right banks of Bordeaux",
        "description": "Bordeaux is perhaps world's most well known ...",
        "imageURL" : "http://assets.vinpass.com/passes/4444-1111-inplay.jpg",
        "sponsor": {
          "name": "Fictitious Bordeaux Society",
          "description": "Collection of Bordeaux experts..."
        }
      },
      {
        "passId": "1234-9885",
        "passType": "CHECK_LIST",
        "progressCurrent": 1,
        "progressToGo": 4,
        "name": "Sorella Ridge Explorer",
        "howToEarn": "Taste any 5 of our wines",
        "description": "We have a big lineup of wines at Sorella Ridge and ...",
        "imageURL" : "http://assets.vinpass.com/passes/1234-9885-inplay.jpg",
        "sponsor": {
          "name": "Sorella Ridge Winery",
          "description": "A small family run winery located..."
        }
      }
    ]
  }
]

Also see the Main VinPass API page, Scoreboard page, and Passes page.

2 Responses to “VinPass API – Activities”

south america luxury travel says:

June 1, 2012 at 1:04 am

Title…

Wow that was strange. I just wrote an extremely detailed response but after I clicked submit my comment didn’t show up. Sigh well I’m not writing all that again. Anyways, just wanted to say great blog…almost as cool as http://google.com!…
south america vacations says:

June 2, 2012 at 12:25 am

Title…

Wow, I’m sincerely delighted that I clicked on this site, good info here! Better than http://google.com!…