Data Service API 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 requests to the API endpoints at a regular basis to get data on how your business is going to store the data on your side. You can then manipulate such data 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 call get /fields.

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 FAQs, consult the Reporting API FAQ.

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

describe

# You can also use wget
curl -X GET /data/ods/1.0/report/fields \
  -H 'Accept: text/html'

GET /data/ods/1.0/report/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.

Parameters

Name	In	Type	Required	Description
`openx3_access_token`	cookie	string	false	Note: This is for curl command only. From the browser example, it uses the browser cookie. This cookie value will be the Openx3 access token that provides access to the data. For information on how to get a token, see OpenX access token.

Example responses

200 Response

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

401 Response

{
  "code": "401",
  "message": "Bad oauth_token, or connection is not using an internal IP, SSO check returned 401",
  "traceId": "string"
}

500 Response

{
  "code": "500",
  "message": [
    "Internal Server Error",
    "Invalid JSON",
    "Connections could not be acquired from the underlying database!"
  ],
  "traceId": "string"
}

502 Response

{
  "code": "502",
  "message": "Server Error",
  "traceId": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success response	metrics
401	Unauthorized	Unauthorized to access the API	error_object
500	Internal Server Error	Internal Server Error	error_object
502	Bad Gateway	Bad Gateway	error_object

report

runReport

# You can also use wget
curl -X POST /data/ods/1.0/report \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/html' \
  -H 'accept-encoding: gzip, deflate'

POST /data/ods/1.0/report

Run a report.

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

Body parameter example

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

Parameters

Name	In	Type	Required	Description
`openx3_access_token`	cookie	string	false	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`	header	string	false	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.
body	body	report_request	true	none

Example responses

200 Response

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

206 Response

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

400 Response

{
  "code": "400",
  "message": [
    "Invalid field(s): attributes=[], metrics=[], filters=[]",
    "Unparseable date : <input date>"
  ],
  "traceId": "string"
}

401 Response

{
  "code": "401",
  "message": "Bad oauth_token, or connection is not using an internal IP, SSO check returned 401",
  "traceId": "string"
}

404 Response

{
  "code": "404",
  "message": "Date Range not valid",
  "traceId": "string"
}

413 Response

{
  "code": "413",
  "message": "Number of accounts requested is too large. Please contact OpenX support",
  "traceId": "string"
}

500 Response

{
  "code": "500",
  "message": [
    "Internal Server Error",
    "Invalid JSON",
    "Connections could not be acquired from the underlying database!"
  ],
  "traceId": "string"
}

502 Response

{
  "code": "502",
  "message": "Server Error",
  "traceId": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success response	report_response
206	Partial Content	A successful response; however the response was truncated as the request hit an internal limit. If you hit this limit please try using filters to partition your request.	report_response
400	Bad Request	Bad Request. The request could not be understood by the server.	error_object
401	Unauthorized	Unauthorized to access the API	error_object
404	Not Found	Not Found	error_object
413	Payload Too Large	Request Entity too large	error_object
500	Internal Server Error	Internal Server Error	error_object
502	Bad Gateway	Bad Gateway	error_object

date-range

getDateRange

# You can also use wget
curl -X POST /data/ods/1.0/date-range \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/html'

POST /data/ods/1.0/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.

Body parameter example

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

Parameters

Name	In	Type	Required	Description
`openx3_access_token`	cookie	string	false	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.
body	body	dateRange_request	true	none

Example responses

200 Response

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

400 Response

{
  "code": "400",
  "message": [
    "You do not have access to one or many of the fields you have requested!",
    "Unparseable date <input date>"
  ],
  "traceId": "string"
}

401 Response

{
  "code": "401",
  "message": {
    "type": "string",
    "enum": [
      "access_token not authorized by SSO"
    ]
  },
  "traceId": "string"
}

500 Response

{
  "code": "500",
  "message": [
    "Internal Server Error",
    "Invalid JSON",
    "email required in auth result"
  ],
  "traceId": "string"
}

502 Response

{
  "code": "502",
  "message": "Server Error",
  "traceId": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success response	dateRange_response
400	Bad Request	Bad Request. The request could not be understood by the server.	error_object
401	Unauthorized	Unauthorized to access the API	error_object
500	Internal Server Error	Internal Server Error	error_object
502	Bad Gateway	Bad Gateway	error_object

Schemas

The OpenX Data Service schemas are described below.

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

The Error model for displaying the error details.

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. For more details, please refer to IAB's AdCom Specifications.

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

{
  "url": "string",
  "method": "GET",
  "encType": "application/json"
}

Link Object

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. For more details, please refer to IAB's AdCom Specifications.

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 MDN web docs.
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 specified in the call.
» maxEndDate	string	false	none	The max date that can be used to request data for the fields specified in the call.