Endpoints

The Polaris Reporting API endpoints are:

• https://inc-metrics.prod.api.metric.works/token - Obtain security token for authentication
• https://inc-metrics.prod.api.metric.works/query - Submit a query to obtain reporting data

Limits

The API has the following limits:

Authentication

All requests to the Reporting API's query endpoint must specify a security token obtained from the token endpoint. To obtain a security token, POST a request containing the following JSON body:

{ "username": "my.email@company.com", "password": "mypassword" }

Replace the username and password placeholder values above (my.email@company.com and mypassword) with your actual Polaris username (which is your email address) and password.

If successful, the response will be a text security token that must be specified in your query requests as a Bearer token in the Authorization header like the following:

Authorization: Bearer [security token]

Replace the [security token] placeholder in the header example above with the security token. Security tokens are valid for 1 hour from the time they are obtained from the token endpoint. Specifying an expired security token will result in a 401 Unauthorized response from the query endpoint.

Querying

To query reporting data from the Reporting API, POST a request containing one or more of the following properties:

-01-01``` 

-01-31``` 

["CHANNEL", "COUNTRY"]``` 

Group By

The table below describes the dimensions that can be used as valid values in the groupBy property. The group by can be thought of as the granularity of the returned results.

Metrics

Each metric object listed in the metrics property must specify the following properties.

``` 

``` 

``` 

The table below describes the metric types that can be used as valid values in the type property of the each metric object. Metric types prefixed by INC_ are incrementality metrics; others are last touch.

Metrics Example

[
  {
    "type": "INC_NEW_USERS",
    "interval": true
  },
  {
    "type": "NEW_USERS"
  },
  {
    "type": "INC_ROAS",
    "day": 3,
    "interval": false
  },
  {
    "type": "ROAS",
    "day": 3
  }
]

Filters

Each filter object listed in the filters property must specify the following properties.

``` 

["Facebook"]``` 

``` 

Filters Example

[
  {
    "type": "CHANNEL",
    "values": ["Facebook"],
    "not": false
  }
]

Order By

Each order by object listed in the orderBy property must specify the following properties.

``` 

``` 

Order By Example

[
  {
    "type": "CHANNEL",
    "descending": false
  }
]

Code Sample

The following is a code sample written in Python. It implements no fault tolerance, error handling, or throttling, but should provide an idea of the basics.

import requests

token_endpoint = "https://inc-metrics.prod.api.metric.works/token"
query_endpoint = "https://inc-metrics.prod.api.metric.works/query"

username = "username"
password = "password"

credentials = {
    "username": username,
    "password": password
}

query = {
    "groupBy": [
        "CHANNEL"
    ],
    "metrics": [
        {
            "type": "INC_NEW_USERS",
            "interval": True
        }
    ],
    "filters": [
        {
            "type": "APP",
            "values": ["App Name (iOS)"]
        }
    ],
    "order": [],
    "startDate": "2022-06-01",
    "endDate": "2022-06-01"
}

token_response = requests.request("POST", token_endpoint, json=credentials)

headers = {'Authorization': 'Bearer ' + token_response.text}

query_response = requests.request("POST", query_endpoint, headers=headers, json=query)

print(query_response.text)

Updated on: 31/10/2024