OpenX Data Service (1.1.0)

Copyright © 2021 OpenX. All rights reserved.


Overview

The OpenX Data Service API is a reporting service which allows you to access your data including revenue numbers and impressions. You can make request to the API endpoints at a regular basis to get data on how your business is going to store the data on your side and manipulate it to generate reports.


Requirements

Prior to start using the OpenX Data Service API, you require the following:

  • consumer_key
  • consumer_secret
  • email
  • password

If you need one of the items mentioned above, please contact us on the OpenX Community.


Authenticating

To authenticate, install one of the following clients:


Obtaining an Access Token

Once authenticated, use the following code to receive a token:

email = 'you@example.com'
password = 'password123'
domain = 'uidomain.com'
realm = 'uidomain_realm'
consumer_key = '1fc5c9ae...'
consumer_secret = '7c664d68...'

To get your access token, use ox_client = ox.logon(email, password). Your value for openx3_access_token is ox_client._token.

ox = ox3apiclient.Client(
email=email,
password=password,
domain=domain,
realm=realm,
consumer_key=consumer_key,
consumer_secret=consumer_secret)


Finding Fields

OpenX Data Service contains 100+ fields allowing you to pick and chose the values that are important to you. To aid with finding fields that are relevant to your business, all fields are associated to a path which are natural business groups of attributes and metrics.

The paths are depicted in the diagrams below in a hierarchy and can be a helpful reference when searching through the get /fields call.

Dimensions Data Stream

Metrics Data Stream


Helpful Notes

Consider the following:

  • Bid level fields are not currently available.
  • Reports are currently only available in UTC.
  • Data is returned in JSON format.

For any questions about these features, please contact api_migration@openx.com.


FAQ

For a list of FAQs, consult the Reporting API FAQ on the OpenX Community.


Schemas

The OpenX Data Service schemas are described below.

For endpoints, please see Endpoints.


base_attribute

{
  "id": "string",
  "description": "string"
}

 

Properties

Name
Type
Required Restrictions Description
id string true none The unique id of the attribute.
description string false none Short description explaining the field.

dimension

{
  "id": "string",
  "path": "string"
}

 

Properties

Name
Type
Required Restrictions Description
id string false none none
path string false none none

dimensions_available

[
  {
    "id": "string",
    "path": "string"
  }
]

 

Properties

Name
Type
Required Restrictions Description
anonymous dimension false none none

error_object

{
  "code": "string",
  "message": "string",
  "traceId": "string"
}

 

Properties

Name
Type
Required Restrictions Description
code string true none none
message string true none none
traceId string true none none

field_attribute_path

{
  "dimensionPaths": "string"
}

 

The path assigns a natural grouping of fields based on business uses. For example, CONTEXT is information about the served ad's environment; whether that be content or physical. PLACEMENTS are properties such as permitted features of the offered ad space while RESPONSE provides information on the winning advertisement. Please refer to IAB's AdCom Specifications for more details.

Properties

Name
Type
Required Restrictions Description
dimensionPaths string false none none

filter

{
  "name": "string",
  "value": [
    "string"
  ],
  "operator": "EQ"
}

 

Properties

Name
Type
Required Restrictions Description
name string false none none
value any false none none

oneOf

Name
Type
Required Restrictions Description
» anonymous [string] false none none

xor

Name
Type
Required Restrictions Description
» anonymous string false none none

continued

Name
Type
Required Restrictions Description
operator string false none none

Enumerated Values

Property Value
operator EQ

filter_expression

{
  "operator": "AND",
  "leftOperand": null,
  "rightOperand": null
}

 

Properties

Name
Type
Required Restrictions Description
operator string false none none
leftOperand any false none none

oneOf

Name
Type
Required Restrictions Description
» anonymous filter_expression false none none

xor

Name
Type
Required Restrictions Description
» anonymous filter false none none

continued

Name
Type
Required Restrictions Description
rightOperand any false none none

oneOf

Name
Type
Required Restrictions Description
» anonymous filter_expression false none none

xor

Name
Type
Required Restrictions Description
» anonymous filter false none none

Enumerated Values

Property Value
operator AND
operator OR
operator XOR

format

"Array[Number]"

 

Define standard type. For example: date, currency.

Properties

Name
Type
Required Restrictions Description
anonymous string false none Define standard type (date, currency).

Enumerated Values

Property Value
anonymous Array[Number]
anonymous Currency
anonymous Date
anonymous Number
anonymous String
anonymous Boolean

metadata_attribute

{
  "id": "string",
  "description": "string",
  "format": "Array[Number]",
  "example": "string"
}

 

The request object for the attribute.

Properties

allOf

Name
Type
Required Restrictions Description
anonymous base_attribute false none none

and

Name
Type
Required Restrictions Description
anonymous object false none none
» format format false none Define standard type (date, currency).
» example string false none An example of the value that could display for the field.

metadata_details

{
  "dimensionsAvailable": [
    {
      "id": "string",
      "path": "string"
    }
  ]
}

 

Properties

Name
Type
Required Restrictions Description
dimensionsAvailable dimensions_available false none none

metadata_metric

{
  "id": "string",
  "path": "string",
  "description": "string",
  "format": "Array[Number]",
  "example": "string",
  "metadataDetails": {
    "dimensionsAvailable": [
      {
        "id": "string",
        "path": {
          "dimensionPaths": "string"
        }
      }
    ]
  }
}

 

Properties

Name
Type
Required Restrictions Description
id string true none The unique id of the attribute.
path string false none The path assigns a natural grouping of fields based on business uses. For example, metrics that fall within the FUNNEL path represent the stages to the final potential resolution of impressions and spend. TRACKING metrics are related to post ad serving measurements such as clicks.
description string false none Short description explaining the field.
format format false none Define standard type (date, currency).
example string false none An example of the value that could display for the field.
metadataDetails object false none none
» dimensionsAvailable [any] false none List of dimensions that can be requested with the metric.
»» id string false none The unique id of the dimensions.
»» path field_attribute_path false none The path assigns a natural grouping of fields based on business uses. For example, CONTEXT is information about the served ad's environment; whether that be content or physical. PLACEMENTS are properties such as permitted features of the offered ad space while RESPONSE provides information on the winning advertisement. Please refer to IAB's AdCom Specifications for more details.

metadata_metrics

{
  "id": "string",
  "path": "string",
  "description": "string",
  "format": "string",
  "example": "string",
  "metadataDetails": {
    "dimensionsAvailable": [
      {
        "id": "string",
        "path": "string"
      }
    ]
  }
}

 

Properties

Name
Type
Required Restrictions Description
id string false none none
path string false none none
description string false none none
format string false none none
example string false none none
metadataDetails metadata_details false none none

metrics

{
  "metrics": [
    {
      "id": "string",
      "path": "string",
      "description": "string",
      "format": "string",
      "example": "string",
      "metadataDetails": {
        "dimensionsAvailable": [
          {
            "id": "string",
            "path": "string"
          }
        ]
      }
    }
  ],
  "dimensions": [
    {
      "id": "string",
      "path": "string"
    }
  ]
}

 

Properties

Name
Type
Required Restrictions Description
metrics [metadata_metrics] false none none
dimensions [dimension] false none none

report_request

{
  "startDate": "string",
  "endDate": "string",
  "reportFormat": "JSON",
  "acceptEncoding": "gzip, deflate",
  "attributes": [
    {
      "id": "string",
      "description": "string",
      "format": "Array[Number]",
      "example": "string"
    }
  ],
  "metrics": [
    {
      "id": "string",
      "path": "string",
      "description": "string",
      "format": "Array[Number]",
      "example": "string",
      "metadataDetails": {
        "dimensionsAvailable": [
          {
            "id": "string",
            "path": {
              "dimensionPaths": "string"
            }
          }
        ]
      }
    }
  ],
  "filters": {
    "operator": "AND",
    "leftOperand": null,
    "rightOperand": null,
  }
}

 

The call structure for running a report.

Properties

Name
Type
Required Restrictions Description
startDate string true none Start date for the data fetched in the report. startDate is inclusive in the query and hour is optional; denoted by :HH at the end of the YYYYMMDD.
endDate string true none End date is exclusive in the query. For example, to get one days of data, apply endDate = startDate + 1 day.
reportFormat string false none Format of the report requested by the user. Currently, only JSON is supported.
acceptEncoding string false none The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. Using content negotiation, the server selects one of the proposals, uses it and informs the client of its choice with the Content-Encoding response header. For more information, see Accept-Encoding.
attributes [metadata_attribute] false none List of attributes.
metrics [metadata_metric] false none List of metrics.
filters any false none Filter object or Filter Expressions

oneOf

Name
Type
Required Restrictions Description
» anonymous filter_expression false none none

xor

Name
Type
Required Restrictions Description
» anonymous filter false none none

Enumerated Values

Property Value
reportFormat JSON
acceptEncoding gzip, deflate
acceptEncoding gzip
acceptEncoding deflate

report_response

{
  "reportData": [
    {
      "property1": "string",
      "property2": "string"
    }
  ],
  "reportMetadata": {
    "reportCreated": "string"
  }
}

 

Properties

Name
Type
Required Restrictions Description
reportData [object] false none Data returned after the report execution. The data will be an array of objects. Each Object will have key value pair with keys as attribute or metric name and their value.
» additionalProperties string false none none
reportMetadata object false none The metadata information about the generated report.
» reportCreated string false none Report creation time.

dateRange_request

{
  "attributes": [
    {
      "id": "string",
      "description": "string",
      "format": "Array[Number]",
      "example": "string"
    }
  ],
  "metrics": [
    {
      "id": "string",
      "path": "string",
      "description": "string",
      "format": "Array[Number]",
      "example": "string",
      "metadataDetails": {
        "dimensionsAvailable": [
          {
            "id": "string",
            "path": {
              "dimensionPaths": "string"
            }
          }
        ]
      }
    }
  ]
}

 

The request structure to see the date range available for a given set of fields.

Properties

Name
Type
Required Restrictions Description
attributes [metadata_attribute] true none List of attributes.
metrics [metadata_metric] true none List of metrics.

dateRange_response

{
  "dateRange": {
    "minStartDate": "string",
    "maxEndDate": "string"
  }
}

 

The date range that can be used in /report call for given set of fields.

Properties

Name
Type
Required Restrictions Description
dateRange object false none Date Range that can be used in /report call for given set of fields.
» minStartDate string false none The min date that can be used to request data for the fields specificed in the call.
» maxEndDate string false none The max date that can be used to request data for the fields specified in the call.

Endpoints

The OpenX Data Service endpoints are as follows:


fields

Get the fields that are available and can be used in the /reports call.

Call this endpoint to get metadata for the fields you have access to including descriptions.

cookie Parameters
openx3_access_token
string
Example: openx3_access_token=accessTokenFromBrowserCookie

This is for curl command only. From the browser example, it will use the browser cookie.
This cookie value will be The Openx3 access token provides access to the data. Information on how to get a token can be found. Find out more about OpenX access token.

Responses

Response samples

Content type
text/html
{
  "metrics": [
    {
      "metadataMetrics": {
        "id": "billableImpressions",
        "path": "funnel::potentialImpressions",
        "description": "Total number of impressions served.",
        "format": "Number",
        "example": "45643",
        "metadataDetails": {
          "dimensionsAvailable": [
            {
              "id": "publisherAccountID",
              "path": "context::site"
            },
            {
              "id": "publisherAccountName",
              "path": "context::site"
            },
            {
              "id": "publisherSiteId",
              "path": "context::site"
            },
            {
              "id": "publisherSiteName",
              "path": "context::site"
            },
            {
              "id": "publisherAdUnitId",
              "path": "placement::generalPlacement"
            },
            {
              "id": "publisherAdUnitName",
              "path": "placement::generalPlacement"
            },
            {
              "id": "demandPartnerAccountId",
              "path": "response::generalResponse"
            },
            {
              "id": "demandPartnerAccountName",
              "path": "response::generalResponse"
            }
          ]
        }
      }
    },
    {
      "metadataMetrics": {
        "id": "publisherRevenue",
        "path": "funnel::potentialSpend::pubRev",
        "description": "Total number of impressions served.",
        "format": "Number",
        "example": "45643",
        "metadataDetails": {
          "dimensionsAvailable": [
            {
              "id": "publisherAccountID",
              "path": "context::site"
            },
            {
              "id": "publisherAccountName",
              "path": "context::site"
            },
            {
              "id": "publisherSiteId",
              "path": "context::site"
            },
            {
              "id": "publisherSiteName",
              "path": "context::site"
            },
            {
              "id": "publisherAdUnitId",
              "path": "placement::generalPlacement"
            },
            {
              "id": "publisherAdUnitName",
              "path": "placement::generalPlacement"
            },
            {
              "id": "demandPartnerAccountId",
              "path": "response::generalResponse"
            },
            {
              "id": "demandPartnerAccountName",
              "path": "response::generalResponse"
            }
          ]
        }
      }
    }
  ],
  "dimensions": [
    {
      "metadataDimensions": {
        "id": "publisherAccountID",
        "path": "context::site",
        "description": " OpenX ID for the publisher.",
        "format": "Number",
        "example": "1610631427"
      }
    },
    {
      "metadataDimensions": {
        "id": "publisherAccountName",
        "path": "context::site",
        "description": "Name of the publisher's account.",
        "format": "String",
        "example": "Demo Account"
      }
    },
    {
      "metadataDimensions": {
        "id": "publisherSiteId",
        "path": "context::site",
        "description": "OpenX ID for the site.",
        "format": "Number",
        "example": "1616469958"
      }
    },
    {
      "metadataDimensions": {
        "id": "publisherSiteName",
        "path": "context::site",
        "description": "Name of the site.",
        "format": "String",
        "example": "Demo Site"
      }
    },
    {
      "metadataDimensions": {
        "id": "publisherAdUnitId",
        "path": "placement::generalPlacement",
        "description": "OpenX ID for the ad unit.",
        "format": "Number",
        "example": "537638175"
      }
    },
    {
      "metadataDimensions": {
        "id": "publisherAdUnitName",
        "path": "placement::generalPlacement",
        "description": "Name of the ad unit.",
        "format": "String",
        "example": "Ad_Unit_abc"
      }
    },
    {
      "metadataDimensions": {
        "id": "demandPartnerAccountId",
        "path": "response::generalResponse",
        "description": "OpenX ID associated with the entity or DSP that submits bids in the OpenX ad exchange.",
        "format": "Number",
        "example": "540657874"
      }
    },
    {
      "metadataDimensions": {
        "id": "demandPartnerAccountName",
        "path": "response::generalResponse",
        "description": "Demand Partner name associated with the entity or DSP that submits bids in the OpenX ad exchange.",
        "format": "String",
        "example": "DoubleClick Bid Manager - RTB"
      }
    }
  ]
}

report

Run a report

Call this endpoint with the attributes and metrics that are important to you to generate a report.

cookie Parameters
openx3_access_token
string
Example: openx3_access_token=accessTokenFromBrowserCookie

The Openx3 access token provides access to the data. Information on how to get a token can be found. Find out more about OpenX access token.

header Parameters
accept-encoding
string
Example: gzip, deflate

The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. Using content negotiation, the server selects one of the proposals, uses it and informs the client of its choice with the Content-Encoding response header. For more information, see MDN web docs.

Request Body schema: application/json
startDate
required
stringYYYYMMDD[:HH] or ISO 8601

Start date for the data fetched in the report. startDate is inclusive in the query and hour is optional; denoted by :HH at the end of the YYYYMMDD.

endDate
required
stringYYYYMMDD[:HH] or ISO 8601

End date is exclusive in the query. For example, to get one days of data, apply endDate = startDate + 1 day.

reportFormat
string
Default: "JSON"
Value: "JSON"

Format of the report requested by the user. Currently, only JSON is supported.

acceptEncoding
string
Enum: "gzip, deflate" "gzip" "deflate"

The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. Using content negotiation, the server selects one of the proposals, uses it and informs the client of its choice with the Content-Encoding response header. For more information, see Accept-Encoding.

Array of objects (metadata_attribute)

List of attributes.

Array of objects (metadata_metric)

List of metrics.

filter_expression (object) or filter (object)

Filter object or Filter Expressions

Responses

Request samples

Content type
application/json
{
  • "startDate": "2019-08-15T00:00:00Z",
  • "endDate": "2019-08-15T13:00:00Z",
  • "attributes": [
    ],
  • "metrics": [
    ],
  • "filters": {
    }
}

Response samples

Content type
text/html
{
  "reportData": [
    {
      "publisherAccountName": "Demo_Account",
      "billableImpressions": 24687,
      "publisherSiteName": "Site_1",
      "publisherRevenue": 0,
      "publisherAdUnitId": "1610619089",
      "publisherAdUnitName": "Ad_Unit_abc"
    },
    {
      "publisherAccountName": "Demo_Account",
      "billableImpressions": 2424,
      "publisherSiteName": "Site_2",
      "publisherRevenue": 2.739120012072817,
      "publisherAdUnitId": "1610619089",
      "publisherAdUnitName": "Ad_Unit_abc"
    },
    {
      "publisherAccountName": "Demo_Account",
      "billableImpressions": 450,
      "publisherSiteName": "Site_1",
      "publisherRevenue": 1.2419999688863754,
      "publisherAdUnitId": "1610632540",
      "publisherAdUnitName": "Ad_Unit_123"
    }
  ],
  "reportMetadata": {
    "reportCreated": "2018-12-10T09:46:20-08:00"
  }
}

date-range

Post call returns the date range available to be used in the post /report call for a given list of fields.

Call this endpoint to determine if there is new data available to request or to determine valid dates to be used in the post /report call.

cookie Parameters
openx3_access_token
string
Example: openx3_access_token=accessTokenFromBrowserCookie

The Openx3 access token provides access to the data. Information on how to get a token can be found. Find out more about OpenX access token.

Request Body schema: application/json
required
Array of objects (metadata_attribute)

List of attributes.

required
Array of objects (metadata_metric)

List of metrics.

Responses

Request samples

Content type
application/json
{
  • "attributes": [
    ],
  • "metrics": [
    ]
}

Response samples

Content type
text/html
{
  "dateRange": [
    {
      "minStartDate": "2019-06-01T00:00:00Z",
      "maxEndDate": "2019-08-23T22:00:00Z"
    }
  ]
}