Skip to main content

Setup

This section will guide you on how to set up the Metrics API, and how to construct some basic queries.

Authentication​

To start setting up the Metrics API, first you need to generate an API key from the GameAnalytics dashboard, Organization settings page.

Overview

Once you've generated the key, you can use it for any requests, for example, in Postman, or from the command console.

GET /metrics/v1/dimensions HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: close
Host: metrics.gameanalytics.com
User-Agent: HTTPie/2.1.0
X-API-Key: ek5KV6aMSl87QAFGGFAQ78lSMa6VK5ke

Querying metrics​

Endpoints​

Each metric has it's own dedicated endpoint:

  • ARPPU: /metrics/v1/metrics/arrpu
  • Session Length: /metrics/v1/metrics/session_length

Basic Query Structure​

For example, we can use the following query:

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

Field descriptions​

  • interval: The time range for your query, specified in ISO-8601 format (e.g., 2025-07-01/P1W means one week starting from July 1st 2025)
  • granularity: defines how the data is aggregated over time. Options include day, week, and all (which aggregates everything into a single value)
  • query: Describes how to group and return the results. The structure depends on the query type.

For a complete list of parameters available for a specific metric, see the endpoint's documentation.

Query types​

Each metric can be queried using one of the following types, set in json**query.type**.

Group query​

A group query aggregates results by a single dimension (e.g., country, platform). It's similar to a SQL GROUP BY clause and is typically faster than a split query.

Example: Top 3 countries by ARPPU on July 1st, 2025

Request:

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

Response:

{
  "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": "2025-07-01T00:00:00.000Z"
    }
  ]
}

Split query​

A split query groups results by two dimensions. Think of it as grouping by both country_code and platform, for instance.

Example: ARPPU split by country and platform on July 1st, 2025

Request:

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

Response:

{
  "result": [
    {
      "event": {
        "arppu": 16273.37,
        "country_code": "US",
        "platform": "android",
        "paying_users": 2,
        "total_revenue": 3254674
      },
      "timestamp": "2025-07-01T00:00:00.000Z"
    },
    {
      "event": {
        "arppu": 1302.86,
        "country_code": "US",
        "platform": "ios",
        "paying_users": 5,
        "total_revenue": 651430
      },
      "timestamp": "2025-07-01T00:00:00.000Z"
    }
    // ...
  ]
}

Timeseries query​

A timeseries query returns metrics over time without grouping by any dimensions. It's useful for trend analysis.

Example: ARPPU over 3 days from July 1st 2025

Request:

{
  "interval": "2025-07-01/P3D",
  "granularity": "day",
  "query": {
    "type": "timeseries"
  }
}

Response:

{
  "result": [
    {
      "result": {
        "arppu": 16.47,
        "paying_users": 3555,
        "total_revenue": 5856147
      },
      "timestamp": "2025-07-01T00:00:00.000Z"
    },
    {
      "result": {
        "arppu": 7.30,
        "paying_users": 3660,
        "total_revenue": 2671878
      },
      "timestamp": "2025-07-02T00:00:00.000Z"
    }
    // ...
  ]
}

Special cases and exceptions​

Some metrics (e.g., conversion) can’t be queried using all query types due to the nature of how they're calculated—usually requiring game-level aggregation.

Example 1: Group query with specified time

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

Example 2: Aggregated split by game (not using query.type)

Some queries imply an internal grouping by game. These use split_by outside the query object:

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

In documentation, these types are usually referred to with special query names like GameConversionQuery or ConversionByGameQuery.

info

See more request examples here