REST API (v1)

The base URL for the REST API is http://reportingapi.realeyesit.com/api/v1/ or https://reportingapi.realeyesit.com/api/v1/ HTTPS is provided for clients who require an additional level of security.

Currently two different types of security solutions are supported by the API. These are: -Signed URLs -Token in the header

Which one to use

Both approaches have their advantages, and both should be usable in most cases.

  • Advantages of Signed URLs
    • Possibility to create pre-signed URLs with expiration
    • Simple to use from the JavaScript side
    • The signature includes the full URL with the query string parameters and the HTTP Method
  • Advantages of Token in the header
    • Security information will be in the request header- The expiring token can be used for multiple requests with different parameters

Whenever the request returns a 503 HTTP status, it means that the API is being updated and should be handled on the client side.

Signed URLs

For all requests you should use the base URL and the action name as the starting the URL. The request URL has three mandatory query string parameters, regardles of the HTTP method.

The three mandatory query string parameters are the AccessKey, the Expiration, and the Signature.

The ´AccessKey´ parameter is the public pair of the API key pairs.

The ´Expiration´ parameter is a whole number that represents the intended timestamp until which time the URL remains valid. It should be a UTC time in linux time format.

The ´Signture´ parameter is a standard HMACSHA1 hash of the whole string which contains the following string: HTTPMethod:BaseUrl/Action?<QueryStringParameters>&AccessKey=<AccessKey>&Expiration=<Expiration>

The result hash should be concatenated at the end of the URL: BaseUrl/Action?<QueryStringParameters>&AccessKey=<AccessKey>&Expiration=<Expiration>&Signature=<Signature>

For example: GET:http://reportingapi.realeyesit.com/api/v1/GetMediaList?StudyId=613&AccessKey=<AccessKey>&Expiration=<Expiration>

http://reportingapi.realeyesit.com/api/v1/GetMediaList?StudyId=613&AccessKey=<AccessKey>&Expiration=<Expiration>&Signature=<HMACSHA1HashOfThePreviousLine>

REST styled URIs are widely supported.

Including the HTTP method in the signature prevents access to the REST API with other HTTP methods.

The above mentioned signing logic shouldn’t be implemented manually for PHP and for .NET. The supllied SDK already includes it with the source code.

For both languages there are URL generator classes and REST API clients with samples.

For POST requests dont forget to provide the contentType which can be application/x-www-form-urlencoded at url encoded form and application/json at JSON.

Token in the Header

For all requests you should use the base URL and the action name as the beginning of the URL. You should also use the corresponding query string parameters or the POST data in the request body.

This technique is a fallback in case the query string parameter ´Signature´ is missing. This means that in cases where you have the signature in the query string the header information will be ignored.

If you use this technique, there are three mandatory header that should be present.

The ´AccessKey´ is the public pair of the API key pairs.

The ´Expiration´ is a whole number that represents the intended timestamp until that the URL is valid. It should be an UTC time in linux time format.

The ´Token´ is a standard HMACSHA1 hash in base64 encoded format of the the following string: <AccessKey>:<Expiration>

GetStudies

  • URI

    (Deprecated) GET /GetStudies
    GET /Studies?collectionId={collectionId}&collectionUrlHash={collectionUrlHash}&collectionExternalKey={collectionExternalKey}&from={from}&to={to}
    
  • Description

    Returns the list of studies for the account of the AccessKey.
    The result is cached on the server side for 15 seconds.
    This action only supports the GET HTTP method.
    
  • Parameters

    collectionId - identifier of the collection. (Optional)
    collectionUrlHash - URL hash of the collection. (Optional)
    collectionExternalKey - external key of the collection. (Optional)
    from - The earliest creation date of the study in ISO 8601 format. (Optional)
    to - The latest creation date of the study in ISO 8601 format. (Optional)
    
  • Result JSON Structure

    The result JSON will be an array of objects. All items will have the following fields:
      Id: The ID of the study.
      Name: The name of the study.
      Collections: List of collection identifiers.
      Created: Creation date of the study in ISO 8601 format.
      Updated: Last update date of the study in ISO 8601 format.
    
  • Result JSON Example

    [
      {
        "Id":466,
        "Name":"Volkswagen and Diamond Coffee (Live Study)",
        "Collections": [ 1, 2, 3 ],
        "Created": "2012-03-28T16:11:08.283Z",
        "Updated": "2012-03-28T16:12:08.283Z"
      },
      {
        "Id":496,
        "Name":"Bud Light - Rescue Dog (Live Study)",
        "Collections": [ 4, 5, 6 ],
        "Created": "2012-05-11T12:13:09.233Z",
        "Updated": "2012-06-28T16:12:08.283Z"
      }
    ]
    

GetMediaList

  • URI

    (Deprecated) GET /GetMediaList?studyId={studyId}
    GET /Studies/{studyId}/medias?from={from}&to={to}
    
  • Description

    Returns the list of media for the specified StudyId.
    The result is cached on the server side for 15 seconds.
    This action only supports the GET HTTP method.
    
  • Parameters

    studyId - The ID of the given study.
    from - The earliest creation date of the media in ISO 8601 format. (optional)
    to - The latest creation date of the media in ISO 8601 format. (optional)
    
  • Result JSON Structure

    The result JSON will be an array of objects. All of the items will have the following fields:
      Id: The ID of the media.
      Name: The name of the media.
      Duration: The duration of the media in milliseconds.
      MediaType: The type of the media. It can be ether 1 (image) or 2 (video).
      YouTubeHash: The YouTube UrlHash of the video if it exists.
      Study: The information about the oldest study that contains the media. (Id, Name, Collections, Creation date)
      Studies: The array of studies' information (Id, Name, Collections, Creation date) which contains this media.
      Brand: The object describe the Brand associated to the Media.        
      Tags: The updated list of tags associated with the media
      Created: Creation date of the media in ISO 8601 format
      Updated: Last update date of the media in ISO 8601 format
      
      The Brand object will have the following fields:
        Id: Identifier of the Brand
        Name: Name of the Brand
        Category: An object describes the Category.
        CategoryHierarchy: A list of category objects.
      
      The Category object will have the following fields:
       Id: Identifier the Category
       Name: Name of the Categroy
       Type: Type of category hierarchy item. It can be: Industry = 1, Category = 2, SubCategory = 3
    
  • Result JSON Example

    [
      {
        "Duration":61959,
        "Id":2500,
        "MediaType":2,
        "Name":"BP - Here's to the Home Team",
        "Study":
        {
            "Id":537,
            "Name":"Olympic Ad Test",
            "Collections": [ 1, 2, 3 ],
            "Created": "2011-10-10T13:57:59Z",
            "Updated": "2011-10-11T13:57:59Z"
        },
        "Studies":
        [
            { "Id":537, "Name":"Olympic Ad Test", "Collections": [ 1, 2, 3 ], Created": "2011-10-10T13:57:59Z", "Updated": "2011-10-11T13:57:59Z" }
        ],
        "YouTubeHash":null,
        "Brand": {
            Id: 1024,
            Name: "Coca-Cola",
            Category: {
                Id: 124,
                Name: "Soft Drinks",
                Type: 2
            },
            CategoryHierarchy: [
                { Id: 21, Name: "Drinks", Type: 1 },
                { Id: 124, Name: "Soft Drinks", Type: 2 }
            ]
        },
        "Tags": [
            "Sport",
            "Commercial"
        ],
        "Created": "2011-07-26T13:07:31.513Z",
        "Updated": "2011-10-11T13:57:59Z"
      },
      {
        "Duration":60040,
        "Id":2505,
        "MediaType":2,
        "Name":"Adidas - Take the Stage",
        "Study":
        {
            "Id":537,
            "Name":"Olympic Ad Test",
            "Collections": [ 4, 5, 6 ],
            "Created": "2011-10-10T13:57:59Z",
            "Updated": "2011-10-11T13:57:59Z"
        },
        "Studies":
        [
            { "Id":537, "Name":"Olympic Ad Test", "Collections": [ 4, 5, 6 ], Created": "2011-10-10T13:57:59Z", "Updated": "2011-10-11T13:57:59Z" }
        ],
        "YouTubeHash":"3MHhaMXrUk8",
        "Brand": {
            Id: 1024,
            Name: "Coca-Cola",
            Category: {
                Id: 124,
                Name: "Soft Drinks",
                Type: 2
            },
            CategoryHierarchy: [
                { Id: 21, Name: "Drinks", Type: 1 },
                { Id: 124, Name: "Soft Drinks", Type: 2 }
            ]
        },
        "Tags": [
            "Sport",
            "Commercial"
        ],
        "Created": "2011-07-26T13:07:31.513Z",
        "Updated": "2011-10-11T13:57:59Z"
      }
    ]
    

GetMediaListByName

  • URI

    (Deprecated) GET /GetMediaListByName?mediaName={mediaName}
    GET /Medias?mediaName={mediaName}&from={from}&to={to}
    
  • Description

    Returns the list of media for the specified search string.
    (It ignores casing and searches inside the media names)    
    The result is cached on the serves side for 15 seconds.
    This action only supports the GET HTTP method.
    
  • Parameters

    mediaName - The search string for the name.
    from - The earliest creation date of the media in ISO 8601 format. (optional)
    to - The latest creation date of the media in ISO 8601 format. (optional)
    
  • Result JSON Structure

    The result JSON will be an array of objects. All items will have the following fields:
      Id: The ID of the media.
      Name: The name of the media.
      Duration: The duration of the media in milliseconds.
      MediaType: The type of the media. It can be ether 1 (image) or 2 (video).
      YouTubeHash: The YouTube UrlHash of the video if it exists.
      Study: The information about the oldest study that contains the media. (Id, Name, Collections, Creation date)
      Studies: The array of studies' information (Id, Name, Collections, Creation date) which contains this media.
      Brand: The object describe the Brand associated to the Media.        
      Tags: The updated list of tags associated with the media
      Created: Creation date of the media in ISO 8601 format
      Updated: Last update date of the media in ISO 8601 format
      
      The Brand object will have the following fields:
        Id: Identifier of the Brand
        Name: Name of the Brand
        Category: An object describes the Category.
        CategoryHierarchy: A list of category objects.
      
      The Category object will have the following fields:
       Id: Identifier the Category
       Name: Name of the Categroy
       Type: Type of category hierarchy item. It can be: Industry = 1, Category = 2, SubCategory = 3
    
  • Result JSON Example

    [
      {
        "Duration":29950,
        "Id":2501,
        "MediaType":2,
        "Name":"BT - Synchronised Swimming",
        "Study":
        {
            "Id":537,
            "Name":"Olympic Ad Test",
            "Collections": [ 1, 2, 3 ],
            "Created": "2011-10-10T13:57:59Z",
            "Updated": "2011-10-11T13:57:59Z"
        },
        "Studies":
        [
            { "Id":537, "Name":"Olympic Ad Test", "Collections": [ 1, 2, 3 ], "Created": "2011-10-10T13:57:59Z", "Updated": "2011-10-11T13:57:59Z" }
        ],
        "YouTubeHash": null,
        "Brand": {
            Id: 1024,
            Name: "Coca-Cola",
            Category: {
                Id: 124,
                Name: "Soft Drinks",
                Type: 2
            },
            CategoryHierarchy: [
                { Id: 21, Name: "Drinks", Type: 1 },
                { Id: 124, Name: "Soft Drinks", Type: 2 }
            ]
        },
        "Tags": [
            "Sport",
            "Commercial"
        ],
        "Created": "2011-07-26T13:07:31.513Z",
        "Updated": "2011-10-11T13:57:59Z"
      },
      {
        "Duration":40480,
        "Id":2510,
        "MediaType":2,
        "Name":"BT Infinity - Hola",
        "Study:
        {
            "Id":537,
            "Name":"Olympic Ad Test",
            "Collections": [ 4, 5, 6 ],
            "Created": "2011-10-10T13:57:59Z",
            "Updated": "2011-10-11T13:57:59Z"
        },
        "Studies":
        [
            { "Id":537, "Name":"Olympic Ad Test", "Collections": [ 4, 5, 6 ], "Created": "2011-10-10T13:57:59Z", "Updated": "2011-10-11T13:57:59Z" }
        ],
        "YouTubeHash": null,
        "Brand": {
            Id: 1024,
            Name: "Coca-Cola",
            Category: {
                Id: 124,
                Name: "Soft Drinks",
                Type: 2
            },
            CategoryHierarchy: [
                { Id: 21, Name: "Drinks", Type: 1 },
                { Id: 124, Name: "Soft Drinks", Type: 2 }
            ]
        },
        "Tags": [
            "Travel",
            "Commercial"
        ],
        "Created": "2011-07-26T13:07:31.513Z",
        "Updated": "2011-10-11T13:57:59Z"
      }
    ]
    

GetMediaByYouTubeHash

  • URI

    (Deprecated) GET /GetMediaByYouTubeHash?youTubeUrlHash={youTubeUrlHash}
    GET /Medias/{youTubeUrlHash}
    
  • Description

    Returns one media for the specified Youtube video URL hash if it exists.
    The result is cached on the server side for 15 seconds.
    This action only supports the GET HTTP method.
    
  • Parameters

    youTubeUrlHash
    
  • Result JSON Structure

    The result JSON will be one Objects. The object will have the following fields:
      Id: The Id of the Media
      Name: The name of the Media
      Duration: The duration of the Media in miliseconds
      MediaType: The Type of the Media. It can be ether 1 (Image) or 2 (Video)
      YouTubeHash: The YouTube UrlHash of the Video.
      Study: The information about the oldest Study contains the media. (Id, Name, Collections, Creation date)
      Studies: The array of Studies' information (Id, Name, Collections, Creation date) which contains this media.
      Brand: The object describe the Brand associated to the Media.        
      Tags: The updated list of tags associated with the media
      Created: Creation date of the media in ISO 8601 format
      Updated: Last update date of the media in ISO 8601 format
      
      The Brand object will have the following fields:
        Id: Identifier of the Brand
        Name: Name of the Brand
        Category: An object describes the Category.
        CategoryHierarchy: A list of category objects.
      
      The Category object will have the following fields:
       Id: Identifier the Category
       Name: Name of the Categroy
       Type: Type of category hierarchy item. It can be: Industry = 1, Category = 2, SubCategory = 3
    
  • Result JSON Example

    {
      "Duration":60040,
      "Id":2505,
      "MediaType":2,
      "Name":"Adidas - Take the Stage",
      "Study":
      {
        "Id":537,
        "Name":"Olympic Ad Test",
        "Collections": [ 1, 2, 3 ],
        "Created": "2011-10-10T13:57:59Z",
        "Updated": "2011-10-12T13:57:59Z"
      },
      "Studies":
      [
        { "Id":537, "Name":"Olympic Ad Test", "Collections": [ 1, 2, 3 ], "Created": "2011-10-10T13:57:59Z", "Updated": "2011-10-12T13:57:59Z" }
      ],
      "YouTubeHash":"3MHhaMXrUk8",
      "Brand": {
            Id: 1024,
            Name: "Coca-Cola",
            Category: {
                Id: 124,
                Name: "Soft Drinks",
                Type: 2
            },
            CategoryHierarchy: [
                { Id: 21, Name: "Drinks", Type: 1 },
                { Id: 124, Name: "Soft Drinks", Type: 2 }
            ]
      },
      "Tags": [
        "Sport",
        "Commercial"
      ],
      "Created": "2011-07-26T13:07:31.513Z",
      "Updated": "2011-10-12T13:57:59Z"
    }
    

UpdateMedia

  • URI

    PUT /Medias/{mediaId}
    
  • Description

    Update the media with the given ID.
    
  • Parameters

    mediaId - The ID of the media need to be updated
    
  • Request body JSON Structure

    Name: It is optional. It can be a maximum 255 characher long string.
    Brand: It is optional. It can be a maximum 255 characher long string. The Brand will be looked up by name. In case it does not exists will be created implicitly.
    Tags: It is optional. It is an array of maximum 255 characher long strings. 
    
  • Request body JSON Example

    {
      "Name": "New Name",
      "Brand": "New Brand", 
      "Tags": ["Tag1", "Tag2"]
    }
    
  • Result JSON Structure

    The result JSON will be an Objects with the updated values. The object will have the following fields:
      Id: The Id of the Media
      Name: The updated name of the Media
      Duration: The duration of the Media in miliseconds
      MediaType: The Type of the Media. It can be ether 1 (Image) or 2 (Video)
      YouTubeHash: The YouTube UrlHash of the Video.
      Study: The information about the oldest Study contains the media. (Id, Name, Collections, Creation date)
      Studies: The array of Studies' information (Id, Name, Collections, Creation date) which contains this media.
      Brand: The object describe the Brand associated to the Media.        
      Tags: The updated list of tags associated with the media
      Created: Creation date of the media in ISO 8601 format
      Updated: Last update date of the media in ISO 8601 format
      
      The Brand object will have the following fields:
        Id: Identifier of the Brand
        Name: Name of the Brand
        Category: An object describes the Category.
        CategoryHierarchy: A list of category objects.
      
      The Category object will have the following fields:
       Id: Identifier the Category
       Name: Name of the Categroy
       Type: Type of category hierarchy item. It can be: Industry = 1, Category = 2, SubCategory = 3
    
  • Result JSON Example

    {
      "Duration":60040,
      "Id":2505,
      "MediaType":2,
      "Name":"Adidas - Take the Stage",
      "Study":
      {
        "Id":537,
        "Name":"Olympic Ad Test",
        "Collections": [ 1, 2, 3 ],
        "Created": "2011-10-10T13:57:59Z",
        "Updated": "2011-10-12T13:57:59Z"
      },
      "Studies":
      [
        { "Id":537, "Name":"Olympic Ad Test", "Collections": [ 1, 2, 3 ], "Created": "2011-10-10T13:57:59Z", "Updated": "2011-10-12T13:57:59Z" }
      ],
      "YouTubeHash": null,
      "Brand": {
            Id: 1024,
            Name: "Coca-Cola",
            Category: {
                Id: 124,
                Name: "Soft Drinks",
                Type: 2
            },
            CategoryHierarchy: [
                { Id: 21, Name: "Drinks", Type: 1 },
                { Id: 124, Name: "Soft Drinks", Type: 2 }
            ]
      },
      "Tags": [
        "Sport",
        "Commercial"
      ],
      "Created": "2011-07-26T13:07:31.513Z",
      "Updated": "2011-10-12T13:57:59Z"
    }
    

GetEmotionAllData

  • URI

    GET /GetEmotionAllData?studyId={studyId}&mediaId={mediaId}
    GET /Studies/{studyId}/Medias/{mediaId}/EmotionAll
    
  • Description

    Returns the EmotionAll report raw JSON data for a StudyId and MediaId pair.
    The result is cached on the serves side for 900 seconds.
    This action supports only GET HTTP method.
    
  • Parameters

    studyId
    mediaId
    
  • Result JSON Structure

    The result JSON will be one Objects. The object will have the following fields:
      ErrorCode: The number what identifies the Error code. If there is no Error it is 0.
      ErrorMessage: The Error message.
      SessionCount: The Session count for the selected Media.
      MediaModels: It will be an array of Objects and will contains every time just One item.
      
      The Media object will have the following fields:
        MediaName: The name of the Media.
        ErrorCode: The number what identifies the Error code. If there is no Error it is 0.
        ErrorMessage: The Error message.
        
        Attraction: The Attraction score based on the comparison with the simular Ads. (Whole number between 0 an 10)
        AttractionHistogram: A Point series (Objects with 'x' and 'y' values) for Attraction histogram plotting.
        MaxAttraction: The Attraction score of the best performing Ad.
        MinAttraction: The Attraction score of the worst performing Ad.
        
        EmotionAllScore: The overall EmotionAll score based on the comparison with the simular Ads. (Whole number between 0 an 10)
        EmotionAllScoreHistogram: A Point series (Objects with 'x' and 'y' values) for EmotionAll histogram plotting.
        
        Engagement: The Engagement score based on the comparison with the simular Ads. (Whole number between 0 an 10)
        EngagementHistogram: A Point series (Objects with 'x' and 'y' values) for Engagement histogram plotting.
        EngagementLine: A Point series (Objects with 'x' and 'y' values) for Engagement chart line plotting.
        MaxEngagement: The Engagement score of the best performing Ad.
        MinEngagement: The Engagement score of the worst performing Ad.
        MaxEngagementLineMax: The highest point of the Engagement chart line for the best performing Ad.
        MinEngagementLineMin: The lowest point of the Engagement chart line for the best performing Ad.                
        
        Impact: The Impact score based on the comparison with the simular Ads. (Whole number between 0 an 10)
        ImpactHistogram: A Point series (Objects with 'x' and 'y' values) for Impact histogram plotting.
        ImpactedHappyLine: A Point series (Objects with 'x' and 'y' values) for Happy chart line plotting.
        MaxImpact: The Impact score of the best performing Ad.
        MinImpact: The Impact score of the worst performing Ad.
        
        Retention: The Retention score based on the comparison with the simular Ads. (Whole number between 0 an 10)
        RetentionHistogram: A Point series (Objects with 'x' and 'y' values) for Retention histogram plotting.
        MaxRetention: The Retention score of the best performing Ad.
        MinRetention: The Retention score of the worst performing Ad.
        
        First7SecSurprisedLine: A Point series (Objects with 'x' and 'y' values) for plotting the first 7 second of the Media Surprise chart line.
        First7SecSurprisedMaxAttractionLine: A Point series (Objects with 'x' and 'y' values) for plotting the first 7 second of the best performing Media Surprise chart line.
        First7SecSurprisedMinAttractionLine: A Point series (Objects with 'x' and 'y' values) for plotting the first 7 second of the worst performing Media Surprise chart line.
        
        From8SecHappyLine: A Point series (Objects with 'x' and 'y' values) for plotting the Happy chart line from second 8.
        From8SecMaxRetentionMaxHappy: The highest peak for the Media with the best Retention score. (Decimal number between 0 and 1) 
        From8SecMinRetentionMinHappy: The lowest point for the Media with the worst Retention score. (Decimal number between 0 and 1)
        
        PeakEndRaw: Happy peak at the end of the Ad.
        MaxPeakEndRaw: Happy peak at the end of the Ad for the best performing Ad.
        MinPeakEndRaw: Happy peak at the end of the Ad for the worst performing Ad.
    
  • Result JSON Example

    {
      "ErrorCode":0,
      "ErrorMessage":null,
      "MediaModels":
      [
        {
          "Attraction":6,
          "AttractionHistogram":[{"x":1,"y":69},{"x":2,"y":103},{"x":3,"y":138},{"x":4,"y":172},{"x":5,"y":206},{"x":6,"y":206},{"x":7,"y":174},{"x":8,"y":135},{"x":9,"y":103},{"x":10,"y":69}],
          "EmotionAllScore":7,
          "EmotionAllScoreBetterThan":0.74545455,
          "EmotionAllScoreHistogram":[{"x":1,"y":74},{"x":2,"y":106},{"x":3,"y":133},{"x":4,"y":168},{"x":5,"y":209},{"x":6,"y":211},{"x":7,"y":165},{"x":8,"y":146},{"x":9,"y":95},{"x":10,"y":68}],
          "Engagement":7,
          "EngagementHistogram":[{"x":1,"y":69},{"x":2,"y":103},{"x":3,"y":139},{"x":4,"y":170},{"x":5,"y":207},{"x":6,"y":206},{"x":7,"y":171},{"x":8,"y":138},{"x":9,"y":104},{"x":10,"y":68}],
          "EngagementLine":[{"x":0,"y":0.261718},{"x":1,"y":0.229411},{"x":2,"y":0.286538},{"x":3,"y":0.27},{"x":4,"y":0.297619},{"x":5,"y":0.274703},{"x":6,"y":0.288934},{"x":7,"y":0.267068},{"x":8,"y":0.292828},{"x":9,"y":0.262195},{"x":10,"y":0.308163},{"x":11,"y":0.279835},{"x":12,"y":0.276371},{"x":13,"y":0.32653},{"x":14,"y":0.304081},{"x":15,"y":0.292181},{"x":16,"y":0.288617},{"x":17,"y":0.280876},{"x":18,"y":0.244855},{"x":19,"y":0.245867},{"x":20,"y":0.308943},{"x":21,"y":0.329218},{"x":22,"y":0.354771},{"x":23,"y":0.3278},{"x":24,"y":0.391666},{"x":25,"y":0.385892},{"x":26,"y":0.37605},{"x":27,"y":0.349372},{"x":28,"y":0.350427},{"x":29,"y":0.369747}],
          "ErrorCode":0,
          "ErrorMessage":null,
          "First7SecSurprisedLine":[{"x":0,"y":0.085317},{"x":1,"y":0.079681},{"x":2,"y":0.107003},{"x":3,"y":0.095528},{"x":4,"y":0.096385},{"x":5,"y":0.0625},{"x":6,"y":0.089958},{"x":7,"y":0.07551}],
          "First7SecSurprisedMaxAttractionLine":[{"x":0,"y":0.231958},{"x":1,"y":0.3},{"x":2,"y":0.28125},{"x":3,"y":0.252475},{"x":4,"y":0.179245},{"x":5,"y":0.174757},{"x":6,"y":0.145},{"x":7,"y":0.112903}],
          "First7SecSurprisedMinAttractionLine":[{"x":0,"y":0.007462},{"x":1,"y":0},{"x":2,"y":0.008064},{"x":3,"y":0},{"x":4,"y":0},{"x":5,"y":0},{"x":6,"y":0},{"x":7,"y":0}],
          "From8SecHappyLine":[{"x":8,"y":0.171314},{"x":9,"y":0.134146},{"x":10,"y":0.173469},{"x":11,"y":0.160493},{"x":12,"y":0.154008},{"x":13,"y":0.159183},{"x":14,"y":0.148979},{"x":15,"y":0.166666},{"x":16,"y":0.138211},{"x":17,"y":0.161354},{"x":18,"y":0.133744},{"x":19,"y":0.130165},{"x":20,"y":0.180894},{"x":21,"y":0.230452},{"x":22,"y":0.219917},{"x":23,"y":0.215767},{"x":24,"y":0.214583},{"x":25,"y":0.217842},{"x":26,"y":0.243697},{"x":27,"y":0.211297},{"x":28,"y":0.196581},{"x":29,"y":0.216386}],
          "From8SecMaxRetentionMaxHappy":0.623711,
          "From8SecMinRetentionMinHappy":0,
          "Impact":8,
          "ImpactHistogram":[{"x":1,"y":69},{"x":2,"y":103},{"x":3,"y":138},{"x":4,"y":171},{"x":5,"y":207},{"x":6,"y":206},{"x":7,"y":171},{"x":8,"y":138},{"x":9,"y":103},{"x":10,"y":69}],
          "ImpactedHappyLine":[{"x":24,"y":0.214583},{"x":25,"y":0.217842},{"x":26,"y":0.243697},{"x":27,"y":0.211297},{"x":28,"y":0.196581},{"x":29,"y":0.216386}],
          "MaxAttraction":10,
          "MaxEngagement":10,
          "MaxEngagementLineMax":0.771276,
          "MaxImpact":10,
          "MaxPeakEndRaw":0.588577032,
          "MaxRetention":10,
          "MediaName":"Cadburys Creme Egg - Opening",
          "MinAttraction":1,
          "MinEngagement":1,
          "MinEngagementLineMin":0.022,
          "MinImpact":1,
          "MinPeakEndRaw":0.0255555,
          "MinRetention":1,
          "PeakEndRaw":0.2300415,
          "Retention":7,
          "RetentionHistogram":[{"x":1,"y":69},{"x":2,"y":105},{"x":3,"y":136},{"x":4,"y":171},{"x":5,"y":215},{"x":6,"y":198},{"x":7,"y":173},{"x":8,"y":136},{"x":9,"y":105},{"x":10,"y":67}]
        }
      ],
      "SessionCount":306
    }
    

GetNormsData

  • URI

    GET /GetNormsData?studyId={studyId}&mediaId={mediaId}&comparisonLevel={comparisonLevel}&significanceLevel={significanceLevel}
    GET /Studies/{studyId}/Medias/{mediaId}/Norms?comparisonLevel={comparisonLevel}&significanceLevel={significanceLevel}
    
  • Description

    Returns the Norms report raw JSON data for a StudyId and MediaId pair.
    Optionally you can specify the SignificanceLevel and the ComparisonLevel.
    
    The comparison level can be:    
      LowestCommonRegion = 0,
      Global             = 1,
      Continent          = 2,
      Country            = 3,
      
    The significance level is a decimal number between 0 and 1.        
    
    The result is cached on the serves side for 900 seconds.
    This action supports only GET HTTP method.
    
  • Parameters

    studyId
    mediaId
    comparisonLevel
    significanceLevel
    
  • Result JSON Structure

    The result JSON will be one Objects. The object will have the following fields:
      StudyId: The Id of the Study
      StudyName: The name of the Study.
      MediaName: The name of the MEdia.
      MediaId: The id of the Media.
      Duration: The duration of hte Media in milliseconds.
      Countries: An array of strings. The array contains the Countries where the comparison happened for the Norms calculation.
      CompareRegions: An array of strings. The array contains the Regions where the comparison happened for the Norms calculation.
      Viewings: The session count for the selected Media.
      CompareViewings: The total session count for all of the Media which took part in the comparison.
      LastUpdateDate: The last update Date of the Media data.
      NormsLastUpdateDate: The last update Date of the Norms data.
      FromOverlap: The lower boundary for the media duration group, what is used for the comparison.
      ToOverlap: The upper boundary for the media duration group, what is used for the comparison.
      Level: The comparison level used for the comparison.
      Media: An object with the following structure
        Id: The Id of the Media.
        Duration: The Duration of the Media
        MediaUrl: The CDN Url for the Media. (It can be null. It means Media does not exists)
        ThumbnailUrl: The CDN Url for the Thumbnail
        Type: The Type of the Media. It can be ether 1 (Image) or 2 (Video)
        Thumbstrips: An array of objects.
          All object will have the same structure:
            StartTime: Time in miliseconds to that the first frame belongs from the thumbstrip.
            EndTime: Time in miliseconds to that the last frame belongs from the thumbstrip.
            FrameCount: It is a number and determines, how mach frame falls into this thumbstrip.
            Url: The CDN Url for the Thumbstrip batch
              
      Items: An array of objects. Contains the Norms comaprison result data.
      
      The Norms item object will have the following fields:
        MetricName: The name of the Metric.
        PositiveDirection: It is true if the difference between the data for the Media and the Norsm data differs in positive direction. (If greater number means the Positive direction)
        
        PercentageOfPeople: The PercentageOfPeople value for the Media and Metric chart line.
        PercentageOfPeopleNorm: The PercentageOfPeople value for the Norms. (The Average of the simular Ads)
        PercentageOfPeopleCompareResult: Determines if the difference between the PercentageOfPeople value for the Media and for the Norms significantly different or not.
        
        Min: The Min value for the Media and Metric chart line.
        MinNorm: The Min value value for the Norms. (The Average of the simular Ads)
        MinCompareResult: Determines if the difference between the Min value for the Media and for the Norms significantly different or not.
    
        Max: The Max value for the Media and Metric chart line.
        MaxNorm: The Max value value for the Norms. (The Average of the simular Ads)
        MaxCompareResult: Determines if the difference between the Max value for the Media and for the Norms significantly different or not.
        
        Avg: The Avg value for the Media and Metric chart line.
        AvgNorm: The Avg value value for the Norms. (The Average of the simular Ads)
        AvgCompareResult: Determines if the difference between the Avg value for the Media and for the Norms significantly different or not.
        
        For the compareReulsts in general:
          *Compareresult == 0 : Not Significantly Different
          *Compareresult > 0 Significantly Greater
          *Compareresult > 0 Significantly Smaller
    
  • Result JSON Example

    {
       "StudyName":"Olympic Ad Test",
       "StudyId":537,
       "MediaName":"Cadburys Creme Egg - Opening",
       "Media":{
         "Duration":30143,
         "Id":2515,
         "ThumbnailUrl":null,
         "Thumbstrips":[
         {
            "EndTime":30143,
            "FrameCount":100,
            "StartTime":0,
            "Url":"https:\/\/d1hwdebky6duei.cloudfront.net\/all\/274b1f2a-55f5-4761-9fef-254042f5e41c_thumbstrip.jpg?Expires=1412166474&Signature=orbnftG~jJLfBwFj1zMLb3bacEoTAkMa6VQFU0qgbQ3rYKo7-PVG2~1FoG-LRNw09mfL2SsYdawGSTcAcDx~Z4NUO9Ey3e-Fu~XxnlcR5yIPGTSowPXMw-c6FH34hgLVMU~PO~ztgrmKHRKm0rjJkhnJZMpnGrDmQOFQrOBHq~k_&Key-Pair-Id=APKAJBXSOGBYX6SKWDDQ"
         }
         ]
       },
       "Type":2,
       "Url":"274b1f2a-55f5-4761-9fef-254042f5e41c.mp4"
       "Countries":[
          "United Kingdom of Great Britain &amp; Northern Ireland",
          "United States of America"
       ],
       "Viewings":306,
       "LastUpdateDate":"2012-10-02T20:09:22.5",
       "MediaCount":690,
       "CompareRegions":[
          "United Kingdom of Great Britain &amp; Northern Ireland",
          "United States of America"
       ],
       "CompareViewings":128940,
       "NormsLastUpdateDate":"2014-02-19T21:16:52.5",
       "FromOverlap":0,
       "ToOverlap":65,
       "Level":3,
       "Items":[{"MetricName":"Happy","PositiveDirection":true,"PercentageOfPeople":0.596721,"PercentageOfPeopleNorm":0.483509123,"PercentageOfPeopleCompareResult":1.0,"Min":0.089843,"MinNorm":0.0458126478,"MinCompareResult":0,"Max":0.243697,"MaxNorm":0.190113962,"MaxCompareResult":0,"Avg":0.1659868,"AvgNorm":0.105914049,"AvgCompareResult":1},{"MetricName":"Confused","PositiveDirection":false,"PercentageOfPeople":0.272875,"PercentageOfPeopleNorm":0.266568452,"PercentageOfPeopleCompareResult":0.0,"Min":0.019455,"MinNorm":0.0115566887,"MinCompareResult":0,"Max":0.063265,"MaxNorm":0.07689551,"MaxCompareResult":0,"Avg":0.0393763,"AvgNorm":0.0385939255,"AvgCompareResult":0},{"MetricName":"Disgusted","PositiveDirection":false,"PercentageOfPeople":0.421311,"PercentageOfPeopleNorm":0.310132921,"PercentageOfPeopleCompareResult":1.0,"Min":0.055555,"MinNorm":0.0226160362,"MinCompareResult":1,"Max":0.119747,"MaxNorm":0.1067469,"MaxCompareResult":0,"Avg":0.0838073,"AvgNorm":0.0586202852,"AvgCompareResult":1},{"MetricName":"Sad","PositiveDirection":false,"PercentageOfPeople":0.101328,"PercentageOfPeopleNorm":0.146519348,"PercentageOfPeopleCompareResult":-1.0,"Min":0.0,"MinNorm":0.003516974,"MinCompareResult":0,"Max":0.020161,"MaxNorm":0.0517553464,"MaxCompareResult":0,"Avg":0.0083124,"AvgNorm":0.02055073,"AvgCompareResult":-1},{"MetricName":"Scared","PositiveDirection":false,"PercentageOfPeople":0.116279,"PercentageOfPeopleNorm":0.127371565,"PercentageOfPeopleCompareResult":0.0,"Min":0.0,"MinNorm":0.0004317686,"MinCompareResult":0,"Max":0.025531,"MaxNorm":0.03359993,"MaxCompareResult":0,"Avg":0.0113795,"AvgNorm":0.0103813363,"AvgCompareResult":0},{"MetricName":"Surprise","PositiveDirection":true,"PercentageOfPeople":0.438538,"PercentageOfPeopleNorm":0.4211043,"PercentageOfPeopleCompareResult":0.0,"Min":0.055084,"MinNorm":0.04078978,"MinCompareResult":0,"Max":0.107003,"MaxNorm":0.130371362,"MaxCompareResult":0,"Avg":0.07691177,"AvgNorm":0.0789415538,"AvgCompareResult":0},{"MetricName":"Engagement","PositiveDirection":true,"PercentageOfPeople":0.803278,"PercentageOfPeopleNorm":0.738293767,"PercentageOfPeopleCompareResult":1.0,"Min":0.229411,"MinNorm":0.171891883,"MinCompareResult":0,"Max":0.391666,"MaxNorm":0.343743384,"MaxCompareResult":0,"Avg":0.304075867,"AvgNorm":0.248013347,"AvgCompareResult":1},{"MetricName":"Negative","PositiveDirection":false,"PercentageOfPeople":0.588235,"PercentageOfPeopleNorm":0.5300208,"PercentageOfPeopleCompareResult":0.0,"Min":0.096078,"MinNorm":0.0662938,"MinCompareResult":0,"Max":0.179166,"MaxNorm":0.178605229,"MaxCompareResult":0,"Avg":0.1366878,"AvgNorm":0.117613755,"AvgCompareResult":0},{"MetricName":"Valence","PositiveDirection":true,"PercentageOfPeople":0.524509,"PercentageOfPeopleNorm":0.410083771,"PercentageOfPeopleCompareResult":1.0,"Min":0.058365,"MinNorm":0.0262647681,"MinCompareResult":0,"Max":0.167364,"MaxNorm":0.141544,"MaxCompareResult":0,"Avg":0.10858997,"AvgNorm":0.0731662661,"AvgCompareResult":1}]
    }
    

GetMetrics

  • URI

    GET /GetMetrics?studyId={studyId}
    GET /Studies/{studyId}/Metrics
    
  • Description

    Returns the list of Metrics for the specified ´studyId´.
    The result is cached on the serves side for 15 seconds.
    This action supports only GET HTTP method.
    
  • Parameters

    studyId
    
  • Result JSON Structure

    The result JSON will be an array of Objects. The objects will have the following fields:
      Id: The Id of the Metric.
      Name: The name of the Metric.
      UseLineAverage: It describes the way of the Aggregation table value calculation.
                      If true, than it gets a simple average over the chart line.
      IsChartLineMetric: It determines if the Metric is capable to be displayed on chart.
                         If false, this Metric can be dispalyed just in the Aggregation table.
    
  • Result JSON Example

    [
       {
          "Id":35,
          "Name":"Sessions",
          "UseLineAverage":false,
          "IsChartLineMetric":false
       },
       {
          "Id":122,
          "Name":"Happy",
          "UseLineAverage":false,
          "IsChartLineMetric":true
       }
    ]
    

GetFilters

  • URI

    GET /GetFilters?studyId={studyId}&mediaIds[]={mediaIds} 
    GET /Studies/{studyId}/Filters?mediaIds[]={mediaIds}
    
  • Description

    Returns the list of available Filters for the specified ´studyId´ and ´mediaId´ pair.
    The result is cached on the serves side for 900 seconds.
    This action supports only GET HTTP method.
    
  • Parameters

    studyId
    mediaIds
    
    The mediaIds parameter is an int array. It should be sent in URI encoded form.
    For example:
      &MediaIds[0]=2515
      &MediaIds[1]=2516
      &MediaIds[2]=2517
    
    The mediaIds parameter is optional.
    If it is not present than all of the Media from the Study will be used as default.
    
  • Result JSON Structure

    The result JSON will be an array of Objects. The objects will have the following fields:
      Id: The Id of the Filter. It is -1 for the Media Filter.
      Name: The name of the filter set. (Filter group title)
      Order: The default order of the Filter set.
      Items: An array of the possible filter options.
      
      Each item of the Items array have the following fields:
        IsDefault: Determines if it should be selected by default.
        Name: The name of the filter option.
        Value: The value of the filter option. Can be an Id or a string value.
        MediaList: The array of MediaId-s which supports the filter option.
    
  • Result JSON Example

    [
       {
          "Id":-1,
          "Name":"Media",
          "Items":[
             {
                "IsDefault":false,
                "Name":"BP - Here's to the Home Team",
                "Value":2500,
                "MediaList":[
                   2500
                ]
             },
             /* ... */
          ],
          "Order":-1
       },
       {
          "Id":1,
          "Name":"Gender",
          "Items":[
             {
                "IsDefault":false,
                "Name":"Female",
                "Value":"Female",
                "MediaList":[
                   2500,
                ]
             },
             {
                "IsDefault":false,
                "Name":"Male",
                "Value":"Male",
                "MediaList":[
                   2500
                ]
             }
          ],
          "Order":1
       },
       {
          "Id":2,
          "Name":"Age",
          "Items":[
             {
                "IsDefault":false,
                "Name":"18-24",
                "Value":"18-24",
                "MediaList":[
                    2500
                ]
             },
             {
                "IsDefault":false,
                "Name":"25-34",
                "Value":"25-34",
                "MediaList":[
                   2500
                ]
             }
          ],
          "Order":2
       }
    ]
    

GetChartData

  • URI

    GET|POST /GetChartData?<parameters>
    
  • Description

    Returns the chart data for the specified ´metricIds´, ´filters´ and component parameters.
    The result is cached on the serves side for 900 seconds.
    This action supports GET and POST HTTP method.
    It is allowed to have query string parameters and POST body as well at a request.
    It makes it possible to use a signed Url on the client side and allow sending more options in the POST body.
    The POST body can contain only more restricted filtering than the query string parameters.    
    
  • Parameters

    metricIds
    filters
    component
    
    The component is optional. Its Default value will be All.
    With this parameter is controllable which part of the full data should be retrieved.
      ChartLines = 1,
      AggregationTable = 2,
      Filtres = 4,
    The values can be combined with the sum of the diferent options. (Eg.: All := 1+2+4 = 7)
    
    The metricIds parameter is an int array. It should be sent in URI encoded form.
    For example:
      &MetricIds[0]=35
      &MetricIds[1]=129
    
    The filters parameter is an array of a complex hierarchy.
    In the querystring it should be also URI encoded.
    The structure is the following:
    [
      {
        Id : <Id of the filter in case the Type == Questin, otherwise it is not needed>
        Type : <Type of the filter. It can be: 1 (Study), 2 (Media), 3 (Question), 4 (Second), 5 (Session)>
        Values : <It is an array of strings for the filter values. In general it should contain one element>
        GroupBy : <Optional. By default false. Determines if based on the filter there should be a comparison or not.>
      }
    ]
    
    For example:
      ?MetricIds[0]=35
      &MetricIds[1]=122
      &MetricIds[2]=129
      &Filters[0].Type=Study
      &Filters[0].Values[0]=649
      &Filters[0].GroupBy=True
      &Filters[1].Type=Media
      &Filters[1].Values[0]=3369
      &Filters[1].Values[1]=3371
      &Component=All
    
    Filter sending rules:
    1) There should be just one filter for the same Type/Id pair in the request.
    2) Filters in the query string can be overridden in the POST body if the filter in the POST body is more restricted.
    3) In case of a POST request the GroupBy option should be False or omitted in the query string parameters.
    4) In case of a Study filter 
    
  • Result JSON Structure

    The result JSON will be an array of Objects. The objects will have the following fields:
      Metrics: An array of objects.
        All object will have the same structure what we get back from the GetMetrics Action:
          Id: The Id of the Metric.
          Name: The name of the Metric.
          UseLineAverage: It describes the way of the Aggregation table value calculation.
                          If true, than it gets a simple average over the chart line.
          IsChartLineMetric: It determines if the Metric is capable to be displayed on chart.
                             If false, this Metric can be dispalyed just in the Aggregation table.
      
      MediaList: An array of objects.
        All object will have the same structure what we get back from the GetMetrics Action:
          Id: The Id of the Media.
          Duration: The Duration of the Media
          MediaUrl: The CDN Url for the Media. (It can be null. It means Media does not exists)
          ThumbnailUrl: The CDN Url for the Thumbnail
          Type: The Type of the Media. It can be ether 1 (Image) or 2 (Video)
          Thumbstrips: An array of objects.
            All object will have the same structure:
              StartTime: Time in miliseconds to that the first frame belongs from the thumbstrip.
              EndTime: Time in miliseconds to that the last frame belongs from the thumbstrip.
              FrameCount: It is a number and determines, how mach frame falls into this thumbstrip.
              Url: The CDN Url for the Thumbstrip batch
          
          
      Filters: An array of objects.
        All object will have the same structure what we get back from the GetFilters Action:
          Id: The Id of the Filter. It is -1 for the Media Filter.
          Name: The name of the filter set. (Filter group title)
          Order: The default order of the Filter set.
          Items: An array of the possible filter options.
          
          Each item of the Items array have the following fields:
            IsDefault: Determines if it should be selected by default.
            Name: The name of the filter option.
            Value: The value of the filter option. Can be an Id or a string value.
            MediaList: The array of MediaId-s which supports the filter option.
       
       ChartLines: An array of objects.
         All object in the Array will have the following fields:
           Metric: The Metric object that belongs the chart line.
           Filters: The Filter object array that belongs the chart line. Refer to 'filters' parameter structure.
           AggreagtedValue: The value for the Aggregation table if the Metric is LineAverage.
           TimeLine: The point series for the chart line plotting.
           MinX: The minimum value for the X values from the TimeLine.
           MinY: The minimum value for the Y values from the TimeLine.
           MaxX: The maximum value for the X values from the TimeLine.
           MaxY: The maximum value for the Y values from the TimeLine.
                      
       AggregationTableValues: An array of objects.
         All object in the Array will have the following fields:
           Metric: The Metric object that belongs the table row.
           Filters: The Filter object array that belongs the table row. Refer to 'filters' parameter structure.
           AggreagtedValue: The value for the Aggregation table if the Metric is not LineAverage.      
    
  • Result JSON Example

    {
       "Metrics":[{"Id":35,"Name":"Sessions","UseLineAverage":false,"IsChartLineMetric":false},{"Id":122,"Name":"Happy","UseLineAverage":false,"IsChartLineMetric":true},{"Id":117,"Name":"Confused","UseLineAverage":false,"IsChartLineMetric":true},{"Id":118,"Name":"Disgusted","UseLineAverage":false,"IsChartLineMetric":true},{"Id":119,"Name":"Sad","UseLineAverage":false,"IsChartLineMetric":true},{"Id":120,"Name":"Scared","UseLineAverage":false,"IsChartLineMetric":true},{"Id":121,"Name":"Surprise","UseLineAverage":false,"IsChartLineMetric":true},{"Id":124,"Name":"Engagement","UseLineAverage":false,"IsChartLineMetric":true},{"Id":127,"Name":"Negative","UseLineAverage":false,"IsChartLineMetric":true},{"Id":128,"Name":"Valence","UseLineAverage":false,"IsChartLineMetric":true}       ],
       "MediaList":[
          {
             "Duration":30040,
             "Id":2515,
             "MediaUrl":null,
             "ThumbnailUrl":null,
             "Thumbstrips":[
             {
               "EndTime":30040,
               "FrameCount":100,
               "StartTime":0,
               "Url":"https:\/\/d1hwdebky6duei.cloudfront.net\/all\/274b1f2a-55f5-4761-9fef-254042f5e41c_thumbstrip.jpg?Expires=1412166441&Signature=sMlW4w4AjoEKFJ28Ihjrpo4waR152sJemOEPOFpbA~XX929SoOCPXaUfj3xMIUHfNiBvBPK-yYsA7inn~jX4nDAZg0Ov26q4tDUh0MM6wEUliKK-b7a6coqXgZJY8P7CZatz~ascFtRuuHZ3q2n3qoUDiFjNhZkI~rGSpwzVDko_&Key-Pair-Id=APKAJBXSOGBYX6SKWDDQ"
             }
             ],
             "Type":2
          },
          {
             "Duration":30000,
             "Id":2516,
             "MediaUrl":"https:\/\/d1hwdebky6duei.cloudfront.net\/all\/21ebdba2-4291-4cce-ae25-fb9b3164098b.mp4?Expires=1411145437&Signature=BU7ZEAxg0uC1wxMyGsJSbHqeGoorZSP7bQsmoQo5ZwzVpDKGqjM7EPJLJLDIBXEjadXc7j8swGP-y9w1euUnfaKf9lhmzpcreNC4or-6~MFua-KLd0~25mqX7UZsoBBMp0uTiQtkHQcP9e0v7XGzwQo8oP~svl-WVZFiyLt~Zkk_&Key-Pair-Id=APKAJBXSOGBYX6SKWDDQ",
             "ThumbnailUrl":"https:\/\/d1hwdebky6duei.cloudfront.net\/all\/21ebdba2-4291-4cce-ae25-fb9b3164098b.jpg?Expires=1411145437&Signature=TRu9cn3x0Go5plY6T2qt2A-wyNQIKsSkqSCiZer2mHp0mDfc5pa20~2TdW7p5IZcs8X8TgpO0go5HVqWAA4sQOadzSBMoaBjY21d2GyXLRVTu9MmGxn5xfo~-FkpHBCAM7l2~GTn865P88xGci7rENrwvhst42Mb1eX7QH7Opzs_&Key-Pair-Id=APKAJBXSOGBYX6SKWDDQ",
             "Thumbstrips":[
             {
               "EndTime":30000,
               "FrameCount":100,
               "StartTime":0,
               "Url":"https:\/\/d1hwdebky6duei.cloudfront.net\/all\/77dbe83b-a507-4a84-8738-ab7f5aa214a0_thumbstrip.jpg?Expires=1412166727&Signature=erh4-As8pXSt7u~yQ99uW9DEfVyKLBHMQMlwUgKBz9rQHZkAyUl52Wv1zI0zUXZMpyJrMhbL9cOPIGnPTziEbUNeXCcvPCXQUjyRXGmQ~NoY75U5whA8SGLmJ0VqeFZBx3vRT4f2Z17ymuEGBFw8CPa2DRBHACS1kl-KDbyM2rU_&Key-Pair-Id=APKAJBXSOGBYX6SKWDDQ"
             }
             ],
             "Type":2
          }
       ],
       "Filters":[{"Id":-1,"Name":"Media","Items":[{"IsDefault":false,"Name":"Cadburys Creme Egg - Opening","Value":2515,"MediaList":[2515]}],"Order":-1},{"Id":1,"Name":"Gender","Items":[{"IsDefault":false,"Name":"Female","Value":"Female","MediaList":[2515]},{"IsDefault":false,"Name":"Male","Value":"Male","MediaList":[2515]},{"IsDefault":false,"Name":"Unknown","Value":null,"MediaList":[2515]}],"Order":1},{"Id":2,"Name":"Age","Items":[{"IsDefault":false,"Name":"18-24","Value":"18-24","MediaList":[2515]},{"IsDefault":false,"Name":"25-34","Value":"25-34","MediaList":[2515]},{"IsDefault":false,"Name":"35-44","Value":"35-44","MediaList":[2515]},{"IsDefault":false,"Name":"45-54","Value":"45-54","MediaList":[2515]},{"IsDefault":false,"Name":"Unknown","Value":null,"MediaList":[2515]}],"Order":2},{"Id":1103,"Name":"Viewing time before skipping","Items":[{"IsDefault":false,"Name":"Viewed to end","Value":"100","MediaList":[2515]}],"Order":883}],
       "ChartLines":[
         {
           "Metric":{"Id":122,"Name":"Happy","UseLineAverage":false,"IsChartLineMetric":true},
           "Filters":[{"Type":1,"Values":["537"]},{"Type":2,"Values":["2515"]}],
           "AggregatedValue":0.1659868,
           "TimeLine":[{"x":0,"y":0.089843},{"x":1,"y":0.098039},{"x":2,"y":0.123076},{"x":3,"y":0.128},{"x":4,"y":0.130952},{"x":5,"y":0.148221},{"x":6,"y":0.159836},{"x":7,"y":0.122489},{"x":8,"y":0.171314},{"x":9,"y":0.134146},{"x":10,"y":0.173469},{"x":11,"y":0.160493},{"x":12,"y":0.154008},{"x":13,"y":0.159183},{"x":14,"y":0.148979},{"x":15,"y":0.166666},{"x":16,"y":0.138211},{"x":17,"y":0.161354},{"x":18,"y":0.133744},{"x":19,"y":0.130165},{"x":20,"y":0.180894},{"x":21,"y":0.230452},{"x":22,"y":0.219917},{"x":23,"y":0.215767},{"x":24,"y":0.214583},{"x":25,"y":0.217842},{"x":26,"y":0.243697},{"x":27,"y":0.211297},{"x":28,"y":0.196581},{"x":29,"y":0.216386}],
           "MaxX":29.0,
           "MinX":0.0,
           "MaxY":0.243697,
           "MinY":0.089843
         }
       ],
       "AggregationTableValues":[
           {
             "Metric":{"Id":35,"Name":"Sessions","UseLineAverage":false,"IsChartLineMetric":false},
             "Filters":[{"Type":1,"Values":["537"]},{"Type":2,"Values":["2515"]}],
             "AggregatedValue":306.0
           },
           {"Metric":{"Id":122,"Name":"Happy","UseLineAverage":false,"IsChartLineMetric":true},"Filters":[{"Type":1,"Values":["537"]},{"Type":2,"Values":["2515"]}],"AggregatedValue":0.596721}
         ]
       }
    }
    

GetSessionAnalysisState

  • URI

    (Deprecated) GET /GetSessionAnalysisState?sessionId={sessionId}
    GET /Sessions/{sessionId}/analysisState
    
  • Description

    Returns the information for he specified ´SessionId´ about the status of the processing.
    The return object contains a list of statuses for all of the Medias.
    For all of the source media the status can be:
      InProgress (1): It means that the Session or Processing is in progress for the Media.
      Included   (2): It means that the Session will be included in analyzis for the Media. (Good session for the Media)
      Excluded   (3): It means that the Session will be excluded from analyzis for the Media. (Failed, not Processable or Bad quality session for the Media)
    This action supports only GET HTTP method.
    
  • Parameters

    SessionId
    
  • Result JSON Structure

    The result JSON will be an Object.
      SessionId: The Id of the Session
      SessionExternalKey: The external key for the session. It can be provided from the Live Audience Measurement injection script.
      ParticipantExternalKey: The external key for the participant. It can be provided from the Live Audience Measurement injection script.
      MediaStates: The states for the Media list. It is an array of objects.
      Created: Creation date of the session in ISO 8601 format
        All object in the Array will have the following fields:
          MediaId: Id of the Media.
          MediaName: Name of the Media.
          ExternalKey: Media external key. Can be null.
          YouTubeUrlHash: The YouTube hash for the sourcemedia. Can be null.
          State: State for the media at this Session. (1 = InProgress, 2 = Included, 3 = Excluded)
          StateName: The string representation for the status. ("InProgress", "Included", "Excluded")
    
  • Result JSON Example

    {
      "MediaStates":
      [
        {
          "MediaId":6366,
          "MediaName":"Test Media 1",
          "ExternalKey": null,
          "YouTubeUrlHash": null,
          "State":1,
          "StateName":"InProgress"
        }
      ],
      "SessionId":905497,
      "SessionExternalKey": "1BEC63FC-C3EF-4A5B-A44A-FC20CAA1017D",
      "ParticipantExternalKey": "ABA64866-CF61-4A56-911C-FBB3E207AAC6"
      "SessionId":905497,
      "CampaignNames": [
            "Volkswagen and Diamond Coffee (Live Study)"
        ],
      "Created": "2013-06-14T18:56:33.0289402Z"    
    }
    

GetCollection

  • URI

    (Deprecated) GET /GetCollection?urlHash={urlHash}&externalKey={externalKey}
    GET /Collections/{keyValue}?keyType={keyType}
    
  • Description

    Returns one specific Collection that satisfies either 'urlHash' either 'externalKey' criteria or both.
    This action supports only GET HTTP method.
    
  • Parameters

    urlHash
    externalKey
    or
    keyValue
    keyType
    
    For example:
      &urlHash="dmyhsh"
      &externalKey="random-external-key"
      dmyhsh?keyType=urlHash
      random-external-key?keyType=externalkey
    
    Either of the parameter is required.
    REST style version has generic parameter 'keyValue'. Its value is treated base on 'keyType'
    parameter that can be either 'urlHash'(default) or 'externalkey'
    
  • Result JSON Structure

    The result JSON will be a collection object. The object has the following fields:
      Id: The Id of the Filter. It is -1 for the Media Filter.
      Name: The name of the filter set. (Filter group title)
      State: Collection State Id.
      StateName: Collection state name
      UrlHash: Collection's url hash
      ExternalKey: Collection's external key
      ParticiapntsSeen: Amount of people visited the collection
      Capable: Amount of people was able to run the collection
      AgreedToRecord: Amount of people accepted the flash
      Recorded: Amount of people who were recorded
      Processed: Amount of sessions that are processed by a job. Not valid sessions may be included.
      EmotionsRead: Amount of collected sessions with emotion data.
      Prompted: Amount of collection sessions that had the flash access dialog.
      MediaList: An array of included media.
      Created: Creation date of the collection in ISO 8601 format
      Updated: Last update date of the collection in ISO 8601 format
      
      Each item of the MediaList array has the following fields:
        MediaId: Determines if it should be selected by default.
        MediaName: The name of the filter option.
        ExternalKey: The value of the filter option. Can be an Id or a string value.
        IncludedSessions: .
        Duration: Length of the media in milliseconds.
    
  • Result JSON Example

       {
          "Id":478,
          "Name":"Media",
          "StateName": "Live",
          "State": 4,
          "UrlHash": "dmyhsh",
          "ExternalKey": null,
          "ParticiapntsSeen": 80,
          "Capable":75,
          "AgreedToRecord":60,
          "Recorded":58,
          "Processed":58,
          "EmotionsRead": 55,
          "Prompted":75,
          "Created": "2012-11-22T09:21:32.6355309Z",
          "Updated": "2012-11-23T09:21:32.6355309Z",
    
          "MediaList": [
             {
                "MediaId":1,
                "MediaName":"BP - Here's to the Home Team",
                "ExternalKey":null,
                "IncludedSessions": 350,
                "Duration": 30799
             },
             {
                "MediaId":2,
                "MediaName":"Tom Tom",
                "ExternalKey":null,
                "IncludedSessions": 350,
                "Duration": 7000
             },
          ],
       }
    

GetCollections

  • URI

    (Deprecated) GET /GetCollections?state={state}
    GET /Collections?state={state}&from={from}&to={to}
    
  • Description

    Returns an array of Collection that satisfy the optional criterias.
    This action supports only GET HTTP method.
    
  • Parameters

    state - State ID value of the collection (optional)
    from - The earliest creation date of the collection in ISO 8601 format. (optional)
    to - The latest creation date of the collection in ISO 8601 format. (optional)
    
  • Result JSON Structure

    The result JSON will be an array collection objects. The object has the following fields:
      Id: The Id of the Filter. It is -1 for the Media Filter.
      Name: The name of the filter set. (Filter group title)
      State: Collection State Id.
      StateName: Collection state name
      UrlHash: Collection's url hash
      ExternalKey: Collection's external key
      ParticipantsSeen: Amount of people visited the collection
      Capable: Amount of people was able to run the collection
      AgreedToRecord: Amount of people accepted the flash
      Recorded: Amount of people who were recorded
      Processed: Amount of sessions that are processed by a job. Not valid sessions may be included.
      EmotionsRead: Amount of collected sessions with emotion data.
      Prompted: Amount of collection sessions that had the flash access dialog.
      MediaList: An array of included media.
      Created: Creation date of the collection in ISO 8601 format
      Updated: Last update date of the collection in ISO 8601 format
      
      Each item of the MediaList array has the following fields:
        MediaId: Determines if it should be selected by default.
        MediaName: The name of the filter option.
        ExternalKey: The value of the filter option. Can be an Id or a string value.
        IncludedSessions: Valuable sessions.
        Duration: Length of the media in milliseconds.
    
  • Result JSON Example

        [
            {
                "Id":478,
                "Name":"Test",
                "StateName": "Live",
                "State": 4,
                "UrlHash": "dmyhsh",
                "ExternalKey": null,
                "ParticiapntsSeen": 80,
                "Capable":75,
                "AgreedToRecord":60,
                "Recorded":58,
                "Processed":58,
                "EmotionsRead": 55,
                "Prompted":75,
                "Created": "2011-07-20T00:40:45.493Z",
                "Updated": "2011-07-22T00:40:45.493Z",
    
                "MediaList": [
                    {
                       "MediaId":1,
                       "MediaName":"BP - Here's to the Home Team",
                       "ExternalKey":null,
                       "IncludedSessions": 55,
                       "Duration": 30799
                    },
                    {
                       "MediaId":2,
                       "MediaName":"Tom Tom",
                       "ExternalKey":null,
                       "IncludedSessions": 350,
                       "Duration": 7000
                    },
                ],
           },
           {
                "Id":381,
                "Name":"Test2",
                "StateName": "Live",
                "State": 4,
                "UrlHash": "dmyhsh2",
                "ExternalKey": null,
                "ParticiapntsSeen": 0,
                "Capable":0,
                "AgreedToRecord":0,
                "Recorded":0,
                "Processed":0,
                "EmotionsRead": 0,
                "Prompted":0,
                "Created": "2012-11-22T09:21:32.6355309Z",
                "Updated": "2011-07-22T00:40:45.493Z",
                "MediaList": [],
           }
       ]
    

UpdateCollection

  • URI

    (Deprecated) POST /UpdateCollection?urlHash={urlHash}&externalKey={externalKey}
    POST /UpdateCollection  
    PUT /Collections
    
  • Description

    It makes possible to update a collection identified by the ´UrlHash´.
    The ´Name´ of the collection (in synchron with the Study name) and the ´State´ can be updated.
    The ´UrlHash´ is mandatory in the request body. This identifies the Collection.
    The ´Name´ and ´State´ fields are optional in the request body.
    If the optional fields does not present, no update will be performed on the corresponding attribute.
    The ´State´ field can have the following values:
      Value Name
      1   = New
      3   = Completed
      4   = Live
      
    The following state transitions are allowed:
      1 -> 4 (From New to Live)
      4 -> 3 (From Live to Completed)
      
    This action supports only POST HTTP method.
    
  • Parameters

    There are no extra parameters in the query string.
    It is important to note, that the URL should be signed!
    It means that the three mantatory query string parameter should be present!
    (´AccessKey´, ´Expiration´, ´Signature´)
    
  • Request body JSON Structure

    UrlHash: It is mandatory. It is the identifier for the Collection.
    Name: It is optional. It can be a maximum 255 characher long string.
    State: It is optional. It can be one of the above mentioned State.
    
  • Request body JSON Example

    {
      "UrlHash": "KexBop",
      "Name": "New Name",
      "State": null
    }
    
  • Result JSON Structure

    The result JSON will be an Object.
      IsSuccessful: Determines if the update was successfull or not.
      ErrorMessage: It contains the error message if the update was unsuccessful.
    
  • Result JSON Example

    {
      "IsSuccessful": true
      "ErrorMessage": null
    }
    

GetSession

  • URI

    (Deprecated) GET /GetSession?sessionId={sessionId}?includeSurveyData={includeSurveyData}
    GET /Sessions/{sessionId}?includeSurveyData={includeSurveyData}
    
  • Description

    Returns one specific Session that satisfies the SessionId criteria
    This action supports only GET HTTP method.
    
  • Parameters

    SessionId
    
    For example:
      &sessionId=15658814
    
    SessionId is required parameter
    
    includeSurveyData - optional parameter (default 'false')
    
  • Result JSON Structure

    The result JSON will be a session object. The object has the following fields:
      Id: The Id of the Session.
      IsReviewer: Shows if the participant is a reviewer or a 
      CollectionUrlHash: The collection's hash which belongs to the session
      IsSessionExcluded: Shows if the session excluded.
      Created: Creation date of the session in ISO 8601 format
      SurveyData: List of question answer objects (Optional).
      
    Each item of the SurveyData array has the following fields:
        Question:  Textual representation of a question.
        Answer: Textual representation of an answer.
      
      MediaStates: List of session analyzis state
      
      Look at MediaStates under the Included or Excluded Analysis state
      
    
  • Result JSON Example

       {
            "Id": 906018,
            "CollectionUrlHash": "KAJBIL",
            "IsReviewer": false,
            "IsSessionExcluded": true,
            "Created": "2013-06-14T18:56:33.0289402Z",
            "SurveyData": [
                 {
                   "AnswerId": 2,
                   "AnswerText": "Mann",
                   "DefaultAnswerText": "Male",
                   "DefaultQuestionText": "Gender",
                   "Id": 94582,
                   "QuestionId": 2,
                   "QuestionText": "Mann/Frau"
                 }
            ],
            "MediaStates": [
                {
                    "SessionId": 906018,
                    "SessionExternalKey": "1BEC63FC-C3EF-4A5B-A44A-FC20CAA1017D",
                    "ParticipantExternalKey": "ABA64866-CF61-4A56-911C-FBB3E207AAC6",
                    "CampaignNames": [
                        "Volkswagen and Diamond Coffee (Live Study)"
                    ],                    
                    "IsReviewer": false,
                    "MediaStates": [
                        {
                            "MediaId": 6415,
                            "MediaName": "149-mani-mantra-736343-calligraphy-tattoo-design-art-flash-pictures--tattoo-design-1920x1200",
                            "ExternalKey": null,
                            "YouTubeUrlHash": null,
                            "State": 3,
                            "StateName": "Excluded"
                        },
                        {
                            "MediaId": 6416,
                            "MediaName": "Art-amazing-wallpaper-of-high-resolution-1920-1200",
                            "ExternalKey": null,
                            "YouTubeUrlHash": null,
                            "State": 3,
                            "StateName": "Excluded"
                        },
                        {
                            "MediaId": 6417,
                            "MediaName": "art-colourful-1920-1200",
                            "ExternalKey": null,
                            "YouTubeUrlHash": null,
                            "State": 3,
                            "StateName": "Excluded"
                        },
                        {
                            "MediaId": 6418,
                            "MediaName": "borubodour",
                            "ExternalKey": null,
                            "YouTubeUrlHash": null,
                            "State": 3,
                            "StateName": "Excluded"
                        },
                        {
                            "MediaId": 6419,
                            "MediaName": "MadC Claudia Walde 3-2000-1333",
                            "ExternalKey": null,
                            "YouTubeUrlHash": null,
                            "State": 3,
                            "StateName": "Excluded"
                        },
                        {
                            "MediaId": 6420,
                            "MediaName": "woman-creative-design-wallpaper-1920x1200",
                            "ExternalKey": null,
                            "YouTubeUrlHash": null,
                            "State": 3,
                            "StateName": "Excluded"
                        }
                    ]
                }
            ]
        }
    

GetSessions

  • URI

    (Deprecated) GET /GetSessions?urlHash={urlHash}&externalKey={externalKey}&sessionExternalKey={sessionExternalKey}&participantExternalKey={participantExternalKey}&externalKey={externalKey}&mediaId={mediaId}&mediaExternalKey={mediaExternalKey}&youTubeUrlHash={youTubeUrlHash}&campaignName={campaignName}&afterSessionId={afterSessionId}
    GET /Sessions/analysisState?urlHash={urlHash}&externalKey={externalKey}&sessionExternalKey={sessionExternalKey}&participantExternalKey={participantExternalKey}&externalKey={externalKey}&mediaId={mediaId}&mediaExternalKey={mediaExternalKey}&youTubeUrlHash={youTubeUrlHash}&campaignName={campaignName}&from={from}&to={to}&afterSessionId={afterSessionId}
    
  • Description

    Returns an array of Sessions that satisfy either the collection ´UrlHash´ or the collection ´ExternalKey´ criteria.
    One of the two parameter is mandatory!
    The size of result is limited to 2500 sessions! To get the next batch ´afterSessionId´ criteria should be set to the last SessionId from the previous result.
    
    Optional filter parameters are the ´SessionExternalKey´ and the ´ParticipantExternalKey´.
    This two filter works on fields what can be set on the Live Audience Measurement client side.
    If the provided ExternalKey-s are not unique, the method can return multiple result objects!
    This action supports only GET HTTP method.
    
  • Parameters

    urlHash
    externalKey
    sessionExternalKey
    participantExternalKey
    mediaId
    mediaExternalKey
    campaignName
    youTubeUrlHash
    from
    to
    afterSessionId
    
    For example:
      &urlHash="dmyhsh"
      &externalKey="random-external-key"
      &sessionExternalKey="1BEC63FC-C3EF-4A5B-A44A-FC20CAA1017D"
      &participantExternalKey="ABA64866-CF61-4A56-911C-FBB3E207AAC6"
    
    UrlHash parameter is optional.
    ExternalKey parameter is optional. 
    Note one of the parameters must be present!
    
    MediaId parameter is optional. 
    MediaExternalKey parameter is optional. 
    CampaignName parameter is optional. 
    YouTubeUrlHash parameter is optional. 
    
    SessionExternalKey parameter is optional.
    ParticipantExternalKey parameter is optional.
    
    From parameter is optional.
    To parameter is optional.
    
    AfterSessionId is optional.
    
  • Result JSON Structure

    The result JSON will be an array session objects. The object has the following fields:
      SessionId: The Id of the Session. It is -1 for the Media Filter.
      SessionExternalKey: The external key for the session. It can be provided from the Live Audience Measurement injection script.
      ParticipantExternalKey: The external key for the participant. It can be provided from the Live Audience Measurement injection script.
      CampaignNames: It is used in DC 2.0 Live Audience measurement as CampaignName. A list of campaigns     
      IsReviewer: Shows if the participant is a reviewer
      MediaStates: List of session analyzis state
      Created: Creation date of the session in ISO 8601 format
      
      The sessions' states can be seen under MediaStates, and will say if a session is 1 (InProgress), 2 (Included), or 3 (Excluded)  
    
  • Result JSON Example

        [
            {
                "CampaignNames": [
                        "Volkswagen and Diamond Coffee (Live Study)"
                ],
                "SessionId": 332135,
                "SessionExternalKey": null,
                "ParticipantExternalKey": "cf049d84-728c-4158-b1a4-211aa3c5a255",
                "SessionExternalKey": "1BEC63FC-C3EF-4A5B-A44A-FC20CAA1017D",
                "ParticipantExternalKey": "ABA64866-CF61-4A56-911C-FBB3E207AAC6",
                "IsReviewer": false,
                "Created": "2013-06-14T18:56:33.0289402Z",
                "MediaStates": [
                    {
                        "MediaId": 420,
                        "MediaName": null,
                        "ExternalKey": null,
                        "YouTubeUrlHash": null,
                        "State": 1,
                        "StateName": "InProgress"
                    }
                ]
            },
            {
                "CampaignNames": [
                        "Volkswagen and Diamond Coffee (Live Study)"
                ],
                "SessionId": 332136,
                "SessionExternalKey": null,
                "ParticipantExternalKey": "cf049d84-728c-4158-b1a4-211aa3c5a255",
                "IsReviewer": true,
                "Created": "2013-06-14T20:48:26.6459042Z",
                "MediaStates": [
                    {
                        "MediaId": 420,
                        "MediaName": null,
                        "ExternalKey": null,
                        "YouTubeUrlHash": null,
                        "State": 3,
                        "StateName": "Excluded"
                    }
                ]
            },
            {
                "CampaignNames": [
                        "Volkswagen and Diamond Coffee (Live Study)"
                ],
                "SessionId": 332137,
                "SessionExternalKey": null,
                "ParticipantExternalKey": "cf049d84-728c-4158-b1a4-211aa3c5a255",
                "IsReviewer": false,
                "Created": "2013-06-14T21:27:24.4807211Z",
                "MediaStates": [
                    {
                        "MediaId": 420,
                        "MediaName": null,
                        "ExternalKey": null,
                        "YouTubeUrlHash": null,
                        "State": 2,
                        "StateName": "Included"
                    }
                ]
            },
            {
                "CampaignNames": [
                        "Volkswagen and Diamond Coffee (Live Study)"
                ],
                "SessionId": 332138,
                "SessionExternalKey": null,
                "ParticipantExternalKey": "cf049d84-728c-4158-b1a4-211aa3c5a255",
                "IsReviewer": false,
                "Created": "2013-06-15T15:56:36.4076766Z",
                "MediaStates": [
                    {
                        "MediaId": 420,
                        "MediaName": null,
                        "ExternalKey": null,
                        "YouTubeUrlHash": null,
                        "State": 2,
                        "StateName": "Included"
                    }
                ]
            }
        ]
    

UpdateSession

  • URI

    (Deprecated) POST /UpdateSession?sessionId={sessionId}
    PUT /Sessions/{sessionId}
    
  • Description

    It makes possible to inlcude or exclude a session identified by the ´SessionId´.
    If the optional fields does not present, no update will be performed on the corresponding attribute.
    The ´IsExcluded´ field can have the following values:
      true
      false
    
      
    This action supports only POST/PUT HTTP method.
    
  • Parameters

    sessionId
    It is important to note, that the URL should be signed!
    It means that the three mantatory query string parameter should be present!
    (´AccessKey´, ´Expiration´, ´Signature´)
    
  • Request body JSON Structure

    SessionId: It is optional when sessionId is present in uri. It is the identifier for the Session.
    IsExcluded: It is mandatory. Is true if it is excluded and false if it included.
    
  • Request body JSON Example

    {
      "SessionId": 958111,
      "IsExcluded": true
    }
    
  • Result JSON Structure

    The result JSON will be an Object.
      IsSuccessful: Determines if the update was successfull or not.
      ErrorMessage: It contains the error message if the update was unsuccessful.
    
  • Result JSON Example

    {
      "IsSuccessful": true
      "ErrorMessage": null
    }
    

GetSessionSurveyData

  • URI

    GET /Sessions/{sessionId}/surveyData
    
  • Description

    Returns survey data (question answers) for the specified session id.
    This action supports only GET HTTP method.
    
  • Parameters

    sessionId - session's identifier.   
    
  • Result JSON Structure

    The result JSON will be an Array of Objects. All of the Items will have the following fields:
      Id: our internal record id.
      QuestionId: The Id of the Question being answered
      QuestionText: Text representation of the original Question
      DefaultQuestionText: Default text representation of the Question
      AnswerId: The Id of the Answer being given
      AnswerText: Text representation of the original Answer
      DefaultAnswerText: efault text representation of the Answer
    
  • Result JSON Example

    [
         {
          "AnswerId": 1,
          "AnswerText": "20",
          "DefaultAnswerText": "18-24",
          "DefaultQuestionText": "Age group",
          "Id": 94589,
          "QuestionId": 1,
          "QuestionText": "How old are you?"
        },
        {
          "AnswerId": 2,
          "AnswerText": "Mann",
          "DefaultAnswerText": "Male",
          "DefaultQuestionText": "Gender",
          "Id": 94582,
          "QuestionId": 2,
          "QuestionText": "Mann/Frau"
        }
    ]
    

SaveSessionSurveyData

  • URI

    POST /Sessions/{sessionId}/surveyData?overwrite={overwrite}
    
  • Description

    Saves survey data (question answers) for the specified session id. Optionally overwrites.
    This action supports only POST HTTP method.
    
  • Parameters

    sessionId - session's identifier.
    overwrite - delete existant data before insert. Optional (default 'false')
    
  • Request body JSON Structure

    Array of JSON object of the following structure.
    QuestionId: The Id of the Question being answered
    QuestionText: Text representation of the original Question
    DefaultQuestionText: Text representation of the original Question (Can be used only alone or in combination with the QuestionText)
    IsHidden: The question be visible between charting filters or not. Optional, if not specified, no change is made to the visibility.
    AnswerId: The Id of the Answer being given
    AnswerText: Text representation of the original Answer
    DefaultAnswerText: Text representation of the original Answer (Can be used only alone or in combination with the AnswerText)
    TestElements: Array of JSON objects with the following structure:
      MediaKey: The external key of the media, what is specified in the Collection Integration API configuration
      TestElementKey: The external key of the test element, what is specified in the Collection Integration API configuration
    
    Either QuestionId or QuestionText or DefaultQuestionText and either AnswerId or AnswerText or DefaultAnswerText should be set.
    Also both Id and Text can be set.
    Also both DefaultText and Text can be set.
    In Id filed will be primary while original text values will be also saved.
    Both pair Id and Text or DefaultText and Text serves the goal to make it possible to identify the same Logical Question and next to it save an other text representation. (Other language, other formalization of the same question)
    The advantage of using Id-s is, that it uniquely identifies the Question and it does not create on the fly a new one if it does not exists.
    The advantage of using DefaultText-s is, that with it a question can be identified without knowing the internal Id. This behaves like an external key. In case of the usage of the DefaultTexts it creates a question if it is missing.
    If there is only AnswerText in the request, the system will handle it as a DefaultAnswerText, meening it will try to identify it as a DefaultAnswerText, and if it can't than a new answer will be created with the AnswerText as DefaultAnswerText.
    If there is only QuestionText in the request, the system will handle it as a DefaultQuestionText, meening it will try to identify it as a DefaultQuestionText, and if it can't than a new question will be created with the QuestionText as DefaultQuestionText.
    The AnswerText, DefaultAnswerText and QuestionText, DefaultQuestionText can be maximum 255 character long.
    
    If there are more than 100 answer for a question, it gets marked as free text question, and the answers get merged together.
    
    In our system there are two system level Question, what can be used (and suggested to use, to leverrage the standard system wide Age/Gender segmentation), but they can not be changed.
    It means:
      Using the DefaultQuestionText "What is your age?" and the DefaultAnswerText "Female" or "Male" will use the system wide variable.
        Important, that only the two specified answer is supported.
      Using the DefaultQuestionText "What is your gender?" and the DefaultAnswerText "1", "2", "3", ... , "200" will use the system wide variable.
        Important, that only the 200 specified answer is supported. (Numbers from 1 to 200) Additional text representation can be saved in the QuestionText and AnswerText fields.
    Additional text representation can be saved in the QuestionText and AnswerText fields.
    
  • Request body JSON Example

    [
    {
      "AnswerId": 1,
      "AnswerText": "20",
      "QuestionId": 1,
      "QuestionText": "How old are you?",
      "TestElements": [ { "MediaKey": "14526" } ]
    },
    {
      "AnswerId": 2,
      "AnswerText": "Mann",
      "QuestionId": 2,
      "IsHidden": true,
      "QuestionText": "Mann/Frau",
      "TestElements": [ { "TestElementKey": "Element01" } ]
    }
    ]
    
  • Result JSON Structure

    The result will be 200 OK code. Response body will contain information about failed inserts.
    In this case it will be an object with 'FailedItems' array of objects with the folowing fileds.
      Item: original posted item.
      ReasonId: Failure reason identifier
      ReasonText: Failure reason message
    The list of failure reasons contains following Ids:
    1 - posted item does not have arbitary fields set up (e.g. both Id and Text of Answer/Question are missing)
    2 - no question found for the specified QuestionText
    3 - no question found for the specified QuestionId
    4 - no answer found for the specified AnswerText
    5 - multiply answers found the for specified AnswerText
    6 - no answer found for the specified AnswerId
    
  • Result JSON Example

      {
        "FailedItems": [
          {
            "Item": {
              "AnswerText": "20",
              "QuestionText": "How old are you?"
            },
            "ReasonId": 2,
            "ReasonText": "No question with such text in our records"
          }
        ]
      }
    

DeleteSessionSurveyData

  • URI

    DELETE /Sessions/{sessionId}/surveyData
    
  • Description

    Deletes survey data (question answers) for the specified session id.
    This action supports only DELETE HTTP method.
    
  • Parameters

    sessionId - session's identifier.
    
  • Result

    The result will be 204 No Content code.
    

GetQuestions

  • URI

    GET /Questions?includeAnswers={includeAnswers}
    
  • Description

    Gets list of all questions owned by the account and system questions(immutable)
    This action supports only GET HTTP method.
    
  • Parameters

    includeAnswers - wheather to include answer options in the reponse. Optional (default 'false')
    
  • Result

    Array of JSON object of the following structure.
    Id: The Id of the Question
    QuestionTexts: Array of text representations of the Question
    DefaultQuestionText: Default text representation of the Question
    Answers: Array of Answer objects(Optional)
    MissingAnswerText: Text value that will be used when session doesn't have answer for that Question
    IsSystem: Denotes that the Question is system/global question (e.g. used for norms)
    
  • Result JSON Example

      [
        {
          "DefaultQuestionText": "Age group",
          "Id": 1,
          "IsSystem": true,
          "MissingAnswerText": "Unknown",
          "QuestionTexts": [
            "What is your age",
            "How old are you"
          ],
          "Answers": [
            {
              "AnswerTexts": [
                "18","20","21","22","23","24"
              ],
              "DefaultAnswerText": "18-24",
              "Id": 1,
              "IsSystem": true
            }
          ]
        }
      ]
    

GetQuestion

  • URI

    GET /Questions/{id}?includeAnswers={includeAnswers}
    
  • Description

    Gets the question by Id.
    This action supports only GET HTTP method.
    
  • Parameters

    id - identifier of the question
    includeAnswers - wheather to include answer options in the reponse. Optional (default 'false')
    
  • Result

    JSON object of the following structure.
    Id: The Id of the Question
    QuestionTexts: Array of text representations of the Question
    DefaultQuestionText: Default text representation of the Question
    Answers: Array of Answer objects(Optional)
    MissingAnswerText: Text value that will be used when session doesn't have answer for that Question
    IsSystem: Denotes that the Question is system/global question (e.g. used for norms)
    
  • Result JSON Example

        {
          "DefaultQuestionText": "Age group",
          "Id": 1,
          "IsSystem": true,
          "MissingAnswerText": "Unknown",
          "QuestionTexts": [
            "What is your age",
            "How old are you"
          ],
          "Answers": [
            {
              "AnswerTexts": [
                "18","20","21","22","23","24"
              ],
              "DefaultAnswerText": "18-24",
              "Id": 1,
              "IsSystem": true
            }
          ]
        }
    

PostQuestion

  • URI

    POST /Questions
    
  • Description

    Creates the question.
    This action supports only POST HTTP method.
    
  • Parameters

    -
    
  • Request body JSON Structure

    JSON object with the following structure.
    QuestionTexts: Array of text representations of the Question
    DefaultQuestionText: Default text representation of the Question
    Answers: Array of Answer objects(Optional)
    MissingAnswerText: Text value that will be used when session doesn't have answer for that Question
    
    All item of the QuestionTexts, the DefaultQuestionText can be maximum 400 character long.
    The MissingAnswerText can be maximum 40 character long.
    
  • Request body JSON Example

    {
          "DefaultQuestionText": "Age group",
          "MissingAnswerText": "Unknown",
          "QuestionTexts": [
            "What is your age",
            "How old are you"
          ],
          "Answers": [
            {
              "AnswerTexts": [
                "18","20","21","22","23","24"
              ],
              "DefaultAnswerText": "18-24",
              "Id": 1,
              "IsSystem": true
            }
          ]
    }
    
  • Result

    The result will be 201 Created code. Body will contain JSON object of the following structure.
    Id: The Id of the created Question
    QuestionTexts: Array of text representations of the Question
    DefaultQuestionText: Default text representation of the Question
    Answers: Array of Answer objects(Optional)
    MissingAnswerText: Text value that will be used when session doesn't have answer for that Question
    IsSystem: Denotes that the Question is system/global question (e.g. used for norms)
    
  • Result JSON Example

        {
          "DefaultQuestionText": "Age group",
          "Id": 1,
          "IsSystem": false,
          "MissingAnswerText": "Unknown",
          "QuestionTexts": [
            "What is your age",
            "How old are you"
          ],
          "Answers": [
            {
              "AnswerTexts": [
                "18","20","21","22","23","24"
              ],
              "DefaultAnswerText": "18-24",
              "Id": 1,
              "IsSystem": true
            }
          ]
        }
    

UpdateQuestion

  • URI

    PUT /Questions/{id}
    
  • Description

    Updates the question.
    This action supports only PUT HTTP method.
    
  • Parameters

    id - identifier of the question to be updated
    
  • Request body JSON Structure

    JSON object with the following structure.
    QuestionTexts: Array of text representations of the Question
    DefaultQuestionText: Default text representation of the Question
    MissingAnswerText: Text value that will be used when session doesn't have answer for that Question
    
    The QuestionTexts and DefaultQuestionText are optional.
    If they are not present in the posted data or they are there with Null value, they will be not updated.
    All item of the QuestionTexts and the DefaultQuestionText can be maximum 400 character long.
    
  • Request body JSON Example

    {
          "DefaultQuestionText": "Age group",
          "MissingAnswerText": "Unknown",
          "QuestionTexts": [
            "What is your age",
            "How old are you"
          ]
    }
    
  • Result

    The result will be 204 No Content code.
    

DeleteQuestion

  • URI

    DELETE /Questions/{id}
    
  • Description

    DELETES the question with its answers
    This action supports only DELETE HTTP method.
    
  • Parameters

    id - identifier of the question to be deleted
    
  • Result

    The result will be 204 No Content code.
    

GetQuestionAnswers

  • URI

    GET /Questions/{id}/answers
    
  • Description

    Gets list of all answers owned by the account for the specified question
    This action supports only GET HTTP method.
    
  • Parameters

    id - identifier of the question
    
  • Result

    Array of JSON object of the following structure.
    Id: The Id of the Answer
    AnswerTexts: Array of text representations of the Answer
    DefaultAnswerText: Default text representation of the Answer
    IsSystem: Denotes that the Question is system/global question (e.g. used for norms)
    
  • Result JSON Example

      [
        {
          "AnswerTexts": [
            "Male",
            "Mann"
          ],
          "DefaultAnswerText": "Male",
          "Id": 1,
          "IsSystem": true
        },
        {
          "AnswerTexts": [
            "Female",
            "Frau"
          ],
          "DefaultAnswerText": "Female",
          "Id": 2,
          "IsSystem": true
        }
      ]
    

DeleteQuestionAnswers

  • URI

    DELETE /Questions/{id}/answers
    
  • Description

    Deletes all answers owned by the account for the specified question
    This action supports only DELETE HTTP method.
    
  • Parameters

    id - identifier of the question
    
  • Result

    The result will be 204 No Content code.
    

PostQuestionAnswer

  • URI

    POST /Questions/{id}/answers
    
  • Description

    Creates the answer for the question.
    This action supports only POST HTTP method.
    
  • Parameters

    id - identifier of the question to create answer for.
    
  • Request body JSON Structure

    JSON object with the following structure.
    AnswerTexts: Array of text representations of the Answer
    DefaultAnswerText: Default text representation of the Answer
    IsSystem: Denotes that the Question is system/global question (e.g. used for norms)
    
    All item of the AnswerTexts and the DefaultAnswerText can be maximum 400 charcter long.
    
  • Request body JSON Example

    {
          "AnswerTexts": [
            "Male",
            "Mann"
          ],
          "DefaultAnswerText": "Male",
          "IsSystem": true
    }
    
  • Result

    The result will be 201 Created code. Body will contain JSON object of the following structure.
    Id: The Id of the Answer
    AnswerTexts: Array of text representations of the Answer
    DefaultAnswerText: Default text representation of the Answer
    IsSystem: Denotes that the Question is system/global question (e.g. used for norms)
    
  • Result JSON Example

    {
          "Id": 1,
          "AnswerTexts": [
            "Male",
            "Mann"
          ],
          "DefaultAnswerText": "Male",
          "IsSystem": true
    }
    

UpdateAnswer

  • URI

    PUT /Answers/{id}
    
  • Description

    Updates the answer.
    This action supports only PUT HTTP method.
    
  • Parameters

    id - identifier of the answer to be updated
    
  • Request body JSON Structure

    JSON object with the following structure.
    AnswerTexts: Array of text representations of the Answer
    DefaultAnswerText: Default text representation of the Answer
    
    The AnswerTexts and DefaultAnswerText are optional.
    If they are not present in the posted data or they are there with Null value, they will be not updated.
    All item of the AnswerTexts and the DefaultAnswerText can be maximum 400 charcter long.
    
  • Request body JSON Example

    {
          "AnswerTexts": [
            "Male",
            "Mann"
          ],
          "DefaultAnswerText": "Male",
    }
    
  • Result

    The result will be 204 No Content code.
    

DeleteAnswer

  • URI

    DELETE /Answers/{id}
    
  • Description

    DELETES the answer
    This action supports only DELETE HTTP method.
    
  • Parameters

    id - identifier of the answer to be deleted
    
  • Result

    The result will be 204 No Content code.
    

GetTestElements

  • URI

    GET /Sessions/{sessionId}/testElement
    
  • Description

    Gets list of all test elements which was displayed at the session.
    This action supports only GET HTTP method.
    
  • Parameters

    sessionId - identifier of the session
    
  • Result

    Array of JSON object of the following structure.
    SequenceNo: The exposure number of the video inside the session
    MediaName: The name of the media
    MediaKey: The externally provided Media key
    TestElementKey: The externally provided TestElement key or the internally generated one.
    
  • Result JSON Example

    [
       {
          "SequenceNo":0,
          "MediaName":"woman-creative-design-wallpaper-1920x1200",
          "MediaKey":null,
          "TestElementKey":null
       },
       {
          "SequenceNo":1,
          "MediaName":"MadC Claudia Walde 3-2000-1333",
          "MediaKey":null,
          "TestElementKey":null
       },
       {
          "SequenceNo":2,
          "MediaName":"borubodour",
          "MediaKey":null,
          "TestElementKey":"TestElementExternalKey01"
       }
    ]
    

GetStudyShareKey

  • URI

    GET /StudyShareKeys/{studyId}
    
  • Description

    Gets share key and path for a public shared study.
    This action supports only GET HTTP method.
    
  • Parameters

    StudyId - Identifier of the study, with that the share key is identified here.
    
  • Result

    JSON object of the following structure.
    Id: The exposure number of the share key.
    StudyId: The exposure number of the study which ownes this share key.
    Key: The externally provided share key.
    Domain: The externally provided domain of the generated share key.
    Url: The externally provided full path of the shared study.
    IsEnabled: Means this share key public or private.
    
  • Result JSON Example

    {
        "Id":0,
        "StudyId":1,
        "Key":"12AB34",
        "Domain":"realeyes",
        "Url":"https://delivery.realeyesit.com/c/12AB34",
        "IsEnabled":true
    }
    

GetStudyShareKeys

  • URI

    GET /StudyShareKeys
    
  • Description

    Gets list of all shared keys and pathes for public shared studies.
    This action supports only GET HTTP method.
    
  • Parameters

    -
    
  • Result

    Array of JSON object of the following structure.
    Id: The exposure number of the share key.
    StudyId: The exposure number of the study which ownes this share key.
    Key: The externally provided share key.
    Domain: The externally provided domain of the generated share key.
    Url: The externally provided full path of the shared study.
    IsEnabled: Means this share key public or private.
    
  • Result JSON Example

    [
        {
            "Id":0,
            "StudyId":1,
            "Key":"12AB34",
            "Domain":"realeyes",
            "Url":"https://delivery.realeyesit.com/c/12AB34",
            "IsEnabled":true
        },
        {
            "Id":1,
            "StudyId":2,
            "Key":"56AB78",
            "Domain":"realeyes",
            "Url":"https://delivery.realeyesit.com/c/56AB78",
            "IsEnabled":false
        },
        {
            "Id":2,
            "StudyId":3,
            "Key":"12AB78",
            "Domain":"realeyes",
            "Url":"https://delivery.realeyesit.com/c/12AB78",
            "IsEnabled":true
        }
    ]
    

CreateStudyShareKey

  • URI

    POST /StudyShareKeys
    
  • Description

    Study can be made publicly accessible via a share Url with this method. In the respons a public access Url (Share Url) will be present.
    This action supports only POST HTTP method. You can't create more then one share key for a study.
    
  • Request body JSON Structure

    JSON object with the following structure.
    StudyId: Mandatory field, identifier of the study for that we want to create a new share key.
    
  • Request body JSON Example

    {
          "StudyId": "479"
    }
    
  • Result

    The result will be 201 Created code. Body will contain JSON object of the following structure.
    Id: The exposure number of the share key.
    StudyId: The exposure number of the study which ownes this share key.
    Key: The externally provided share key.
    Domain: The externally provided domain of the generated share key.
    Url: The externally provided full path of the shared study.
    IsEnabled: Means this share key public or private.
    
  • Result JSON Example

    {
        "Id":0,
        "StudyId":1,
        "Key":"12AB34",
        "Domain":"realeyes",
        "Url":"https://delivery.realeyesit.com/c/12AB34",
        "IsEnabled":true
    }
    

UpdateStudyShareKey

  • URI

    PUT /StudyShareKeys/{studyId}
    
  • Description

    Study share key can be updated, the public accessibility can be disabled or reenabled with this method. If a share key is disabled it behaves like it wouldn't exist.
    This action supports only POST HTTP method. You can't create more then one share key for a study.
    
  • Parameters

    StudyId - Identifier of the study, with that the share key is identified here.
    
  • Request body JSON Structure

    JSON object with the following structure.
    IsEnabled: Mandatory field, with that this share key can be made public (IsEnabled == true) or private (IsEnabled == false)
    
  • Request body JSON Example

    {
          "IsEnabled": "true"
    }
    
  • Result

    The result will be 204 No Content code.
    

GetTags

  • URI

    GET /Tags
    
  • Description

    Get list of all tags used on media.
    
  • Parameters

    None
    
  • Result JSON Structure

    The result JSON sructure will be an array of strings.
    
  • Result JSON Example

    [
          "Tag1",
          "Tag2",
          ...
    ]
    

Survey Data Management

The following terms will be used through the article.

Survey data - data associated with each collected session usually in the form of questions and corresponding answers. This data can be used to segment sessions into groups(e.g. Males vs Females) for future analysis.

Survey data item - single data item representing single attribute value of a single session.

Question - resource object in our records representing some valid sessions attribute usually in the form of the question(e.g. “Age” or “What is your age?”). This is a muttable object and has the identifier that can be used to update/delete it.

Answer - resource object in our records representing some valid sessions attribute value usually in the form of the answer(e.g. “18yrs”, “Male”, “Non smoking”). This is a muttable object and has the identifier that can be used to update/delete it.

Text representation - representation of some object in the form of string value(case insensitive). Usually object can have many text representations(e.g. synonyms, localization). Another use of multiply text representations is grouping of similar objects into one object (e.g. grouping age values “18”, “19”, “20” into one answer object with default text representation “18-20”). Text representations are immutable in objects in our system and don’t have identifiers (their string value is their identity).

Question text representation - text representation of the Question object. When creating questions you can specify a list of string values that are different text representations of the same Question(e.g. [“Age”, “What is your age?”, “How old are you?”, “Alter”,…]). Also you should specify default text representation that will be used in our reports(e.g. chart page filter label(“Age”)).

Answer text representation - text representation of the Answer object. When creating answers you can specify a list of string values that are different text representations of the same Answer(e.g. [“Male”, “Mann”, “M”, “Мужчина”,…]). Also you should specify default text representation that will be used in our reports(e.g. chart page filter option label(“Male”)).

Survey Data Management Rest API is described in this document starting from GetSessionSurveyData method. Currently survey data is used to filter and group sessions into segments that can be analysed separately. Old channels of survey data include csv files uploads and/or callbacks to the survey providers to retrieve this data when new session is created/collected. Survey Data Management Rest API is a new channel recommended to the users who want to automate their survey data upload workloads.

Survey Data Management includes creation and maintainance of Question/Answer collections, posting survey data for each created/collected sessions. Creating Question and Answers before posting survey data is not necessary but required if you want to guarantee that no duplicate Question and Answer objects will be accidentally added to our records(e.g. “Male” and “Mann” is logically the same answer and it is desirable to put session with such attribute value into one bucket when analyzing). To fulfill this mission you can either resolve such issues in your system before posting survey data to us. In that case you can create a single Question/Answer object in our system using Rest Api and further post sessions’ survey data to us with Id of this object in the payload. Otherwise you can delegate this work to our system by using text representations. The workflow in that case includes creation of a single Question/Answer object with multiply text representations denoting the same value. When posting sessions’ survey data you can specify question/answer text value instead of the id and we will use that text value to find it through the list of existant text representations of all avaliable questions and answers belonging to your account in our records and binding will happen automatically. If no question/answer with supplied text representation found, we will skip this survey data item and tell you about each such item in the api call reponse body. You can afterwards take actions(even manual) to resolve this new text representations in our system (add new text representation to one of the Question/Answer objects) and reupload those failed items only.

Lets look how one can post session’s survey data to our system. For that purpose you can make http POST request to /Sessions/{sessionId}/surveyData Rest Uri with the array of survey data items in payload:

[
     {
      "AnswerId": 1,
      "AnswerText": "20",
      "QuestionId": 1,
      "QuestionText": "How old are you?"
    },
    {
      "AnswerId": 2,
      "AnswerText": "Male",
      "QuestionId": 2,
      "QuestionText": "What is your gender?"
    }
]

This will mark the session as a 20 years old male. The AnswerId and QuestionId are the identifiers of the corresponding Answer and Question objects. AnswerText and QuestionText are the original text representations of the Answer and Question objects in your system(e.g. what participant(session) actually saw when completing survey). Not all fields are required to post and our Api support different workflows(some of them were described above).

Specifying only AnswerId with/without QuestionId - in this case we are able to link survey data item to correct Answer and Question object. QuestionId is not really required because we can find Question based on Answer, but we recommend setting it properly for future compatibility. If you additionaly specify Text fields those will be recorded as original text values passed and can be used in future for audit/restore purposes.

Specifying only QuestionId with AnswerText - in this case we are able to link survey data item to correct Question object. AnswerText in turn is used to find matching text representation of one of the Answers belonging to above Question.

Specifying only QuestionText with AnswerText - in this case we are using supplied text values to find matching text representations of one of the Questions and then we do the same for the Answer.