0
Scan Data API

Using the Tag Scan Data API


Detailed scan data for your Tags are stored by the Tag Services. You can retrieve your Tag scan data using the Tag Scan Data API.


To use the Tag Scan Data API you must first have a Microsoft Tag Scan Data API key. The Microsoft Tag Scan Data API key is associated with the Windows Live ID that was used to create your Tags. To obtain a Microsoft Tag Scan Data API key, please log in to the Tag Key Manager and request one.


In addition to connecting the Scan Data API to third-party reporting systems, you can also use it with our Tag Dashboard, an Excel add-in that displays your scan data in pre-configured charts and graphs. Learn more about the Tag Dashboard.


The Tag Scan Data API is a REST API that returns XML from a defined schema. When you make an HTTP GET request for scan data, you must specify text/xml in the Accept request header. Alternatively, when you make a HTTP GET request you may specify the query parameter format=xml. An example is as follows:


https://data.tag.microsoft.com/scans/v1/<api-key>?format=xml.


To request scan data for any of Tag's recognition technologies, use an HTTP GET request in the following format, with optional query parameters:


https://data.tag.microsoft.com/scans/v1/<api_key>?<optional query parameters>


The optional query parameters are described in the following table:

Query Parameter Continuation Token Response Header Description
none x-mstag-scans-Token Gets all scan data.
?id=startID x-mstag-scans-Token Gets all scan records with id > startID. The request is rejected if there is no scan record with the specified ID provided in the URL.
?from=fromDateTime&to=toDateTime x-mstag-scans-Token Gets all scan records in the specified date/time range. If fromDateTime > toDateTime, the most recent scan appears first (scan records are reverse-sorted).
?token=continuationToken x-mstag-scans-Token Specifies the continuation token to use to complete a scan record request.
?format=xml Gets scan records in xml format. If this query parameter is omitted, the Accept header of the GET request must be set to text/xml.

There is a limit to the number of scan records returned from a single query. If your query has more scan records than can be returned from a query, the response includes a continuation token response header (x-mstag-scans-Token) your client can use to retrieve the next batch of records. If the continuation token header is not present in the Tag Scan Data API response, it indicates that you have all the scan records available. As your scan counts increase, the time required to retrieve your scan data will also increase. If you are building your own scan performance dashboard we suggest storing scan data locally and only fetching the newer scans from the API. This can be accomplished using either the 'from' & 'to' params or the 'id' param.

Tag Scan Data Notes

  • Date/time values in the from and to query parameters must be in coordinated universal time (UTC) format (for example, 2011-08-04T04:00:05.21Z).

  • URL query parameters must specify a value (for example, the query parameter “from=&to=” is invalid).

  • In a date range query, values for the from and to parameters are required.

  • You can compare scan IDs for equality, but other comparison operators have no meaning. You cannot infer the order of scans by comparing scan IDs.

  • There can be a delay of up to 15 minutes between the time a Tag is scanned and when the scan data is available on the Tag Services.

  • First party QR Codes and NFC touchpoints will record total scan counts, but will not provide any scan Source data.

  • The Device ID field contains data gathered from scans from our Tag app as well as 3rd party QR Code scanning apps. 3rd party app data is collected using cookies on the mobile device. Because of known limitations with mobile cookies, the 3rd party app device ID counts may not be accurate. For example, if a user scans a QR Code created on the Tag platform, they receive a cookie and are counted as a unique device. If the user deletes the cookies from their mobile device, when they scan a 2nd QR Code made on the Tag platform, they will receive a new cookie with a new device ID and be counted as two separate devices. The cookie will expire one year from the date of the last scan. The device ID number generated by the cookie is masked to be unique to each Tag customer to prevent identifying a specific device's scanning activity across multiple Tag Manager accounts.

Tag Scan Data Elements

The scan data returned by the Tag Services is described by the following XML elements:

Element Description
ID Specifies the ID for a particular scan.
ClientScanTime Specifies the date/time in UTC format when a particular device scans a Tag. The date/time format is yyyy-MM-dd HH:mm:ss zzz. See Custom Date and Time Format Strings for more information.
ServiceScanTime Specifies the date and time when the Tag Services resolve a scan in UTC format. The date/time format is yyyy-MM-dd HH:mm:ss zzz, and the time zone offset (zzz) is 0. See Custom Date and Time Format Strings for more information.
TagStateAtScanTime Specifies the status of a Tag when it is scanned. Possible values are:
  • Active
  • Deleted
  • Paused
  • Expired
  • Future
TagNameAtScanTime Specifies the title of a Tag when it is scanned.
TagURLAtScanTime Specifies the URL of a Tag when it is scanned. For non-URL Tags, this field is empty.
CategoryName Specifies the category name of a Tag at report time.
Culture Specifies the culture of the client app. The culture format is:

<languageCode><country/regionCode>

where <languageCode> is the language code and <country/regionCode> is the subculture code. For example, ja-JP represents Japanese (Japan) and en-US represents English (United States).
UserAgent Specifies the user agent sent by the device when scanning a Tag.
DeviceID Specifies the device ID.
LatLong Specifies the approximate location where a Tag is scanned (Note: Precise location is not returned to enhance user privacy.) This value is blank if the user does not opt-in to share location.
Operator Specifies the mobile service provider.
Platform Specifies the device platform (for example, iPhone, Android, and so on).
PlatformVersion Specifies the device platform version number. In some cases this information might not be available, in which case the element is empty.
ApplicationId Specifies the application ID if the Tag is associated via the Microsoft Tag Scanning SDK; otherwise, the value is empty.
ApplicationSdkVersion Specifies the Microsoft Tag Scanning SDK version number, if applicable; otherwise, this value is empty.
Source Specifies the scan source. Possible values are:
  • Scan - Specifies a Tag was scanned by a device.
  • Direct - Specifies that scan data is a result of the user clicking a link that is associated with a Tag (for example, a Tag link embedded on the page of a Featured Tag).
  • Shared - Specifies the scan data is from a shared Tag. For example, a user can share a Tag to Facebook to make the Tag available to other users.
  • Featured - Specifies the scan data was selected from the Tag app Featured list.
  • History - Specifies a Tag was selected from the Tag app History.
  • QuickHistory - Specifies the scan data is from the user selecting an item from the history on the Tag app home screen.
Referrer If the value of the Source element is “Shared” or “Direct,” Referrer specifies the referring app.
TagType Specifies the type of Tag recognition technology scanned.

Tag Scan Data Examples

The following C# code sample shows how to fetch all Tag scan data and Tag scan data based on a date range.


   public string GetAllScansFromBeginning(string accessKey)
   {
      // Query all data belong to the user with the specified access token.
      string query = "https://data.tag.microsoft.com/scans/v1/" 
         + accessKey;

      // Retrieve data and return the last scan ID from result. If no scans 
      // were fetched,this function will return null.
      return DataQuery(query);
   }

   public string GetScansFromLastLeftOff(string accessKey, string lastId)
   {
      // Query by scan ID.
      string query = "https://data.tag.microsoft.com/scans/v1/" 
         + accessKey + "?id=" + lastId;

      // Retrieve data and return the last scan ID from result. If no scans
      // were fetched,this function will return null.
      return DataQuery(query);
   }

   public void GetScansByDateRange(string accessKey)
   {
      // Query by date range. The from and to parameters 
      // must contain UTC times.
      string query = "https://data.tag.microsoft.com/scans/v1/" 
         + accessKey 
         + "?from=2010-01-01T00:00:00&to=2010-12-31T23:59:59";
            
      // Retrieve data
      DataQuery(query);
   }

   private string DataQuery(string query)
   {
      // Create data http web request
      HttpWebRequest request = WebRequest.Create(query) as HttpWebRequest;
      request.Accept = "text/xml";

      // Get response
      HttpWebResponse response = request.GetResponse() as HttpWebResponse;
      WebHeaderCollection responseHeaders = response.Headers;
      if (request.HaveResponse == true && response != null)
      {
         Stream responseStream = response.GetResponseStream();

         // Process the result set
         // ProcessContent(responseStream);
      }

      // Get continuation token if the result set exceeds the batch size
      string token = GetHeaderKeyValueIfExist(responseHeaders, 
         "x-mstag-scans-Token");
      while (!string.IsNullOrEmpty(token))
      {
         query = query + "&token=" + token;

         // Get response
         response = request.GetResponse() as HttpWebResponse;
         responseHeaders = response.Headers;
         if (request.HaveResponse == true && response != null)
         {
            Stream responseStream = response.GetResponseStream();

            // Process the result set
            // ProcessContent(responseStream);
         }

         // Get continuation token if the result set exceeds the batch size
         token = GetHeaderKeyValueIfExist(responseHeaders, 
            "x-mstag-scans-Token");
      }
            
      // Retrieve and return the last scan ID in the header.  
      // The ID can be used for subsequent queries by scan ID to retrieve 
      // scans after the specified scan ID
      return GetHeaderKeyValueIfExist(responseHeaders, 
         "x-mstag-scans-LastID");
   }

   private string GetHeaderKeyValueIfExist(WebHeaderCollection responseHeaders, 
      string key)
   {
      for (int i = 0; i < responseHeaders.Count; i++)
      {
         string headerKey = this.ResponseHeaders.GetKey(i);
         if (string.Compare(key, headerKey, 
            true, CultureInfo.InvariantCulture) == 0)
         {
            return responseHeaders[key];
         }
      }
      return null;
   }

arrow

Best Practices for Using Tag

Design Tags that scan easily and offer an engaging mobile experience