OpenX Data Service (1.1.0)

E-mail: api_migration@openx.com License: Copyright and legal notices

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

Link Object

{
  "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.

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:

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.

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

Payload

Content type

application/json

{"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"
}
}

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

Payload

Content type

application/json

{"attributes": [{"id": "publisherAccountName"
},
{"id": "publisherAccountId"
},
{"id": "publisherCurrency"
},
{"id": "publisherSiteName"
}
],
"metrics": [{"id": "marketRequests"
},
{"id": "marketImpressions"
}
]
}

Response samples

Content type

text/html

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