You are here: Demand Partners > Discovery API

Discovery API

Last updated July 20, 2016

Introduction

The discovery API is a tool that enables Demand Side Platforms (DSPs), Agency Trading Desks and Agencies to discover available Private MarketplaceThe packaging, offering, and selling of high quality inventory to a limited set of buyers. Abbreviated as PMP. (PMPPrivate marketplace, the packaging, offering, and selling of high quality inventory to a limited set of buyers.) packages, publishers and sites from OpenX through their demand platforms. This in turn provides you with the capability and efficiency to discover deals across multiple packages and categories within the same demand platform used to execute deals.

Getting started

Before using the discovery API, you must first be authenticated and authorized to access the PMP using your credentials. For purposes of this document, it is assumed you already have user credentials that provide you access to OpenX’s marketplace. If you do not currently have access credentials, please contact your account manager. If you would like more detailed information about authentication and authorization, reference OpenX documentation.

Implementing the discovery API

After you have been authenticated and authorized to access the private marketplace via an access token, you are ready to begin making API calls to discover packages. The example below describes how you can use Python to implement the PMP API logic and retrieves discoverable packages in the marketplace. To simplify the process of using the discovery API to find discoverable packages, contact your OpenX account manager for a Python API client example. The client example includes a ReadMe file and an example Python script that implements the client library logic and retrieve a list of packages in the private marketplace.

Step 1 - Set up the git repository

The first step in the process is to set up your Git repository to work with the Python example. Perform the following tasks:

  1. Create the git_clones directory.
  2. mkdir git_clones
  3. Go to the newly-created git_clones directory.
  4. cd git_clones
  5. Clone the Python API Client Library.
  6. git clone https://github.com/openx/OX3-Python-API-Client.git
  7. Clone the Oauth2 library.
  8. git clone https://github.com/joestump/python-oauth2
  9. Clone the HTTP client library.
  10. git clone https://github.com/jcgregorio/httplib2

Step 2 - Create symbolic links to directories

When you are finished configuring the GitHub repository, create symbolic links to each of these directories by entering the following commands:


ln -s git_clones/OX3-Python-API-Client/ox3apiclient .
ln -s git_clones/python-oauth2/oauth2 .
ln -s git_clones/httplib2/python2/httplib2 .	

Step 3 - Edit the example.py script

You will then need to edit the following variables in the example.py file:

  • email = 'you@example.com'
  • password = 'password123'
  • domain = 'uidomain.com'
  • realm = 'uidomain_realm'
  • consumer_key = '<your_consumer_key>'
  • consumer_secret = '<your consumer secret>'

Note: : Contact your account manager to receive Consumer Key and Consumer Secret.

Step 4 - Execute the example.py script

Now that you have edited the variables in the example.py file, enter the following command to execute the python script and make the GET /ox/4.0/package/discover API call to the OpenX server.

python example.py

Once executed, the script will:

  1. Implement the authentication logic by logging you into the OpenX server.
  2. Make the GET /ox/4.0/package/discover call and print a list of all packages that have been made discoverable.
  3. Log you out of the server.

Note that you can change the call in the script to a different discovery API call described in this document if needed. Mostly, the script sets up authentication so that you can make an API call.

You can also modify the call to GET /ox/4.0/package/discover/{package_id} to get a particular packageA bundle of targeting criteria for similar inventory segments which you can offer at a predetermined price (typically to facilitate regular sales efforts) and automatically create line items from in OpenX. instead of a list of packages.

The array of packages returned will look similar to the following example:

{
        "has_more": false,
        "objects": [
        {"access_type": 1,"audience": 1,
        "contact_email": "yosef@toto.com",
        "contact_name": "Yosef Oh",
        "countries": null,
        "currency": "USD",
        "description": "",
        "device_types": [2,4,5],
        "expandable": 0,
        "iab_categories": null,
        "id": "1",
        "inventory_types": [1,2],
        "last_updated": "2015-09-15 02:06:55",
        "logo_url": null,
        "name": "another package to discover",
        "participants": [{"rate_price": "99.4000","special_rate": null,"wseat": null}],
        "price_type": 3,
        "publishers": ["537273067"],
        "sites": null,
        "sizes": ["300x250"]
        },
   ]
}	

Note that the following fields and values are displayed in the response for each package:

Step 5 - Purchase a package in the private marketplace

After having had an opportunity to review the packages, you can then purchase a package by executing the following POST command with the package_id and openx_buyer_ids arguments:

POST /ox/4.0/package/buy
{"package_id": 888,"openx_buyer_ids":"1234",}

In this example, the package_id is "888" and the specific openx_buyer_ids is "1234."

Note: A complete list of all package attributes can be found in the Appendices section of this guide.

Step 6 - Confirm package purchase

When you make the POST /ox/4.0/package/buy API call with package_id and openx_buyer_ids argument, the package will be purchased and a full deal object is returned. Note the following:

  1. openx_buyer_id must be authorized for the package 888.
  2. if multiple prices are available for a package, the lower price will be used.

Return a list of deals

You can use the discovery API to get a list of deals you are eligible for, using the following call:

GET /demand/deal

Sample Request

https://SERVER_NAME/ox/4.0/demand/deal

Sample Response

{
        "access_type": 1,
        "account_executive_email": "joe@example.com",
        "account_executive_name": "Joe Moseti",
        "account_manager_email": "karen@example.com",
        "account_manager_name": "Karen Fuh",
        "currency": "INR",
        "description": "",
        "end_date": "2016-03-23 07:00:00",
        "id": "OX-qav-XCU4fF",
        "last_updated": "2016-03-04 22:38:50",
        "name": "deal-discovery-6",
        "open_access": "",
        "package": "1610741638",
        "participants": [
        {
        "brands": [
        "49511"
        ],
        "wseat": [
        "1001"
 ]
   }
      ],
        "price": "12.00",
        "price_type": 3,
        "start_date": "2016-03-10 08:00:00",
        "status": "Active"
    },
    {
        "access_type": 1,
        "account_executive_email": "jose@example.com",
        "account_executive_name": "Jose Ruiz",
        "account_manager_email": "hui@example.com",
        "account_manager_name": "Hui Len",
        "currency": "USD",
        "description": "",
        "end_date": "2016-03-17 07:00:00",
        "id": "OX-qai-3xflKM",
        "last_updated": "2016-03-10 21:46:18",
        "package": "1610765719",
        "participants": [
     {
        "brands": [
        "18340"
        ],
        "wseat": [
        "1001"
     ]
     }
     ],
        "price": "1.00",
        "price_type": 3,
        "start_date": "2016-03-10 08:00:00",
        "status": "Active"
     }
		

Return a list of publishers and sites

You may also use the discovery API to discover a list of publishers and sites in the Private Marketplace. The discovery API includes the following four Inventory API calls listed in the table below.

Inventory API Calls

API Call Description
GET /inventory/publisher This call returns all visible publishers.
GET /inventory/site This call returns all visible sites.
GET /inventory/publisher/{id} This call returns the referred publisherAn account type that represents a business with ad space to sell., if visible.
GET /inventory/site/{id} This call returns the referred siteAn OpenX component that represents top-level domains or sub-domains and is used to organize ad units. Sites enable you to target and report on inventory performance., if visible.

These API calls not only enable you to retrieve publishers and sites, but also specify which of these publishers and sites you want to see (assuming they are visible). The sample code snippets shown below illustrate how you can make these calls in a browser window to return specified publisher(s) and site(s).


GET /inventory/publisher

Sample Request

https://SERVER_NAME/ox/4.0/inventory/publisher

Sample Response

[{
        "cat": null,
        "contact_email": "jose@example.com",
        "contact_name": "Jose Ruiz",
        "country_of_business": "in",
        "currency": "USD",
        "description":
        "domain": null,
        "id": "1611252355",
        "last_updated": "2015-10-13 20:02:53",
        "name": "discover_pub",
        "network": "1611252354",
        "timezone": "America/Los_Angeles"
        },
        {
        "cat": null,
        "contact_email": "hui@example.com",
        "contact_name": "Hui Len",
        "country_of_business": "us",
        "currency": "USD",
        "description":
        "domain": null,
        "id": "1611260509",
        "last_updated": "2015-10-23 20:44:09",
        "name": "publisher2",
        "network": "1611260205",
        "timezone": "America/Los_Angeles"
        }]
        

GET /inventory/site

Sample Request

https://SERVER_NAME/ox/4.0/inventory/site

Sample Response

[{
        "bundle": null,
        "cat": null,
        "contact_email": "jose@example.com",
        "contact_name": "Jose Ruiz",
        "description": "",
        "domain": "http://www.openx.org/",
        "id": "1610767341",
        "last_updated": "2015-11-18 23:52:19",
        "name": "Sports Site",
        "os": "Windows10",
        "publisher": "1610864422"
        },
        {
        "bundle": null,
        "cat": null,
        "contact_email": "jose@example.com",
        "contact_name": "Jose Ruiz",
        "description": "",
        "domain": "http://www.openx.com/",
        "id": "1610768182",
        "last_updated": "2015-11-18 23:15:02",
        "name": "News Site",
        "os": "Windows10",
        "publisher": "1610868381"
        }]
        

GET /inventory/publisher/{id}

Sample Request

https://SERVER_NAME/ox/4.0/inventory/publisher/1611252355

Sample Response

[{
        "cat": null,
        "contact_email": "mary@example.com",
        "contact_name": "Mary Rose",
        "country_of_business": "in",
        "currency": "USD",
        "description": "",
        "domain": null,
        "id": "1611252355",
        "last_updated": "2015-10-13 20:02:53",
        "name": "sample_publisher1",
        "network": "1611252354",
        "timezone": "America/Los_Angeles"
        }]
			

GET /inventory/site/{id}

Sample Request

https://SERVER_NAME/ox/4.0/inventory/site/1610767341

Sample Response


[{
        "bundle": null,
        "cat": null,
        "contact_email": "ursula@toto.com",
        "contact_name": "Ursula Gottlieb",
        "description": "",
        "domain": "http://www.openx.org/",
        "id": "1610767341",
        "last_updated": "2015-11-18 23:52:19",
        "name": "Fashion Site",
        "os": null,
        "publisher": "1610864422"
 }]    

Package attributes

A package is a specific advertised buying opportunity representing the advertised product on a virtual shelf. Packages address inventory on a particular publisher/site or a set of publishers and/or sites that are part of a network. The following attributes listed in the table below can be associated with a package.

You can set a priority when you create a deal (the default priority is 5) or adjust it later. The following instructions assume that you have multiple deals associated with a single package and want to adjust their priority.

Attribute Definition
id

A unique identifier that represents the package being offered.

name

The name for the package.

description

A text description for the package.

discoverable

A flag that specifies whether the package should be discoverable in the UI.

logo_url

The URL path for the package logo.

cat

An array of categories included in the package.

sites

An array of site IDs included in the package.

publishers

An array of publisher IDs included in the package.

countries

An array of countries in which inventory for the package.

sizes

An array of sizes being offered for the package.

device_types

An array of device types for the package.

inventory_types

An array of inventory being offered for the package.

access_type

The type of access being offered for the package.

price_type

The type of pricing being offered for the package.

audience

Specifies whether the package contains inventory with first-party audience data.

7dimps 7-day impressionA single display of an ad on a web page, mobile app, or other delivery medium. For deals, impression is a metric to relay the total number of ads that have served. See also billable impression, forecasted impressions. count.
7duus 7-day unique userA site's total number of users or visitors over a certain length of time. Accuracy depends on each user logging in with a unique cookie to access the site, such as a different browser. average count.
rate_price The CPMCost per mille, a pricing method which calculates cost based on the number of impressions (per 1000). rate for the package, which can be set as optional by the publisher if they want to have the price set during negotiation.
special_price The special price for the CPM, which can be set as optional by the publisher if they want to have the price set during a negotiation.
currency The type of currency used for the CPM (e.g. USD, Euro, etc.).
expandable A value that specifies whether the package can be expanded.
page positionThe location of an ad on a page, such as above the fold (ATF) or below the fold (BTF). This is also referred to as "screen location" or "page placement." Specifies where the package is placed (e.g. ATFAbove the fold. ATF ads are visible on the screen without needing to scroll. See screen location., BTFBelow the fold. Below the fold ads are not visible until the user scrolls down to them. See screen location.).
contact_name The name of the person who should be contacted if there are questions about the package.
contact_email The email address associated with the contact name attribute.
wseat Wseat is the buyerid associated with the demand partnerA company which purchases ad inventory on OpenX Ad Exchange., and needs to be set when buying a package.
last_updated The date/time of the last update, which is in UTC format.

Server response values

The tables below list the various server response values that can be returned when making the GET /ox/4.0/package/discover API call.

Device Type

Device Type Value Name
2 Personal Computer
3 Connected Device
4 Phone
5 Tablet

Inventory Type

Inventory Type Name Description
1 Web Web content that is intended to be viewed on a desktop. If it is seen on a mobile device, it is still this type.
2 Mobile Web (Optimized) Web content that is optimized to be viewed on a phone or tablet. The design is mobile-specific or responsive.
3 Mobile AppSynonymous with mobile. Refers to the use of an app via a mobile device, specifically to differentiate from mobile web. Web content that is optimized to be viewed on a phone or tablet.
4 Video Web content that is optimized to be viewed on a phone or tablet.

Access Type

Access Type Name Description
1 Preferred access Buyers are eligible for preferential access to inventory (i.e. in a tier before open auction occurs, or the inventory is not available at all in open auction).
2 Standard access Buyers have standard access to inventory; their bids compete against the set of other bidders in the general auction.

Pricing Type

Pricing Type Name Description
1 Fixed-price The deal is to be transacted at a fixed price. If there are multiple buyers competing for a given impression, the highest fixed price deal wins.
2 Floor price, first-price auction The deal has a floor price, and first-price auction mechanics apply
3 Floor price, second-price auction The deal has a floor price, and second-price auction mechanics apply in the event of competing bids

Note: : Only certain types of access and pricing combinations will make sense for certain use cases.

Access Type

Access Type Pricing Type Notes/Typical Use Case
Preferred access Fixed-price "First look" or "preferred look"
Preferred access Floor-price, first-price auction Private auction
Preferred access Floor-price, second-price auction Private auction
Standard access Fixed-price Theoretically possible, but not beneficial to publisher
Standard access Floor price, first-price auction Only useful in the case that a deal carries additional targeting beyond what is exposed in the bid requestWhen OpenX Ad Exchange receives an ad request, it sends a communication containing details about the impression to selected real-time bidders to solicit bids for it.
Standard access Floor price, second-price auction Only useful in the case that a deal carries additional targeting beyond what is exposed in the bid request

Operating System

Value Name
1 Android
2 iOS
3 Windows Phone

Access Type

Access Type Pricing Type Notes/Typical Use Case
1 Active The deal is live and, provided that the current time is between the deal's start and end dates/times, bid requests are being sent to the DSPDemand-side platform, a platform or provider that allows advertisers to manage multiple ad exchange and data exchange accounts through one interface, often in real time..
2 Suspended by Publisher The deal has been suspended by the publisher. Bid requests are not being sent to the DSP. The deal can be reactivated by the publisher as desired.
3 Suspended by BuyerA company that pays a demand partner to purchase ad inventory on OpenX Ad Exchange. The deal has been suspended by the buyer (may be identified using Buyside API). SSPs stop sending bid requests to the DSP when this status is set. The deal can be reactivated by the publisher as desired.

Filtering Deals, Packages, and Inventory Publishers and Inventory Sites

The discovery API also enables buyers with a "buyer_experience=1" to return a list of all discoverable packages, sites, publishers, by allowing buyers to filter for deals, packages, publisher inventory, and site inventory.

The tables below list the different fields that users can filter.

Deals

Field Description
id The ID associated with the deal.
name The name of the deal.
status The current status of the deal.
start_date The start date for the deal.
end_date The end date for the deal.
last_updated The date the deal was last updated.

Packages

Field Description
id The ID associated with the package.
name The name of the package.
start_date The start date for the package.
end_date The end date for the package.
last_updated The date the package was last updated.

Inventory Publishers

Field Description
id The ID associated with the publisher.
name The name of the publisher.
currency The currency used for the publisher.
network The network associated with the publisher.
last_updated The date the publisher was last updated.

Inventory Sites

Field Description
id The ID associated with the site.
name The name of the site.
publisher The publisher associated with the site.
last_updated The date the site was last updated.

Sample Requests and Responses

The sample requests & responses shown below demonstrate how you can use filtering for the Discovery API.

Return a list of discoverable packages which start after 2016-03-21 and start before 2016-04-04 and status is active

http://qa-v2-i17-lmi.api-v4-qa-ca.openx.net/ox/4.0/package/discover?status=active&start_date__gt=2016-03-21&start_date__lt=2016-04-04&pretty=true
"objects": [
        {
        "access_type": 1,
        "audience": 0,
        "contact_email": null,
        "contact_name": null,
        "countries": null,
        "currency": "USD",
        "description": "",
        "device_types": [
        2,
        4,
        5
        ],
        "domains": "website.com",
        "end_date": "2016-04-13 10:22:07",
        "expandable": 0,
        "iab_categories": null,
        "id": "1610789154",
        "inventory_types": [],
        "last_updated": "2016-03-23 17:22:08",
        "logo_url": null,
        "name": "OXbot_Package_50386775_1458753710",
        "page_position": 0,
        "participants": [
        {
        "rate_price": "1.0000",
        "special_rate": null,
        "wseat": null
        }
        ],
        "price_type": 3,
        "publishers": [],
        "sites": [],
        "sizes": [],
        "start_date": "2016-03-23 10:22:07",
        "urls": []
        }]
        Other filter for package
        +        - id
        +        - name
        +        - start_date
        +        - end_date
        +        - last_updated
        ----------------------------------------------------------------------------------------------------

Return a deal with a particular id

http://qa-v2-i17-lmi.api-v4-qa-ca.openx.net/ox/4.0/demand/deal?id=OX-qav-bTuzCj&pretty=true
        [
        {
        "access_type": 1,
        "account_executive_email": "",
        "account_executive_name": "",
        "account_manager_email": "",
        "account_manager_name": "",
        "currency": "USD",
        "description": "",
        "end_date": "2026-03-26 07:00:00",
        "id": "OX-qav-bTuzCj",
        "last_updated": "2016-03-23 00:02:56",
        "name": "Cameron - deal",
        "open_access": "",
        "package": "1610664185",
        "participants": [
        {
        "brands": [],
        "wseat": []
        }
        ],
        "price": "5.00",
        "price_type": 3,
        "start_date": "2016-03-22 07:00:00",
        "status": "Active"
        }
        ]
        Other filters for deals
        +        - id
        +        - name
        +        - status
        +        - start_date
        +        - end_date
        +        - last_updated
        ----------------------------------------------------------------------------------------------------

Return a list of publishers with name

http://qa-v2-i17-lmi.api-v4-qa-ca.openx.net/ox/4.0/inventory/publisher?pretty=true&name=discover_pub
        [
        {
        "cat": null,
        "contact_email": null,
        "contact_name": null,
        "country_of_business": "in",
        "currency": "INR",
        "description": "",
        "domain": null,
        "id": "1611252355",
        "last_updated": "2015-10-13 20:02:53",
        "name": "discover_pub",
        "network": "1611252354",
        "timezone": "America/Los_Angeles"
        }
        ]
        For inventory publishers
        +        - id
        +        - name
        +        - currency
        +        - network
        +        - last_updated
        ----------------------------------------------------------------------------------------------------

Return a list of sites

http://qa-v2-i17-lmi.api-v4-qa-ca.openx.net/ox/4.0/inventory/site?pretty=true&id=1610613518
        [
        {
        "bundle": null,
        "cat": null,
        "contact_email": null,
        "contact_name": null,
        "description": "",
        "domain": "https://market.android.com/details?id=[package-name]",
        "id": "1610613518",
        "last_updated": "2015-09-08 22:08:10",
        "name": "Kyle_i26_EntPub1_site1 (mobile)",
        "os": null,
        "publisher": "1610635695"
        }
        ]

API reference

Access type

Returns a list of all packages a publisher has made discoverable and available for purchase in the Private Marketplace.

Sample request

The code snippet shown below illustrates the API call you need to make to find available packages:

get /ox/4.0/package/discover

Sample response

When the server receives and processes the request, you will see the following sample response. Note that no IAB categories are returned in this response.

{
        "has_more": false,
        "objects": [
        {"access_type": 1,
        "audience": 1,
        "contact_email": "my_bla@toto.com",
        "contact_name": "my bla name",
        "countries": null,
        "currency": "USD",
        "description": "",
        "device_types": [2,4,5],
        "expandable": 0,
        "iab_categories": null,
        "id": "1",
        "inventory_types":[1,2],
        "last_updated": "2015-09-15 02:06:55",
        "logo_url": null,
        "name": "another package to discover",
        "participants": [{"rate_price": "99.4000","special_rate": null,"wseat": null}],
        "price_type": 3,
        "publishers": ["537273067"],
        "sites": null,
        >"sizes":["300x250"]
        },
        {"access_type": 1,
        "audience": 0,
        "contact_email": "my_bla@toto.com",
        "contact_name": "my bla name",
        "countries": null,
        "currency": "USD",
        "description": "",
        "device_types": [2,4,5],
        "expandable": 0,
        "iab_categories": null,
        "id": "536871726",
        "inventory_types": [1,2],
        "last_updated": "2015-09-15 02:06:55",
        "logo_url": null,
        "name": "kAPPS-6496",
        "participants": [{"rate_price": "3.4000","special_rate":
        null,"wseat": null}],
        "price_type": 3,
        "publishers": ["537273067"],
        "sites": null,
        "sizes": ["300x250"]
        }
        ]

Feedback form