Developer Zone

Metadata Queries

Usage Intelligence reports support filtering and segmentation by a number of different properties. In order to be able to build filters and custom segments, you first need to know what filters are available and what filter values are possible.

Getting a list of filter / segmentation properties

This request is to be used to get a list of properties by which you can filter or segment your reports.

Request/response parameters summary

POST /meta/productProperties

The request and reponse are both JSON objects. The following is a summary of the properties inside the request and response objects.

Request JSON Object:
 
  • user (string) – The username of your Usage Intelligence user account. Required only for non-cookie authentication.
  • sessionId (string) – The sessionId obtained via POST /auth/login. Required only for non-cookie authentication.
  • productId (integer) – The product ID on which this request is being done
Request Headers:
 
  • Content-Type – Can be set to application/json or text/javascript
  • Accept – Should be set to text/javascript
Response Headers:
 
Status Codes:
Response JSON Object:
 
  • status (string) – Contains OK if successful or SYNTAX ERROR or AUTH ERROR
  • reason (string) – Present only if status is not OK. Contains error message (reason)
  • results (array) – Present only if status is OK. Contains the list of available properties as described below.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "OK",
    "results": [
        {
            "category": "Product Properties",
            "properties": [
                {
                    "name": "prodVersion",
                    "friendlyName": "Product Version",
                    "filterType": "standard",
                    "dataType": "string"
                },
                {
                    "name": "prodEdition",
                    "friendlyName": "Product Edition",
                    "filterType": "standard",
                    "dataType": "string"
                },
                {
                    "name": "prodLanguage",
                    "friendlyName": "Product Language",
                    "filterType": "standard",
                    "dataType": "string"
                },
                {
                    "name": "prodBuild",
                    "friendlyName": "Product Build",
                    "filterType": "standard",
                    "dataType": "string"
                }
            ]
        },
        {
            "category": "Licensing Properties",
            "properties": [
                {
                    "name": "licenseType",
                    "friendlyName": "License Type",
                    "filterType": "standard",
                    "dataType": "string"
                },
                {
                    "name": "licenseStatus",
                    "friendlyName": "License Status",
                    "filterType": "standard",
                    "dataType": "special",
                    "subProperties": [
                        {
                            "name": "activated",
                            "friendlyName": "Activated",
                            "dataType": "boolean"
                        },
                        {
                            "name": "blacklisted",
                            "friendlyName": "Blacklisted",
                            "dataType": "boolean"
                        },
                        {
                            "name": "expired",
                            "friendlyName": "Expired",
                            "dataType": "boolean"
                        },
                        {
                            "name": "whitelisted",
                            "friendlyName": "Whitelisted",
                            "dataType": "boolean"
                        }
                    ]
                }
            ]
        },
        {
            "category": "Platform Properties",
            "properties": [
                {
                    "name": "osLanguage",
                    "friendlyName": "OS Language",
                    "filterType": "standard",
                    "dataType": "string"
                },
                {
                    "name": "os",
                    "friendlyName": "OS",
                    "filterType": "standard",
                    "dataType": "special",
                    "granularityLevels": [
                        {
                            "name": "platform",
                            "friendlyName": "Platform",
                            "dataType": "string"
                        },
                        {
                            "name": "version",
                            "friendlyName": "Version",
                            "dataType": "string"
                        },
                        {
                            "name": "edition",
                            "friendlyName": "Edition",
                            "dataType": "string"
                        }
                    ]
                },
                {
                    "name": "geography",
                    "friendlyName": "Geography",
                    "filterType": "standard",
                    "dataType": "special",
                    "granularityLevels": [
                        {
                            "name": "continent",
                            "friendlyName": "Continent",
                            "dataType": "string"
                        },
                        {
                            "name": "country",
                            "friendlyName": "Country",
                            "dataType": "string"
                        },
                        {
                            "name": "usState",
                            "friendlyName": "US State",
                            "dataType": "string"
                        }
                    ]
                },
                {
                    "name": "formFactor",
                    "friendlyName": "Form Factor",
                    "filterType": "currentData",
                    "dataType": "string"
                },
                {
                    "name": "cpuType",
                    "friendlyName": "CPU Type",
                    "filterType": "currentData",
                    "dataType": "string"
                },
                {
                    "name": "cpuCores",
                    "friendlyName": "CPU Cores",
                    "filterType": "currentData",
                    "dataType": "numeric",
                    "units": ""
                },
                {
                    "name": "displayCount",
                    "friendlyName": "Monitor Count",
                    "filterType": "currentData",
                    "dataType": "numeric",
                    "units": ""
                },
                {
                    "name": "ram",
                    "friendlyName": "RAM",
                    "filterType": "currentData",
                    "dataType": "numeric",
                    "units": "MB"
                },
                {
                    "name": "resolutionWidth",
                    "friendlyName": "Resolution - Horizontal",
                    "filterType": "currentData",
                    "dataType": "numeric",
                    "units": "px"
                },
                {
                    "name": "resolutionHeight",
                    "friendlyName": "Resolution - Vertical",
                    "filterType": "currentData",
                    "dataType": "numeric",
                    "units": "px"
                },
                {
                    "name": "osWordLength",
                    "friendlyName": "OS Word Length",
                    "filterType": "currentData",
                    "dataType": "numeric",
                    "units": "bit"
                }
            ]
        }
    ]
}

Getting a list of possible property values

This request is used in order to get a list of possible values for the selected property. This data is then used to build filters or segments as required.

Request/response parameters summary

POST /meta/propertyValues

The request and reponse are both JSON objects. The following is a summary of the properties inside the request and response objects.

Request JSON Object:
 
  • user (string) – The username of your Usage Intelligence user account. Required only for non-cookie authentication.
  • sessionId (string) – The sessionId obtained via POST /auth/login. Required only for non-cookie authentication.
  • productId (integer) – The product ID on which this request is being done
  • property (string) – The name of the property to retrieve listing for
  • filter (string) – An optional value used to filter very long meta lists. This feature is not available if the property is geography or os. Details about filtering can be found in the Filtering long lists section.
  • granularity (string) –

    Required only when property is os or geography. The values can be as follows:

    • If geography:
      • continent
      • country
      • usState
    • If os:
      • platform
      • version
      • edition
  • getFullList (boolean) – Optional value. Can be used when property is os, osLanguage, or geography. Instructs the server to return a list of all known values by the system instead of showing only the ones that were collected in this praticular product. Default is false.
Request Headers:
 
  • Content-Type – Can be set to application/json or text/javascript
  • Accept – Should be set to text/javascript
Response Headers:
 
Status Codes:
Response JSON Object:
 
  • status (string) – Contains OK if successful or SYNTAX ERROR or AUTH ERROR
  • reason (string) – Present only if status is not OK. Contains error message (reason)
  • results (array) –

    Present only if status is OK. Contains the list of property values. Each item is presented in a JSON object as follows:

    • value (string) – Present in all responses. This contains the value that is to be used for filtering and segmentation.
    • shortName (string) – Present if property is os. Contains an abbreviated OS name that can fit better in some user interfaces.
    • devBuild (boolean) – Present if property is prodBuild. Contains true if a product build has been marked as a development (testing) build and false if not.
    • fullName (string) – Present if property is geography or osLanguage. Contains the full continent, country, US state, or language name while the value property contains an abbreviated code.
  • truncated (boolean) – Present only if the list is too long. Use filtering in order to retrieve shorter lists.

Example request:

POST meta/propertyValues  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 12345678901,
    "property": "os",
    "granularity": "version"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "status": "OK",
     "results": [
                     {
                         "value": "Microsoft Windows XP",
                         "shortName": "MS Win XP"
                     },
                     {
                         "value": "Microsoft Windows Server 2003",
                         "shortName": "MS Win Srv 2003"
                     },
                     {
                         "value": "Microsoft Windows Vista",
                         "shortName": "MS Win Vista"
                     },
                     {
                         "value": "Microsoft Windows Server 2008",
                         "shortName": "MS Win Srv 2008"
                     },
                     {
                         "value": "Microsoft Windows 7",
                         "shortName": "MS Win 7"
                     }
                ]
}

Filtering long lists

When the list of property values is too long, the list will get truncated. This is especially common on requests related with custom properties. The filter property is a JSON object which should contain the following values:

  • type (string) – Can be either regex or string. Normally, regex should be used because string is to be used only to verify existance of a certain value.
  • value (string) – A string normally containing a regular expression that defines the filter to be applied.

Getting oldest permitted date

POST /meta/oldestReportedDate

This request returns the oldest allowed start date based on the product plan.

Example request:

POST meta/oldestReportedDate  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 12345678901
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "OK",
    "oldestDate": "2015-06-20"
}