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.

Comments are closed.