API¶

Authentication¶

We require authentication on some requests, but JSONP requests don’t require them. Authentication works in one of two ways:

For requests made in your web browser, your authenticated session will be used
For all other requests, you need to use the Authorization HTTP header:
Authorization: Token 0000000000000000000000000000000000000000
Where the value of the header is the string “Token” followed by a space and your 40 character API key.

Note

Creating an API token can be done under Username Dropdown > API Token.

Ad decision¶

class adserver.api.views.AdDecisionView(**kwargs)[source]¶

Make a decision on an Advertisement to show.

The ad decision is based on

the publisher (ad campaigns may be publisher specific)
the available placements (ad types and priorities)
minimal user agent details (browser, mobile, operating system)
geography (based on IP)
keywords

GET /api/v1/decision/¶

Request an advertisement for a specific publisher.

The publisher must be explicitly permitted to allow unauthenticated requests. This is typically used as a JSONP call.

Request JSON Object:
	publisher (string) – Required. The slug of the publisher. If using the ethical-ad-client, this comes from `data-ea-publisher`. div_ids (string) – A `\|` delimited string of on-page ids. The number and order must correspond to the `ad_types` ad_types (string) – A `\|` delimited string of ad types. The number and order must correspond to the `div_ids`. priorities (string) – An optional `\|` delimited string of priorities for different ad types. The number and order matter, applying to `div_ids` and `ad_types`. keywords (array) – An optional `\|` delimited string of case-insensitive keywords that describe content on the page where the ad is requested (eg. `python\|docker\|kubernetes`). Used for ad targeting and is additive with any publisher settings. campaign_types (array) – An optional `\|` delimited string of campaign types (eg. `paid\|community\|house`) which can be used to limit to just certain types of ads. Can only further reduce campaign types, not allow ones prohibited for the publisher. url (string) – The URL of the requesting page. This is where the ad will appear. format (string) – Format can optionally be specified as `jsonp` to allow a callback. callback (string) – The name of the callback for a JSONP request (default is `callback`) force_ad (string) – Limit results to a specific ad force_campaign (string) – Limit results to ads from a specific campaign
Response JSON Object:
	id (string) – The advertisement slug of the chosen ad text (string) – The HTML text of only the ad without any images (see `html` for full HTML) body (string) – The text of the ad, stripped of any HTML. copy (object) – A breakdown of the ad into its `content`, optional `headline` and optional call to action (`cta`). These fields are always plain text. html (string) – An HTML rendering of the ad link (string) – A click URL for the ad view_url (string) – A view URL to count an ad view view_time_url (string) – A URL endpoint that updates how long the ad was viewed nonce (string) – A one-time nonce used in the URLs so the ad is never double counted display_type (string) – The slug of type of ad (eg. sidebar) div_id (string) – The <div> ID where the ad will be inserted campaign_type (string) – The type of campaign this as is from (eg. house, community, paid)

An example:

# Multiple type options
{
    "ad_types": "readthedocs-fixed-footer|readthedocs-sidebar",
    "div_ids": "text-div|image-div"
    "priorities": "3|5"
}

# Simplest case
{
    "ad_types": "readthedocs-sidebar",
    "div_ids": "sample-div"
}

POST /api/v1/decision/¶

Authentication is required for this endpoint. The POST version of the API is similar to the GET version with only a few changes:

Request JSON Object:

publisher (string) – Required. The slug of the publisher.
placements (array) – Required. Various possible ad placements where an ad could go. This is a combination of div_ids, ad_types, and priorities in the GET API. Only one ad will be returned but you can prioritize one type of ad over another.
keywords (array) – Case-insensitive strings that describe the page where the ad will go for targeting
campaign_types (array) – Limit the ad results to certain campaign types.
user_ip (string) – User’s IP address used for targeting (the requestor’s IP will be used if not present)
user_ua (string) – User’s user agent used for targeting (the requestor’s UA will be used if not present)

The response is the same as the GET request above.

An example:

{
    "publisher": "your-publisher",
    "placements": [
        {
            "div_id": "ad-div-1",
            "ad_type": "image-v1",
            "priority": 10,
        }
    ],
    "campaign_types": ["paid"],  # request PAID ads only
    "keywords": [
        "python",
        "docker",
        "kubernetes",
    ],
}

Publisher APIs¶

class adserver.api.views.PublisherViewSet(**kwargs)[source]¶

Publisher API calls.

GET /api/v1/publishers/¶

Return a list of publishers the user has access to

Response JSON Object:
	count (int) – The number of publisher returned next (string) – A URL to the next page of publisher (if needed) previous (string) – A URL to the previous page of publisher (if needed) results (array) – An array of publisher results (see publisher details call)

GET /api/v1/publishers/(str: slug)/¶

Return a specific publisher

Response JSON Object:
	url (string) – The URL to this report name (string) – The name of the publisher slug (string) – A slug for the publisher created (date) – An array of publisher results modified (date) – The date the publisher was last modified

GET /api/v1/publishers/(str: slug)/report/¶

Return a report of ad performance for this publisher

Query Parameters:
	start_date (date) – Start the report on a given day inclusive. If not specified, defaults to 30 days ago end_date (date) – End the report on a given day inclusive. If not specified, no end time is used (up to current)
Response JSON Object:
	days (array) – An array of publisher results per day total (object) – An object of aggregated totals for the publisher

Advertiser APIs¶

class adserver.api.views.AdvertiserViewSet(**kwargs)[source]¶

Advertiser API calls.

GET /api/v1/advertisers/¶

Return a list of advertisers the user has access to

Response JSON Object:
	count (int) – The number of advertisers returned next (string) – A URL to the next page of advertisers (if needed) previous (string) – A URL to the previous page of advertisers (if needed) results (array) – An array of advertiser results (see advertiser details call)

GET /api/v1/advertisers/(str: slug)/¶

Return a specific advertiser

Response JSON Object:
	url (string) – The URL to this report name (string) – The name of the advertiser slug (string) – A slug for the advertiser created (date) – An array of advertiser results modified (date) – The date the advertiser was last modified

GET /api/v1/advertisers/(str: slug)/report/¶

Return a report of ad performance for this advertiser

Query Parameters:
	start_date (date) – Start the report on a given day inclusive. If not specified, defaults to 30 days ago end_date (date) – End the report on a given day inclusive. If not specified, no end time is used (up to current)
Response JSON Object:
	days (array) – An array of advertiser results per day total (object) – An object of aggregated totals for the advertiser flights (array) – An array of flights for this advertiser in the time period