Developer Zone

Generic Date-Range Reports

This reporting mechanism is to be used for generating reports regarding user activity within a particular specified date range. Depending on the request, this can create timeline charts, pie/bar charts, geographical maps, or hierarchical tables.

Request/response parameters summary

POST /reporting/generic/dateRange

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
  • dateSplit (string/null) – Whether to present results by day, week, or month or to combine all results into a pie/bar chart or table
  • startDate (string) – The first date of the date range on which to base the report. This is to be formatted as YYYY-MM-DD.
  • stopDate (string) – The last date of the date range on which to base the report. This is to be formatted as YYYY-MM-DD.
  • clientStatus (array) – The client statuses to show in the report. Each report can show any combination of new, active, and lost users. This is to be presented as an array of up to 3 strings which can be new, active, and lost.
  • daysUntilDeclaredLost (integer) – Required only if the clientStatus array contains lost. This specifies the number of consecutive days of inactivity that have to pass until a client installation is declared lost.
  • dateReportedLost (string) – Required only if the clientStatus array contains lost. When an installation is lost, it can either be shown as lost on the date it last contacted the Revulytics servers (dateLastSeen) or else it can be shown as lost when it was declared lost (last date when it contacted Revulytics + the number of days specified in daysUntilDeclaredLost) (dateDeclaredLost). Therefore, the permitted values are dateLastSeen and dateDeclaredLost.
  • globalFilters (object) – JSON object containing the filters to be applied to the available data. Details about these filters can be found in the Global Filters section.
  • levels (object) – Optional JSON object that describes how data is to be split into segments in each level. Requests where dateSplit is null can have up to 3 levels while when date splitting is being done, 0 or 1 levels can be specified. Details about levels and segmentation can be found in the Segmentation and Levels section.
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)
  • levelLabels (object) – Present only on responses where dateSplit is null. When present, this contains the property names of each level as requested.
  • results (object) – Contains the results as requested represented as a JSON object. The structure differs between reports using date splitting and those that have date splitting set to null. The result format is described below.

Global Filters

Most of the available filter properties are string-based. This means that when applying a filter, the requested field can be represented as a string, stringArray or regex. There are also some filters which are numeric. These filters should be represented as number or numberRange.

String-based filters

The following properties are stored as strings:

  • prodVersion
  • prodEdition
  • prodBuild
  • prodLanguage
  • licenseType
  • formFactor *
  • osLanguage
  • osWordLength *
  • cpuType *
  • dotNetVersion *
  • licenseKey * **

The type field in the above filters needs to be string, stringArray or regex. A value field is always required. The contents of this field should be according to the specified type. If string is specified, then the value field must contain a single string that needs to be matched precisely with the stored data. If stringArray is specified, then the value field must contain an array of strings where one of which needs to match precisely with the stored data. If specifying a regex, the value field should contain a string which is treated as a regular expression and the stored data will be matched against it using regular expression rules.

* These marked properties are based on the current (latest known) values.
** licenseKey requires a special user permission to be used as a filter.

Example filter using a string value

In this example, the product build value needs to be exactly “3014.int-12214”:

{
      "prodBuild":
          {
              "type": "string",
              "value": "3014.int-12214"
          }
 }

Example filter using a string array

In this example, the product build value needs to be either “3014.int-12214”, “3017.enx-57718”, or “4180.vrx-81059”. Note that since the type is declared as stringArray, the value field needs to contain an array. Consider all elements in the array to have an OR logical expression between them.:

{
    "prodBuild":
        {
            "type": "stringArray",
            "value": ["3014.int-12214", "3017.enx-57718", "4180.vrx-81059"]
        }
}

Example filter using a regular expression

In this example, the product build value needs to start with “30” and end with “18” whilst having 10 characters in between:

{
     "prodBuild":
         {
             "type": "regex",
             "value": "^30.{10}18$"
         }
}

Numeric filters

The following properties are stored as numeric values:

  • cpuCores *
  • displayCount *
  • ram *
  • resolutionWidth *
  • resolutionHeight *
  • lifetimeRuntimeMinutes *
  • lifetimeSessionCount *

* These marked properties are based on the current (latest known) values.

The type field in the above filters needs to be number or numberRange. If number is specified, then a value field must also be present. The value field should contain a number, which may contain a decimal point if required. If numberRange is specified, then the value field should NOT be used. Instead, the properties min and max are to be used. These refer to the minimum and maximum number to be included in the report. If only one limit needs to be set, the other property is to be left out. Therefore, if you want to include installations with up to 2 display devices, you would not specify a min value, but instead specify only a max and set it as 2.

Example filter using a number value

In this example, the number of display devices needs to be exactly 3:

{
      "displayCount":
          {
              "type": "number",
              "value": 3
          }
 }

Example filter using a number range value

In this example, the RAM needs to be between 1025MB and 4096MB (both included):

{
      "ram":
          {
              "type": "numberRange",
              "min": 1024,
              "max": 4096
          }
 }

Special filters

Some filters need to be represented in a special format due to their unique requirements. These special filters are:

Special filter: licenseStatus

The licenseStatus filter is made up of 4 sub-values: activated, blacklisted, expired and whitelisted. These are presented as boolean values. Unlike other filters, this filter is presented as an array of JSON objects. Each object can contain a subset (or all) of these 4 boolean values. Consider the following example. In this example, for a client to be included, the license has to either be activated AND whitelisted, or else it can be not whitelisted AND expired. In other words, ( (activated AND whitelisted) OR ((NOT)whitelisted AND expired) ).

{
    "licenseStatus":
        [
            {
                "activated": true,
                "whitelisted": true
            },
            {
                "whitelisted": false,
                "expired": true
            }
        ]
}

Special filter: os

The os filter is made up of 3 granularity levels. These are platform, version, and edition. These are meant to split the OS name into levels of detail as required by the user. Consider the following:

  • platform: Microsoft Windows
  • version: Microsoft Windows 7
  • edition: Microsoft Windows 7 Professional

If a filter is set on the version “Microsoft Windows 7”, the result would include all editions of Windows 7. One or more of these granularity levels may be specified. If more than 1 granularity level is specified, the values are ORed together.

In the following example, all editions of “Microsoft Windows 7” are included, and also “Microsoft Windows Vista Home Premium”:

{
    "type": "string",
    "version": "Microsoft Windows 7",
    "edition": "Microsoft Windows Vista Home Premium"
}

In the following example, the type is stringArray. Note that an array needs to be passed if the type is set as such, even if it is to contain only 1 element. In this case, the version can be either “Microsoft Windows 7” or “Microsoft Windows 8” (which are ORed together). Also, clients running on “Microsoft Windows XP Professional” are to be included.

{
    "type": "stringArray",
    "version": ["Microsoft Windows 7", "Microsoft Windows 8"],
    "edition": ["Microsoft Windows XP Professional"]
}

Special filter: geography

The geography filter is made up of 3 granularity levels. These are continent, country, and usState. The usState value applies only to United States. Continents and countries are presented in 2-letter codes. Countries follow ISO standard 3166-1 alpha-2. US states are presented in ISO 3166-2:US format.

In the following example, the clients have to be either:

  • In the continents Asia or Oceania
  • In the country Germany
  • In the US states New York, New Jersey, or Kansas
{
    "type": "stringArray",
    "continent": ["AS", "OC"],
    "country": ["DE"],
    "usState": ["US-NY", "US-NJ", "US-KS"]
}

IMPORTANT: In this filter, the type can be string or stringArray. Regular expressions are not supported in geography filters.

Special filter: gpu

The gpu filter is made up of 2 granularity levels. These are vendor and model. Both are represented as string values.

In the following example, the clients have have a GPU:

  • From the vendors NVIDIA or Intel
  • With the model number AMD Radeon HD 4600
{
    "type": "stringArray",
    "vendor": ["NVIDIA", "Intel"],
    "model": ["AMD Radeon HD 4600"]
}

Special filters: optOut and backOff

The opt-out was introduced in SDK version 5.1.0. With this feature, vendors can have their application report to the Revulytics servers that a user does not want to be tracked. With this feature, vendors can filter-out installations that were opted-out. Similarly, backoff filtering was introduced with version 5.0.0. Backoff is when a product account runs over-quota and the server starts rejecting data. Although filtering for backed-off installations was introduced with version 5, it was also backported to previous versions. However, when a new installation with an SDK prior to version 5 tries to register with the server and is rejected, it is not marked as being once backed-off when it is eventually accepted by the server. With version 5 onwards, the server flags an installation as being historically backed-off in such cases.

Both backOff and optOut filters are made up of 2 boolean sub-values: historical and current. The historical value refers to installations that were once backed-off or opted-out. These may include installations that are still currently backed-off or opted-out. The current value refers to the status during the last time that the client called the server. Therefore, if an installation was opted-out yesterday but got opted-in today, it will be marked as historically opted-out but not currently opted-out.

In the following example, for a client to be included, the optOut status has to either be historical AND not current, or else it can be not historical.

{
    "optOut":
        [
            {
                "historical": true,
                "current": false
            },
            {
                "historical": false
            }
        ]
}

Segmentation and Levels

Report data may be segmented in up to 3 levels. Each level represents a property. Using multi-level segmentation, you can create hierarchical reports that are used to drill down based on the property values. For example, you can create a report that splits all the users based on which edition they are using. Then, you can split the user counts for each edition based on product version on level 2. Finally, the user counts for each product version can be split up by product build on level 3.

Such multi-level reporting is available only when not splitting by date. Splitting by date is meant to be used in timeline reports, and creating such a hierarchy for each date would result in a huge data set which would only have limited use. When date splitting is used, segmentation with 1 level is still allowed, however. This allows creating timeline reports where each line represents a property value, such as comparing usage trend for version 1 vs version 2.

Segmentation is optional. In order not to split data by any property, you may either not include a levels property in the request object, or else leave the levels object empty. The following examples show the difference between not requesting any segmentation, requesting a single level, and requesting 2 levels:

0 Levels

  • New Users: 30
  • Active Users: 100
  • Lost Users: 20

1 Level

Product Versions:
  • Version 1:
    • New Users: 10
    • Active Users: 30
    • Lost Users: 8
  • Version 2:
    • New Users: 20
    • Active Users: 70
    • Lost Users: 12

2 Levels

Product Versions:
  • Version 1:
    • New Users: 10
    • Active Users: 30
    • Lost Users: 8
    Product Editions:
    • Premium:
      • New Users: 4
      • Active Users: 13
      • Lost Users: 1
    • Standard:
      • New Users: 6
      • Active Users: 17
      • Lost Users: 7
  • Version 2:
    • New Users: 20
    • Active Users: 70
    • Lost Users: 12
    Product Editions:
    • Premium:
      • New Users: 5
      • Active Users: 40
      • Lost Users: 4
    • Standard:
      • New Users: 15
      • Active Users: 30
      • Lost Users: 8

In the above examples, the first example is showing a case where no segmentation is being applied. The second example is showing a response where a single level of segmentation has been requested. In this case, segmentation is being done based on product versions. For each product version, one can see the number of new, active, and lost users within the specified date range. Segmenting by 1 level is also possible in reports that use date splitting, so, in a similar example, one would be able to see how many users were using a specific version on each day within the date range. The third example shows 2 levels of segmentation. In this example, one can see how many new, active, and lost users were using each version, and then, that data is further split by product edition. A further level is also allowed, so, for example one may choose to segment each product edition by product language.

The properties that are available for segmentation are the same ones that are used for Global Filters. There are 4 properties that require special formatting. These are described below.

Segment levels are to be defined in a property inside the main JSON object named “levels”. This property should contain a JSON object which contains the following members:

  • property (string) - The name of the property by which to segment. Note that in case of os, geography, licenseStatus and gpu, a special format is used.
  • segments (array) - An array containing a number of JSON objects. The format of these object is described in the Level Segments Format section below.
  • sort (string) - Optional property to specify how the segments in this level are to be sorted. Possible values are alpha, new, active, and lost. alpha refers to alphabetical sorting which is based on the segment label. The other 3 are based on the client statuses. Note that if sorting by new, active, or lost users, that particular client status must be included in the clientStatus array. If this property is not included, the data is sorted alphabetically by default.
  • sortDirection (string) - Optional property to specify whether to sort in ascending or descending order. Possible values are asc and desc. If not specified, data is sorted in ascending order by default.

Level Segments Format

Segments are defined as JSON objects. A single JSON object may create a single item on a table (or a single series on a timeline chart), or it may create a number of items/series if splitting is enabled. Each object should contain the following:

  • type (string) - The data type of the value. Can be string, stringArray, regex, number or numberRange based on whether the property is string-based or numeric.
  • value (string/array/number) - An exact string, an array of strings, a regular expression or a numeric value. This property should not be used if type is numberRange. Format is based on whether the property is string-based or numeric.
  • min (number) - Used only if the type is numberRange. Contains the minimum numeric value to include in this segment. May be combined with max.
  • max (number) - Used only if the type is numberRange. Contains the maximum numeric value to include in this segment. May be combined with min.
  • split (boolean) - Used only if the type is stringArray or regex. This specifies whether to split the returned data based on each different value matched by the regular expression or array (true), or to join all the clients that match the value as 1 table value or series (false).
  • segmentLabel (string) - Used only if split is false or if type is numberRange. This is required to give a name to a series when not splitting by value. It is important that the name given is unique.
  • limit (integer) - Optional property to set the limit on the maximum number of table values or serieses that should be produced by this set of values. To be used only if split is true.

String-based segmentation properties

The following properties are stored as strings:

  • prodVersion
  • prodEdition
  • prodBuild
  • prodLanguage
  • licenseType
  • formFactor *
  • osLanguage
  • osWordLength *
  • cpuType *
  • licenseKey * **
* These marked properties are based on the current (latest known) values.
** licenseKey requires a special user permission to be used for segmentation

The type field when using one of the above properties needs to be string, stringArray or regex. A value field is always required. The contents of this field should be according to the specified type. If string is specified, then the value field must contain a single string that needs to be matched precisely with the stored data. If stringArray is specified, then the value field must contain an array of strings where one of which needs to match precisely with the stored data. If specifying a regex, the value field should contain a string which is treated as a regular expression and the stored data will be matched against it using regular expression rules.

Example using 1-level segmentation by number, and numberRange values

{
    "level1": {
        "property": "cpuCores",
        "segments": [
            {
                "type": "number",
                "value": 1,
            },
            {
                "type": "numberRange",
                "min": 2,
                "max": 4
                "segmentLabel": "2 - 4"
            },
            {
                "type": "numberRange",
                "min": 5,
                "segmentLabel": "5 +"
            }
        ]
    }
}

In the above example, we are requesting a report with 3 segments. The first segment containa only installations running on 1 CPU core, the second segments contains installations running on 2, 3, or 4 cores (range 2 - 4), while the last segment contains all installations which are running on a machine with 5 or more CPU cores. Note how when the type was numberRange, we had do specify a segmentLabel which is a free string that will be used by the user to identify what is being included in that specific segment.

Numeric segmentation properties

The following properties are stored as numeric values:

  • cpuCores *
  • displayCount *
  • ram *
  • resolutionWidth *
  • resolutionHeight *

* These marked properties are based on the current (latest known) values.

The type field in the above properties needs to be number or numberRange. If number is specified, then a value field must also be present. The value field should contain a number, which may contain a decimal point if required. If numberRange is specified, then the value field should NOT be used. Instead, the properties min and max are to be used. These refer to the minimum and maximum number to be included in the report. If only one limit needs to be set, the other property is to be left out. Therefore, if you want to include installations with up to 2 display devices, you would not specify a min value, but instead specify only a max and set it as 2.

Example filter using a number value

In this example, the number of display devices needs to be exactly 3:

{
      "displayCount":
          {
              "type": "number",
              "value": 3
          }
 }

Example filter using a number range value

In this example, the RAM needs to be between 1025MB and 4096MB (both included):

{
      "ram":
          {
              "type": "numberRange",
              "min": 1024,
              "max": 4096
          }
 }

Special segmentation properties

Some properties need to be represented in a special format due to their unique requirements. These special properties are:

Special segmentation format: licenseStatus

The licenseStatus value is made up of 4 sub-values: activated, blacklisted, expired and whitelisted. These are presented as boolean values. Any number of segments can be defined, and each segment can contain any subset of the 4 sub-values. These values are ANDed together. A segmentLabel value is required.

In the following example, 2 table values/series are produced - the first one showing blacklisted AND not expired and the second one showing whitelisted AND activated:

[
    {
        "segmentLabel": "BL and not EXP",
        "blacklisted": true,
        "expired": false
    },
    {
        "segmentLabel": "WL and ACT",
        "whitelisted": true,
        "expired": true
    }
]

Special segmentation format: os

The os value is made up of 3 granularity levels - platform, version, and edition. A particular level needs to be selected for a level, and this is to be included in the property name such as os.version or os.edition. Different granularity levels can be requested for different segmentation levels. Therefore, it is possible to generate a 3-level hierarchical tree in which level 1 would show the OS platform, level 2 would show the version, and level 3 would show the full name including the OS edition or sub-version. For a description of the differences between the 3 granularity levels, refer to the os special filter section.

The following example shows the levels object requesting 3 granularity levels as described above:

{
    "level1": {
        "property": "os.platform",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    },
    "level2": {
        "property": "os.version",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    },
    "level3": {
        "property": "os.edition",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    }
}

In the above example, no filtering is being done, and instead, a regular expression to include everything is set as the value. This will result in the top OS platforms, versions, and editions to be included in the hierarchy.

Special segmentation format: geography

The geography value is made up of 3 granularity levels - continent, country, and usState. These granularity levels are explained in the geography special filter section. A particular level needs to be selected for a level, and this is to be included in the property name such as geography.continent or geography.country. Different granularity levels can be requested for different segmentation levels. Therefore, it is possible to generate a 3-level hierarchical tree in which level 1 would show the continent, level 2 would show the country, and level 3 would show the US state (for United States only).

The following example shows the levels object requesting 3 granularity levels as described above:

{
    "level1": {
        "property": "geography.continent",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    },
    "level2": {
        "property": "geography.country",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    },
    "level3": {
        "property": "geography.usState",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    }
}

In the above example, no filtering is being done, and instead, a regular expression to include everything is set as the value. This will result in all the continents, and the top countries and US states (where applicable) to be included in the hierarchy.

Special segmentation format: gpu

The gpu value is made up of 2 granularity levels - vendor and model. These granularity levels are explained in the gpu special filter section. A particular level needs to be selected for a level, and this is to be included in the property name, namely gpu.vendor or gpu.model. Different granularity levels can be requested for different segmentation levels. Therefore, it is possible to generate a 2-level hierarchical tree in which level 1 would show the vendor, and level 2 would show the model number.

The following example shows the levels object requesting 2 granularity levels as described above:

{
    "level1": {
        "property": "gpu.vendor",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    },
    "level2": {
        "property": "gpu.model",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    }
}

In the above example, no filtering is being done, and instead, a regular expression to include everything is set as the value. This will result in all the GPU vendors and the top models to be included in the hierarchy.

Special segmentation format: optOut and backOff

Both backOff and optOut filters are made up of 2 boolean sub-values: historical and current. Any number of segments can be defined, and each segment can contain any subset of the 2 sub-values. These values are ANDed together. A segmentLabel value is required.

In the following example, 2 table values/series are produced - the first one showing historical AND not current and the second one showing not historical (i.e. never opted-out):

[
    {
        "segmentLabel": "HISTORICAL and not CURRENT",
        "historical": true,
        "current": false
    },
    {
        "segmentLabel": "Never opted-out",
        "historical": false
    }
]

Results format for reports using date splitting

The results object contains a number of members having a date as the key and an object as the value. The date is formatted as YYYY-MM-DD regardless of whether the report is being split by day, week, or month. If the report is being split by week or by month, the first date of the week or month is used.

If segmentation level 1 has been specified in the request, each sub-object contains a number of values. The keys are the property values that were specified in the request as level 1. Therefore, if prodVersion was requested as the property of level 1, the keys would be the different product version numbers or the segmentLabel that was specified. The value contains an object with up to 3 members. These are new, active, and lost, referring to new, active, and lost clients within this day, week, or month based on what was specified in the *clientStatus property in the request. Refer to the following example for a sample request and response.

Full example request/response of daily timeline report with segmentation

The following example request and response show a timeline report being segmented by selected product versions. Versions 1 and 1.5 are being combined into a single series, while version 2 is in a series on its own.

Example request

POST reporting/generic/dateRange  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 12345678901,
    "dateSplit": "day",
    "startDate": "2014-08-01",
    "stopDate": "2014-08-03",
    "clientStatus": [
        "new",
        "active",
        "lost"
    ],
    "daysUntilDeclaredLost": 30,
    "dateReportedLost": "dateDeclaredLost",
    "globalFilters": {
        "prodLanguage": {
            "type": "stringList",
            "value": ["English", "French"]
        },
        "os": {
            "type": "string",
            "version": "Microsoft Windows 7"
        }
    },
    "levels": {
        "level1": {
            "property": "prodVersion",
            "segments": [
                {
                    "type": "stringArray",
                    "value": [
                        "1",
                        "1.5"
                    ],
                    "segmentLabel": "1 and 1.5",
                    "split": false
                },
                {
                    "type": "string",
                    "value": "2"
                }
            ]
        }
    }
}

Example server response

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

{
    "status": "OK",
    "results": {
        "2014-08-01": {
            "2": {
                "active": 80,
                "new": 2,
                "lost": 0
            },
            "1 and 1.5": {
                "active": 133,
                "new": 0,
                "lost": 4
            }
        },
        "2014-08-02": {
            "2": {
                "active": 58,
                "new": 18,
                "lost": 0
            },
            "1 and 1.5": {
                "active": 74,
                "new": 0,
                "lost": 5
            }
        },
        "2014-08-03": {
            "2": {
                "active": 38,
                "new": 20,
                "lost": 0
            },
            "1 and 1.5": {
                "active": 31,
                "new": 0,
                "lost": 1
            }
        }
    }
}

Results format for reports using date splitting with no segmentation levels

If no segmentation levels have been specified in the request, the results object still contains members having a date as the key and an object as the value. However, the sub-object contains the new, active, and lost values or a subset of them.

The following is and example of the results object with only new and active specified in the clientStatus property.

{
    "2014-05-01": {
        "active": 643,
        "new": 27
    },
    "2014-05-02": {
        "active": 637,
        "new": 31
    },
    "2014-05-03": {
        "active": 322,
        "new": 19
    }
}

Results format for reports without date splitting

The results object contains a hierarchy of sub-objects depending on how many segmentation levels were requested. If at least 1 level was requested, the results object will contain only 1 member named level1. The value of level1 is a JSON object with a member for each segment of level 1. Therefore, assuming the level 1 property is prodVersion, the keys contain product versions or the segment labels that were specified. The value for each of these members will be an object containing an object named totals and if 2 or more levels were requested, another object named level2. The totals object will contain up to 3 members - new, active, and lost, based on what was specified in the clientStatus property in the request. If the level2 object is present, it will be in the same format as level1. Similarly, the level2 object may contain an object named level3. Refer to the following example for a sample request and response.

Full example request/response of report with 2-level segmentation

The following example request and response show a requested report not split by dates but with the data segmented by selected product versions in level 1 and all product editions in level 2. In level 1, product versions 1 and 1.5 are being combined into a single segment, while product version 2 is in a segment on its own. In level 2, each known product edition will be shown in a segment on its own.

Example request

POST reporting/generic/dateRange  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 12345678901,
    "dateSplit": null,
    "startDate": "2014-08-01",
    "stopDate": "2014-08-03",
    "clientStatus": [
        "new",
        "active",
        "lost"
    ],
    "daysUntilDeclaredLost": 30,
    "dateReportedLost": "dateDeclaredLost",
    "globalFilters": {
        "os": {
            "type": "string",
            "version": "Microsoft Windows 7"
        }
    },
    "levels": {
        "level1": {
            "property": "prodVersion",
            "segments": [
                {
                    "type": "stringArray",
                    "value": [
                        "1",
                        "1.5"
                    ],
                    "segmentLabel": "1 and 1.5",
                    "split": false
                },
                {
                    "type": "string",
                    "value": "2"
                }
            ]
        },
        "level2": {
            "property": "prodEdition",
            "segments": [
                {
                    "type": "regex",
                    "value": ".*",
                    "split": true
                }
            ]
        }
    }
}

Example server response

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

{
    "status": "OK",
    "levelLabels": {
        "level1": "prodVersion",
        "level2": "prodEdition"
    },
    "results": {
        "level1": {
            "2": {
                "totals": {
                    "new": 40,
                    "active": 138,
                    "lost": 0
                },
                "level2": {
                    "Lite": {
                        "totals": {
                            "new": 5,
                            "active": 30,
                            "lost": 0
                        }
                    },
                    "Premium": {
                        "total": {
                            "new": 5,
                            "active": 17,
                            "lost": 0
                        }
                    },
                    "Standard": {
                        "totals": {
                            "new": 30,
                            "active": 91,
                            "lost": 0
                        }
                    }
                }
            },
            "1 and 1.5": {
                "totals": {
                    "new": 0,
                    "active": 174,
                    "lost": 10
                },
                "level2": {
                    "Lite": {
                        "total": {
                            "new": 0,
                            "active": 48,
                            "lost": 5
                        }
                    },
                    "Premium": {
                        "totals": {
                            "new": 0,
                            "active": 13,
                            "lost": 1
                        }
                    },
                    "Standard": {
                        "totals": {
                            "new": 0,
                            "active": 113,
                            "lost": 4
                        }
                    }
                }
            }
        }
    }
}

Results format for reports without date splitting and with no segmentation levels

If no segmentation levels are specified, the results object will be a simple JSON object with up to 3 members - new, active, and lost, depending on what was requested in the clientStatus property in the request. The following is an example of a complete response:

{
    "status": "OK",
    "results": {
        "active": 1734,
        "new": 729,
        "lost": 387
    }
}