Introduction

Welcome to the NextMillennium Reporting API. The methods below will allow you to query reporting data.

Authentication

An example of using token for authentication:

curl "https://pp2-api.nextmillennium.io/api/public/..." \
  -H "Authorization: Bearer <token>"

const response = await fetch("https://pp2-api.nextmillennium.io/api/public/...", {
    headers: {
        "Authorization": `Bearer ${<token>}`
    }
})

Make sure to replace <token> with your personal API key.

Our API uses tokens for managing access to its endpoints. The token should be included as a Bearer authorization header in each request.

You can obtain token by contacting your account manager.

Reporting

Dimensions and Metrics

Core Dimensions:

Additional Dimensions (Choose One):

Metrics:

Using Metrics with Dimensions:

• Users can call any combination of the core dimensions (date, site, and placement) along with one additional dimension.
• Metrics can be applied to the specified dimensions to gain insights into ad performance and revenue generation.
• Example API Request: Retrieve adImpressions and revenue for a specific site on a particular date with the additional dimension of country.

Campaign Type Limitations

For Standard NM Campaigns (isDirectCampaign: false or not present in request body)

• Users can call any combination of core dimensions along with one additional dimension.
• Metrics like adRequests, adOpportunities, adImpressions, revenue, and eCPM are available.

For Direct Campaigns (isDirectCampaign: true)

• browser and referrerCategory (Traffic Source) dimensions are not accessible due to system limitations.
• adRequests and adOpportunities metrics are not accessible due to system limitations.
• On top of the available adImpressions, revenue and eCPM you can use additional metrics for Direct Campaigns:

For additional info use Fields method

Query Reports

curl --request POST 'https://pp2-api.nextmillennium.io/api/public/reports/query' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from": "2024-01-01",
    "to": "2024-01-01",
    "dimensions": [
        "date"
    ],
    "metrics": [
        "revenue"
    ]
}'

const response = await fetch("https://pp2-api.nextmillennium.io/api/public/reports/query", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        from: "2024-01-01",
        to: "2024-01-01",
        dimensions: [ 
            "date"
        ],
        metrics: [
            "revenue"
        ]
    })
})

The above request returns the following JSON response:

{
    "data": [
        {
            "date": "2024-01-01",
            "revenue": 100
        }
    ],
    "total": 1
}

This endpoint allows you to query reports. That includes grouping, filtering and sorting.

HTTP Request

POST https://pp2-api.nextmillennium.io/api/public/reports/query

Body Parameters

Response Format

If everything is okay you will receive the next response:

{
  "data": [],
  "total": 0
}

In case of error the response will have the following format:

{
  "error": {
    "message": ""
  }
}

The response body contains only two fields:

• data - requested report
• total - the total number of rows in the report. Usually used to calculate the number of pages with the selected limit

Filtering

Example of a filter

curl --request POST 'https://pp2-api.nextmillennium.io/api/public/reports/query' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from": "2024-01-01",
    "to": "2024-01-01",
    "dimensions": [
        "placement"
    ],
    "metrics": [
        "revenue"
    ],
    "filters": [
        {
            "dimension": "placement",
            "operation": "in",
            "value": [
                "placement_gunstar"
            ]
        }
    ]
}'

const response = await fetch("https://pp2-api.nextmillennium.io/api/public/reports/query", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        from: "2024-01-01",
        to: "2024-01-01",
        dimensions: [
            "placement"
        ],
        metrics: [
            "revenue"
        ],
        filters: [
            {
                dimension: "placement",
                operation: "in",
                value: [
                    "placement_gunstar"
                ]
            }
        ]
    })
})

Filters field is an array of objects describing logical statements. All elements of the array are concatenated using AND operator. The fields of a filter object are:

• dimension - identifier of dimension to which we need to apply the filter;
• operation - optional identifier of the filtering operation. Possible values are "in" and "not_in". All filters are considered IN filters by default;
• value - an array of string values to filter by.

Filtering is only available for the requested dimensions

Ordering and Pagination

Using the following code you can query the third page with of the report ordered by revenue with a page size equal to 10

curl --request POST 'https://pp2-api.nextmillennium.io/api/public/reports/query' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from": "2024-01-01",
    "to": "2024-01-01",
    "dimensions": [
        "placement"
    ],
    "metrics": [
        "revenue"
    ],
    "order": [
        {
            "by": "revenue",
            "direction": "desc"
        }
    ],
    "limit": 10,
    "offset": 20
}'

const response = await fetch("https://pp2-api.nextmillennium.io/api/public/reports/query", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        from: "2024-01-01",
        to: "2024-01-01",
        dimensions: [
            "placement"
        ],
        metrics: [
            "revenue"
        ],
        order: [
            {
                by: "revenue",
                direction: "desc"
            }
        ],
        limit: 10,
        offset: 20
    })
})

You can define a list of order statements to format reports. Ordering object contains two fields

• by - identifier of a dimension or a metric
• direction - identifier of the ordering direction. Available values are "asc" and "desc". This field has no default value

Statements will be applied in the same order they appear in the array.

By using the "limit" and "offset" fields you can either establish a pagination logic (use a consistent ordering; "limit" will be your page size and "offset" will help you to change the pages) or limit expected output. Note that you cannot use "offset" without a "limit".

List Available Fields

The following API method provides users with a comprehensive list of available dimensions and metrics. It's essential to note that users may have different dimensions and metrics accessible to them based on system limitations.

curl "https://pp2-api.nextmillennium.io/api/public/reports/fields"

const response = await fetch("https://pp2-api.nextmillennium.io/api/public/reports/fields")

HTTP Request

GET https://pp2-api.nextmillennium.io/api/public/reports/fields

Response Format

{
    "dimensions": [
        {
            "id": "date",
            "name": "Date",
            "description": "Reporting day. Has format of an ISO 8601 date. Timezone is EST/EDT."
        }
    ],
    "metrics": [
        {
            "id": "revenue",
            "name": "Revenue",
            "description": "Net Publisher revenue in United States Dollars ($)"
        }
    ]
}

Each object in the response body has three fields:

• id - identifier of the metric or dimension
• name - human-readable name of the metric/dimension
• description - human-readable explanation of the metric/dimension meaning

Errors

You might face the following response codes during the interaction with our API: