How to migrate to the new API for Analytics?

From March 2020 until mid 2021, we’ll be replacing Analytics (classic) with Analytics (new). The switch will result in changing API. Around September 2020, we’ll remove an old API from our product for cloud customers. LTS customers may expect this change after they upgrade to the latest version of our product.

We recommend clients who use Analytics (classic) API to migrate to the new version as soon as possible. If you need help with the migration, contact our support and our technical team will assist you.

In this article, we’ll show you the major changes that will apply.

New authentication

The Analytics (new) API uses OAuth authentication. The authentication method used in the classic version, based on a token_auth parameter, will not work for the new API. Learn more about OAuth authentication in our technical documentation.

Websites, apps and meta sites

Websites, apps, and meta sites are identified in the new API with an ID (also called UUID).

To find the ID for the website, app or meta site, follow these steps:

1. Go to Menu > Administration. 
2. Navigate to Websites & apps or Meta sites.
3. On the left, select the website, app or meta site for which you want to find an ID.
4. The ID is under the name of your website, app or meta site.
   

   

Report requests

In the new API, unlike in the classic version, there is a single endpoint used for executing reporting queries. Each report request contains the entire report definition, without any references to objects created via UI. Therefore, you don’t need to create any report or segments beforehand.

Here’s the list of elements that each API request has:

• Website, app or meta site ID (UUID)
• Date range (absolute or relative)
• Columns that should be returned (dimensions and metrics)
• Filters that should be applied to the query (both dimension and metric filters are supported)
• Other options (data format, pagination, ordering)

To see the API request structure, read our technical documentation.

Raw data requests

When you request raw sessions, data is returned as a flat list. You can select any session-level dimension (event-level dimensions are not available in this request). Let’s see an example.

{
  "data": [
    {
      "session_id": "2132573",
      "visitor_id": "1f9ea85fc03837c8",
      "timestamp": "2018-12-03T00:01:48"
    },
    {
      "session_id": "2132575",
      "visitor_id": "7d1363eadd95b7ef",
      "timestamp": "2018-12-03T00:06:32"
    }
  ],
  "meta": {
    "columns": [
      "session_id",
      "timestamp",
      "visitor_id"
    ],
    "count": 42
  }
}

When you request raw events, data is also returned as a flat list. You can select any session-level or event-level dimension. Let’s see an example.

{
  "data": [
    {
      "session_id": "2132565",
      "event_id": "8131573",
      "visitor_id": "bb452cbba002a8e2",
      "timestamp": "2018-12-03T00:05:53"
    },
    {
      "session_id": "2132573",
      "event_id": "8131571",
      "visitor_id": "1f9ea85fc03837c8",
      "timestamp": "2018-12-03T00:01:48"
    }
  ],
  "meta": {
    "columns": [
      "event_id",
      "session_id",
      "timestamp",
      "visitor_id"
    ],
    "count": 17444
  }
}

To see the structure of raw data API requests, read our technical documentation.

Data formats

The new API has four data formats (file types): JSON, JSON-VS, CSV, and XML.

JSON: A format optimized for a response size. It’s recommended for server-to-server integrations or requesting a large amount of data.

{
  "data": [
    [
      [
        "IE",
        "Internet Explorer"
      ],
      "11.0",
      165447,
      45080
    ]
  ],
  "meta": {
    "columns": [
      "browser_name",
      "browser_version",
      "events",
      "sessions"
    ],
    "count": 1577
  }
}

JSON-KV: A format recommended for integrations with BI tools that expect a key-value structure.

{
  "data": [
    {
      "browser_name__label": "Internet Explorer",
      "browser_name__id": "IE",
      "browser_version": "11.0",
      "events": 165447,
      "sessions": 45080
    }
  ],
  "meta": {
    "columns": [
      "browser_name__id",
      "browser_name__label",
      "browser_version",
      "events",
      "sessions"
    ],
    "count": 1577
  }
}

CSV

browser_name__label,browser_name__id,browser_version,events,sessions
Internet Explorer,IE,11.0,165447,45080

XML

<?xml version="1.0" encoding="UTF-8" ?>
<result>
  <row>
    <browser_name__label>Internet Explorer</browser_name__label>
    <browser_name__id>IE</browser_name__id>
    <browser_version>11.0</browser_version>
    <events>165447</events>
    <sessions>45080</sessions>
  </row>
</result>

Metric mapping

The names of the metrics used in Analytics (new) are different from the ones used in Analytics (classic). If you are migrating to the new version, use our metric mapping table. The table contains metrics used in Analytics (classic) and corresponding metric names in Analytics (new).

For a full list of metrics, dimensions, and their available transformations, read our technical documentation.