Documentation

Reporting API V2

Our reporting API offers aggregated data, matching the capabilities of our Dashboard: you can select multiple dimensions and metrics, add filters, and report by different time zones.

For detailed API reference and code snippets, please see our API Reference

Authentication

The API Key is available in your account details (by clicking on your email in the top menu). You can authenticate requests by a header X-API-KEY with the value being your API key.

Endpoints

We offer two endpoints for our reporting api.

/api/v2/reporting/account

Endpoint for account specific reports. Pagination is enforced on this endpoint and so a large report will likely require multiple requests. See our API reference here: <https://docs.adaptmx.com/reference/getapiv2reportingaccount>

/api/v2/reporting/async

Asynchronous endpoint for reports. This is preferred if you want to request a single large report. View our API reference here: <https://docs.adaptmx.com/reference/getapiv2reportingasync>

The key steps when calling the async endpoint are the following:

  1. Initiate the async report request by sending a GET request with your report parameters as the query string to https://dash-api.appmonet.com/api/v2/reporting/async
  2. A 202 response will be returned with a Retry-After header with a value indicating how many seconds to wait until repeating the same original GET request.
  3. On retry the response will either be the same 202 response if the report is not yet ready or a 303 redirect response. This response will contain the download link in the Location header if the report is ready to be downloaded.

The below Python script provides an example on how to implement calling our async reporting endpoint.

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
from datetime import datetime, timedelta
import urllib.parse

# by default Retry-After is only respected for 429 & 503 status codes
retries = Retry(total=999, backoff_factor=1, respect_retry_after_header=True, status_forcelist=[202])
adapter = HTTPAdapter(max_retries=retries)

session = requests.Session()
session.headers.update({
    'x-api-key': 'TOKEN',
    'accept': 'application/json, text/plain, */*'
})
session.mount('https://', adapter)

yesterday = (datetime.now() - timedelta(1)).strftime('%Y-%m-%d')
day_before_yesterday = (datetime.now() - timedelta(2)).strftime('%Y-%m-%d')

query = {
  'dimensions[]': 'hourly',
  'metrics[]': 'impressions',
  'metrics[]': 'revenue',
  'tz': 'UTC',
  'sort_by': 'hourly',
  'sort_dir': 'desc',
  'start_date': day_before_yesterday,
  'end_date': yesterday
}
encoded_query = urllib.parse.urlencode(query, doseq=True)

url = "https://dash-api.appmonet.com/api/v2/reporting/async?" + encoded_query

print(f"Executing query with parameters: {query}")

response = session.get(url)

if response.status_code != 200:
  print(f"Request failed with status code {response.status_code}: {response.text}")
  exit(1)

filename = response.url.split("?")[0].split("/")[-1]

print(f"Fetching data for report: {filename}")

with open(filename, "wb") as file:
    for chunk in response.iter_content(chunk_size=8192):
        file.write(chunk)

print(f"Downloaded file: {filename}")

Migrating from V1 to V2

Our V2 API is largely the same as V1, except for a few key differences:

  • The API Key is now provided as a HTTP header: X-API-Key
  • If you were using the path api/v1/hourly-member-reports/account_reports.json you will now need to change to one of the two options listed above.
  • Pagination is enforced on the /api/v2/reporting/account endpoint. Which means you will likely have to send multiple requests in order to receive the entire report is you are requesting a large amount of data.
  • Alternatively the /api/v2/reporting/async endpoint allows you to request an entire report at once. However it is done asynchronously and will require a second request to retrieve the report once it is completed.

Updated 10 months ago