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. The lowest priority is 1 and the maximum priority is 10.
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|publisher-house|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. Forcing a specific ad will ignore ad targeting, but forced ads are never counted for billing purposes.
force_campaign (string) – As with force_ad, 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, publisher-house, 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.

Please set your publisher name in the user agent of the request and set the requesting user’s user agent in user_ua. For example, if you would hit our API with the user agent python-requests/2.26.0, instead send something like python-requests/2.26.0 +YOURPUBLISHER. The actual end-user’s user agent should remain unchanged.

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