Metrics API (1.10.0)

Download OpenAPI specification:Download

Metrics API

What is the Metrics API?

The Metrics API is a data service offered by GameAnalytics. Read more about our other data service offerings here.

What is possible with the Metrics API?

The Metrics API enables you to programmatically query your games and fetch KPIs relevant for your studio. While it is possible to get game specific data from the GameAnalytics tool, the Metrics API provides new capabilities such as building BI dashboards to compare performance across games or specific user groups.

Metric data is aggregated by time and dimension. Metrics API supports most dimensions and event filters that are available in the GameAnalytics dashboards.

Metrics API use cases

Custom business intelligence reporting

The most popular use is creating bespoke BI reports & dashboards for an organization or game, to enable simple tracking of the metrics most relevant to the team. For instance, studios may track their global traffic, but also look in greater depth at a certain country or region. Others may look in greater detail at a certain metric - such as having reports that split user sessions by geo-location.

Health monitoring across titles

Reviewing every metric, for every game, every day can be time consuming. Getting access to key metrics like retention programmatically, and verifying that daily/weekly/monthly change is within certain parameters (e.g. +/- 10%), is the easiest way to monitor your portfolio for outliers, and to have the peace of mind that all your games are doing well at a given time.

Combining metrics across tools

When tools are fit for purpose, it makes sense to combine data to get the best overview. Want to see your retention and new users alongside CPI and app store ranking, for all your live titles? An in-house dashboard that combines data from our Metrics API with data from your attribution and ASO provider is likely to do the trick.

Get in touch with us to learn more about the Metrics API and different pricing options.

Data Availability

The data is available with a soft real-time guarantee, availability of which is checked once in an hour (e.g. the first request returns data in the latest available time interval, which is updated in an hour after the initial call). Metrics API gives the flexibility to query and retrieve the time when this data becomes available.

Integration

Metrics API provides users a way to get different data projections of the collected events across multiple games on an organization level.

Once the collected events have been processed, the service would be able to help to get a view on the games performance using a set of metrics such as ARPU, retention, session length, revenue and many others. The full list of currently supported metrics is available via metrics endpoint:

$ curl -H X-API-Key:<API KEY> https://metrics.gameanalytics.com/metrics/v1/metrics

[
    "arpu",
    "arppu",
    "conversion",
    "conversion_ft",
    "converting_users",
    "event_count",
    "installs_ratio",
    "new_users",
    "paying_users",
    "retention_retro",
    "returning_users",
    "revenue",
    "session_length",
    "session_unique",
    "user_unique",
    ...
]

Metrics

Each metric has a dedicated endpoint. For example /metrics/v1/metrics/arppu for ARPPU metric and /metrics/v1/metrics/session_length for session length.

To retrieve the metric the majority of the metrics endpoints accept a POST request with a payload that would look similar that what can be seen below:

{
  "interval": "2020-07-01/P1W",
  "granularity": "day",
  "query": {
    "type": "group",
    "dimension": "country_code",
    "limit": 100
  }
}

Where:

  • interval is ISO-8601 interval that defines the time range to run the query
  • granularity defines how the metric gets aggregated across the time dimension (e.g. by day, week or all where all datapoints gets aggregated into a single bucket).
  • query specifies a kind of a query along with its parameters to execute to retrieve the metric. The example above would return the top 100 countries of the requested metric.

Please read the specific metrics endpoint documentation to see all available parameters.

Query types

Generally each metric can be retrieved using one of the following query, type of which is specified via type field in the query object.

Group Query

Group query returns a sorted set of results for the values in the provided dimension according to the given criteria. One might think of a group query as a "GROUP BY" query where the result is aggregated by a single dimension. group queries would typically be faster than split queries.

The example below would return the top 3 countries with the highest ARPPU for 1st of August 2020:

{
  "interval": "2020-08-01/P1D",
  "granularity": "day",
  "query": {
    "type": "group",
    "dimension": "country_code",
    "limit": 3
  }
}

Result:

{
  "result": [
    {
      "result": [
        {
          "arppu": 896.64,
          "country_code": "GB",
          "paying_users": 1,
          "total_revenue": 89664
        },
        {
          "arppu": 4.16,
          "country_code": "US",
          "paying_users": 1,
          "total_revenue": 416
        },
        {
          "arppu": 2.99,
          "country_code": "CN",
          "paying_users": 2,
          "total_revenue": 598
        }
      ],
      "timestamp": "2020-08-01T00:00:00.000Z"
    }
  ]
}
Split Query

Split query returns a list of objects with the values aggregated by the 2 specified dimensions. Roughly speaking one might think of a split query as a group query where the result is aggregated by 2 dimensions.

To have a picture on ARPPU split by country and platform the following query might be used:

{
  "interval": "2020-09-01/P1D",
  "granularity": "day",
  "query": {
    "type": "split",
    "dimensions": [
      "country_code",
      "platform"
    ]
  }
}

Which returns a list of objects, aggregated by country and platform pairs for the time period specified in the query (1st of September 2020):

{
  "result": [
    {
      "event": {
        "arppu": 16273.37,
        "country_code": "US",
        "paying_users": 2,
        "platform": "android",
        "total_revenue": 3254674
      },
      "timestamp": "2020-09-01T00:00:00.000Z",
      "version": "v1"
    },
    {
      "event": {
        "arppu": 1302.8600000000001,
        "country_code": "US",
        "paying_users": 5,
        "platform": "ios",
        "total_revenue": 651430
      },
      "timestamp": "2020-09-01T00:00:00.000Z",
      "version": "v1"
    },
    {
      "event": {
        "arppu": 299.97,
        "country_code": "UZ",
        "paying_users": 1,
        "platform": "android",
        "total_revenue": 29997
      },
      "timestamp": "2020-09-01T00:00:00.000Z",
      "version": "v1"
    },
    {
      "event": {
        "arppu": 1206.86,
        "country_code": "YE",
        "paying_users": 1,
        "platform": "android",
        "total_revenue": 120686
      },
      "timestamp": "2020-09-01T00:00:00.000Z",
      "version": "v1"
    }
  ]
}
Timeseries Query

Timeseries queries returns a specified metric with no aggregation by any dimension. Each object is aggregated based on time dimension only.

The following example shows how to get average revenue per paying user for 3 days starting from 1st of August 2020:

{
  "interval": "2020-08-01/P3D",
  "granularity": "day",
  "query": {
    "type": "timeseries"
  }
}

The returned objects are bucketed with a granularity of a day and the metric is calculated based on time aggregation solely:

{
  "result": [
    {
      "result": {
        "arppu": 16.472987341772154,
        "paying_users": 3555,
        "total_revenue": 5856147
      },
      "timestamp": "2020-08-01T00:00:00.000Z"
    },
    {
      "result": {
        "arppu": 7.300213114754098,
        "paying_users": 3660,
        "total_revenue": 2671878
      },
      "timestamp": "2020-08-02T00:00:00.000Z"
    },
    {
      "result": {
        "arppu": 6.5728080229226356,
        "paying_users": 4188,
        "total_revenue": 2752692
      },
      "timestamp": "2020-08-03T00:00:00.000Z"
    }
  ]
}
Exceptions

There are some exceptions from the query types. Some of the metrics can't be retrieved with group query (e.g. conversion).

Typically this limitation is caused by the nature of the metric itself. Such metrics would imply aggregation per game.

Such metrics would usually provide a way to use group query (along with other query types) for a particular game. In the specification the query would have a Game prefix (e.g. GameConversionQuery):

{
  "game": "2923",
  "granularity": "day",
  "interval": "2020-08-01/P1W",
  "query": {
    "type": "group",
    "dimension": "country_code",
    "limit": 100
  }
}

Alternatively, if it's necessary to split the result by game, one might use by game query. Note that the query type won't be available for a client as the request implies aggregation by game. In the specification such query type would have a suffix ByGameQuery (e.g. ConversionByGameQuery):

{
  "interval": "2020-08-01/P1W",
  "granularity": "all",
  "split_by": "country_code"
}

Examples

The common flow of the generic use case should follow the next steps:

  1. Make sure that the interval is available to query (check data availability).
  2. Understand what metrics are available via the API.
  3. Get an idea of the what query type to use and possible filters to get the best result.
  4. Complete the result with information about games and studios in the response.

Check data availability

Using the interval endpoint, check if the data for the interval of interest is available to query:

$ curl -HX-API-Key:<API KEY> https://metrics.gameanalytics.com/metrics/v1/interval

Service should return the time boundaries of the data available to query:

"2020-06-14T00:00:00.000Z/2020-09-14T00:00:00.000Z"

If the data is not within the time boundaries, you might need to wait until it gets processed by the backend.

Explore the data

Supported dimensions

Using the dimensions endpoint get an idea of what dimensions the metrics can be aggregated on:

$ curl -HX-API-Key:<API KEY> https://metrics.gameanalytics.com/metrics/v1/dimensions

Service always returns the latest version of the supported list of dimensions. Example:

[
  "game_id",
  "country_code",
  "platform",
  "is_paying",
  "is_converting",
  // ...
]
Dimensions values

To get an idea of all possible dimension values submitted in a given time interval by games. This might be necessary if the query has to be refined to get the precise metrics result in a specific set.

Using dimension values endpoint list the values submitted in the provided time interval:

$ curl -HX-API-Key:<API KEY> 'https://metrics.gameanalytics.com/metrics/v1/dimensions/platform?interval=2020-08-01/P1M'
{
  "dimension": "platform",
  "values": [
    "android",
    "windows"
  ]
}

Available games

It might be handy to have a view on a performance of a set of games under a specific studio.

If there are plenty of games and studios, it might be necessary to limit the list of games to certain studios that have any data sent in the given interval:

$ curl -HX-API-Key:<API KEY> 'https://metrics.gameanalytics.com/metrics/v1/studios?interval=2020-08-01/P1M'

[
  {
    "id": "238393",
    "name": "Manc Ave"
  },
  // ...
]

Having the studio id the service then could be asked for all the games which submitted any events in the given interval:

$ curl -HX-API-Key:<API KEY> 'https://metrics.gameanalytics.com/metrics/v1/games?interval=2020-08-01/P1M&studios=238393'

[
  {
    "id": "3833679",
    "title": "Frontnite"
  },
  {
    "id": "83858202",
    "title": "Pups vs Dragons"
  },
  // ...
]

The game ids are then could be used to either limit metrics to refine the search or to complete the metrics result by looking up the titles of the games from the response.

Get the metric

Once you know the metric that is in your interest get the value using flexible filtering and aggregation based on time and dimensions:

cat <<EOF |
{
  "interval": "2020-08-01/P5D",
  "granularity": "all",
  "filter": {
    "or": [
      {"game_id": "3833679"},
      {"platform": "windows"}
    ]
  },
  "query": {
    "type": "split",
    "dimensions": [
      "game_id",
      "platform"
    ]
  }
}
EOF
curl -X POST                         \
 -H "Content-Type: application/json" \
 -H "Accept: application/json"       \
 -H "X-API-Key: <API KEY>"           \
 --data-binary @-                    \
 https://metrics.gameanalytics.com/metrics/v1/metrics/new_users

Which in this example would get the number of new users for the period of 5 days from 1st of August 2020 for all games on windows platform and for any platform for the game with id "83689":

{
  "result": [
    {
      "event": {
        "game_id": "83689",
        "new_users": 3449361,
        "platform": "android"
      },
      "timestamp": "2020-08-01T00:00:00.000Z",
      "version": "v1"
    },
    {
      "event": {
        "game_id": "83689",
        "new_users": 576973,
        "platform": "windows"
      },
      "timestamp": "2020-08-01T00:00:00.000Z",
      "version": "v1"
    },
    {
      "event": {
        "game_id": "29284",
        "new_users": 1,
        "platform": "windows"
      },
      "timestamp": "2020-08-01T00:00:00.000Z",
      "version": "v1"
    }
  ]
}

Use cases

List highest-grossing games in a country

If a country code that one has interest in is known (GB in this example), then it's easy to get the top 3 of the game with the highest revenue for 1st of August using the flowing query:

cat <<EOF |
{
  "interval": "2020-08-01/P1D",
  "granularity": "day",
  "filter": {
    "country_code": "GB"
  },
  "query": {
    "type": "group",
    "dimension": "game_id",
    "limit": 5
  }
}
EOF
curl -X POST                         \
 -H "Content-Type: application/json" \
 -H "Accept: application/json"       \
 -H "X-API-Key: <API KEY>"           \
 --data-binary @-                    \
 https://metrics.gameanalytics.com/metrics/v1/metrics/revenue

The result would be compri