Reporting API

The u-Slicer API allows you query all of your media trading activity to better understand your The MediaGrid integration. The API methods accept and return serialized data in YAML, XML, or JSON.

  • YAML: This format is used by default. Accept/Content-Type: text/x-yaml

  • XML: is obtained by providing appropriate value in HTTP header, Accept/Content-Type: text/xml

  • JSON: is obtained by providing appropriate value in HTTP header, Accept/Content-Type: application/json

Access Tokens

To access the API, you need an IPONWEB uAuth account. This is created for you when you get an IPONWEB account. If you do not have one, contact your account manager. Once you have uAuth access, you can generate an API token which you can use with your u-Slicer queries.

Permanent Token

You can create long-lived access tokens, which you can revoke from the UI at any time.

  1. Log into https://uauth.iponweb.com/uauth/settings/

  2. Click Create New Token

  3. In the scope field, enter uslicer.iponweb.com

  4. Save your token, as this will be required for all of your API queries

Temporary Token

You can also create short-lived tokens for each new session. To do this use the following steps.

  1. Make a post request, which includes the following details to https://uauth.iponweb.com/oauth2/token/

    • grant_type=password

    • scope=service_id=uslicer.iponweb.com

    • username=<USERNAME> Your IPONWEB LDAP login

    • password=<PASSWORD> Your IPONWEB LDAP password

  2. Use the returned access_token in your requests to u-Slicer

# Example temp token post request
curl https://uauth.iponweb.com/oauth2/token/ \
  --request POST \
  --data "grant_type=password" \
  --data "username=<username>" \
  --data "password=<password>" \
  --data "scope=service_id=uslicer.iponweb.com"

Querying the API

To query u-Slicer and get data, you need to post your query to the relevant endpoint. Each endpoint maps to an API method, which returns or processes data based on what you pass in the request body. Some endpoints merely return data, and others return a subset of all possible data based on the post request details.

  • For all requests, you must pass the Always Required Fields. For some endpoints, these are all you need to pass.

  • For others you will need to pass additional required or optional fields to get the data you want. You can get the complete details for each of the endpoints listed in the All u-Slicer Endpoints table

Always Required Fields

The following fields are required for all post requests to your u-Slicer endpoint.

u-Slicer Required Fields

Field

Description

slicer_name

The name of your u-Slicer instance, each customer has their own so please ask your account manager to send it to you.

project_name

The name of the project, each customer has their own so please ask your account manager to send it to you.

token

Your authorisation token, see Access Tokens

Example INFO Endpoint

This example query will return all of the fields available to you, and uses the endpoint outlined in the Info Endpoint section.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import requests
import json

token = "" # https://uauth.iponweb.com/uauth/settings/ use scope uslicer.iponweb.com
slicer = "https://uslicer.iponweb.com/API/v2/info"

payload = {
    "slicer_name": "", # ask your account manager
    "project_name": "", # ask your account manager
    "token": token,
}

get_info = requests.post(slicer, json=payload)
raw = get_info.json()
print(json.dumps(raw, sort_keys=True, indent=4))

All u-Slicer Endpoints

<!-- Base URL; POST your request to query data based on each method's fields -->
https://uslicer.iponweb.com/API/v2/<endpoint>
u-Slicer Methods

Endpoint

Description

audience

Returns audience data restricted by query parameters passed in POST arguments, see Audience Endpoint

export

Exports report data to a file of the xls, csv, tsv or tsv2 format. Data is restricted by query parameters passed in POST arguments Export Endpoint

info

Provides information about a particular slicer. This information includes the list of available key and data fields, as well as their descriptions. See example Info Endpoint

query

Returns report data restricted by query parameters passed in POST arguments see Query Endpoint

time_series

Returns time series data restricted by query parameters passed in POST arguments see Time Series Endpoint