Reporting API V1

Important update February 2025

The reporting API V1 is going to be deprecated and no longer available from June 1st 2025.

Users will need to transition to the V2 of the API instead. Our V2 API is largely the same as V1, except for a few key differences:

1. The API Key is now provided as a HTTP header: X-API-Key
2. If you were using the path api/v1/hourly-member-reports/account_reports.json you will now need to change to one of two new options for querying data.
   1. /api/v2/reporting/account- Pagination is enforced on this 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.
   2. /api/v2/reporting/async- Alternatively this 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.

You can see more detailed documentation here.

Authentication

The API Key (api_key) is available in your account details (by clicking on your email in the top menu). You can authenticate requests by adding the query parameter api_key.

API

Endpoint

https://reporting.adaptmx.com/api/v1/hourly-member-reports/account_reports.json

This endpoint provides data for all sites in your account.

Requests

• The api_key is required
• Make a GET request
• All parameters should be URI-encoded

Parameters

Metrics

The metrics can be used to retrieve specific data points. These should be provided as a comma-separated list to the metrics parameter.

Dimensions

The following dimensions can be used to group results. They should be provided as a comma-separated list for the dimensions parameter.

📘

Domain & Operating System

The domain and operating_system dimensions are currently only available to publishers using a Run-Of-Network tagId. Please contact your account manager for more information on enabling these dimensions for your account.

For other accounts, a domain/site breakdown is available from the "applications_name" dimension.

Filters

We support filters on certain fields:

• country_code
• adunit_identifier (aka "adunit_id")
• creative_type

Filters should be passed filter[FILTER_NAME]=FILTER_VALUE, e.g:

https://reporting.adaptmx.com/api/v1/hourly-member-reports/account_reports.json?filter[country_code]=us

In some languages/libraries, this can be represented as a nested map:

require 'httparty'

today = Date.now.strftime('%Y-%m-%d')

data = HTTParty.get(
  'https://reporting.adaptmx.com/api/v1/hourly-member-reports/account_reports.json',
  query: {
    api_key: 'YOUR_API_KEY',
    start_date: today,
    end_date: today,
    filter: {
      country_code: "us"
    },
    dimensions: 'hour,adunit_id',
    metrics: 'impressions,revenue'
    tz: 'America/New_York'
  })

Example Request and Response

Request

Valid API requests are GET requests with the API key passed as api_key. Note that parameters must be url-encoded.

This example shows how to request a report for today's data, grouped by hour and ad unit:

today=$(date +%Y-%m-%d)
curl -G --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode 'dimensions=adunit_id,hour' \
  --data-urlencode "start_date=$today" \
  --data-urlencode "end_date=$today" \
  --data-urlencode 'metrics=revenue,impressions' \
  --data-urlencode 'tz=America/New_York' \
  'https://reporting.adaptmx.com/api/v1/hourly-member-reports/account_reports.json' |\
  jq '.[] | "\(.hour),\(.adunit_id),$\(.revenue)"'

from datetime import date
import requests

today = date.today().strftime("%Y-%m-%d")

payload = {
  'api_key': 'YOUR_API_KEY',
  'dimensions': 'adunit_id,hour',
  'metrics': 'revenue',
  'start_date': today,
  'end_date': today,
  'tz': 'America/New_York'
}

response = requests.get(
  'https://reporting.adaptmx.com/api/v1/hourly-member-reports/account_reports.json',
  params=payload)

for row in response.json():
  print("{hour},{adunit_id},${revenue}".format(**row))

require 'httparty'

today = Date.now.strftime('%Y-%m-%d')

data = HTTParty.get(
  'https://reporting.adaptmx.com/api/v1/hourly-member-reports/account_reports.json',
  query: {
    api_key: 'YOUR_API_KEY',
    start_date: today,
    end_date: today,
    dimensions: 'hour,adunit_id',
    metrics: 'impressions,revenue'
    tz: 'America/New_York'
  })

data.parsed_response.each do |row|
  puts "#{row['hour']},#{row['adunit_id']},$#{row['revenue']}"
end

Response

Responses will be an array of objects:

[{ 
 date: '2021-06-30',
 adunit_id: 'my-adunit-id',
 impressions: 1000,
 revenue: 1.22,
}, {
 date: '2021-06-30',
 adunit_id: 'my-adunit-2',
 impressions: 1211,
 revenue: 1.40,
}]