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.
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.
To authenticate, install one of the following clients:
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)
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.
Consider the following:
For any questions about these features, please contact api_migration@openx.com.
For a list of FAQs, consult the Reporting API FAQ on the OpenX Community.
{
"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. |
{
"id": "string",
"path": "string"
}
Properties
Name |
Type |
Required | Restrictions | Description |
---|---|---|---|---|
id |
string |
false | none | none |
path |
string |
false | none | none |
[
{
"id": "string",
"path": "string"
}
]
{
"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 |
{
"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 |
{
"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 |
{
"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 |
"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 |
{
"url": "string",
"method": "GET",
"encType": "application/json"
}
Properties
Name |
Type |
Required | Restrictions | Description |
---|---|---|---|---|
url |
string |
true | none | The URL of the related HATEOAS link to use in subsequent calls. |
method |
string |
false | none | The HTTP method required for the related call. |
encType |
string |
false | none | The media type in which to submit data in the request. |
{
"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. |
{
"dimensionsAvailable": [
{
"id": "string",
"path": "string"
}
]
}
Properties
Name |
Type |
Required | Restrictions | Description |
---|---|---|---|---|
dimensionsAvailable |
dimensions_available |
false | none | none |
{
"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. |
{
"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": [
{
"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 |
{
"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 |
{
"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. |
{
"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": {
"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. |
The OpenX Data Service endpoints are as follows:
GET /data/1.0/report/fields
: Gets the fields that are available and can be used in the /report
call.POST /data/1.0/report
: Generates a report by considering the provided attributes and metrics.POST /data/1.0/date-range
: Returns the date range available to be used in the POST /report
call for a given list of fields.Call this endpoint to get metadata for the fields you have access to including descriptions.
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. |
{ "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" } } ] }
Call this endpoint with the attributes and metrics that are important to you to generate a report.
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. |
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. |
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 |
{- "startDate": "2019-08-15T00:00:00Z",
- "endDate": "2019-08-15T13:00:00Z",
- "attributes": [
- {
- "id": "publisherAccountName"
}, - {
- "id": "publisherAccountId"
}, - {
- "id": "publisherCurrency"
}, - {
- "id": "publisherSiteName"
}
], - "metrics": [
- {
- "id": "marketRequests"
}, - {
- "id": "marketImpressions"
}
], - "filters": {
- "name": "publisherAdUnitId",
- "value": "533648256",
- "operator": "EQ"
}
}
{ "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" } }
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.
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. |
required | Array of objects (metadata_attribute) List of attributes. |
required | Array of objects (metadata_metric) List of metrics. |
{- "attributes": [
- {
- "id": "publisherAccountName"
}, - {
- "id": "publisherAccountId"
}, - {
- "id": "publisherCurrency"
}, - {
- "id": "publisherSiteName"
}
], - "metrics": [
- {
- "id": "marketRequests"
}, - {
- "id": "marketImpressions"
}
]
}
{ "dateRange": [ { "minStartDate": "2019-06-01T00:00:00Z", "maxEndDate": "2019-08-23T22:00:00Z" } ] }