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
link_domain (string) – The domain where the ad will link to, extracted from the click URL
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

GET /api/v1/advertisers/(str: slug)/report/geos/

Return a report of ad performance for this advertiser broken down by country. This matches the geo report shown in the advertiser dashboard.

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:

results (array) – An array of advertiser results per country. Each result is indexed by the country name in the index field.
total (object) – An object of aggregated totals for the advertiser

GET /api/v1/advertisers/(str: slug)/report/publishers/

Return a report of ad performance for this advertiser broken down by publisher. This matches the publisher report shown in the advertiser dashboard.

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:

results (array) – An array of advertiser results per publisher. Each result is indexed by the publisher name in the index field.
total (object) – An object of aggregated totals for the advertiser

Flight APIs

class adserver.api.views.FlightViewSet(**kwargs)[source]

Flight API calls.

GET /api/v1/advertisers/(str: advertiser_slug)/flights/

Return a list of the advertiser’s flights the user has access to

Response JSON Object:

count (int) – The number of flights returned
next (string) – A URL to the next page of flights (if needed)
previous (string) – A URL to the previous page of flights (if needed)
results (array) – An array of flight results (see flight details call)

GET /api/v1/advertisers/(str: advertiser_slug)/flights/(str: flight_slug)/

Return a specific flight. The fields returned are the same as the flights in the advertiser report API.

Response JSON Object:

name (string) – The name of the flight
slug (string) – A slug identifying the flight
live (bool) – Whether the flight is currently shown
cpc (float) – The cost per click of the flight
cpm (float) – The cost per 1,000 impressions of the flight
targeting_parameters (object) – The flight targeting (regions, topics, keywords, etc.)
start_date (date) – The date the flight starts being shown
end_date (date) – The estimated end date for the flight
created (date) – The date the flight was created
modified (date) – The date the flight was last modified

Advertisement APIs

class adserver.api.views.AdvertisementViewSet(**kwargs)[source]

Advertisement API calls.

GET /api/v1/advertisers/(str: advertiser_slug)/flights/(str: flight_slug)/advertisements/

Return a list of the flight’s advertisements the user has access to

Response JSON Object:

count (int) – The number of advertisements returned
next (string) – A URL to the next page of advertisements (if needed)
previous (string) – A URL to the previous page of advertisements (if needed)
results (array) – An array of advertisement results (see details call)

GET /api/v1/advertisers/(str: advertiser_slug)/flights/(str: flight_slug)/advertisements/(str: advertisement_slug)/

Return a specific advertisement. The fields returned are the same as the advertisements in the advertiser report API.

Response JSON Object:

name (string) – The name of the ad (not shown to users)
slug (string) – A slug identifying the ad
text (string) – The text of the ad (only set on old ads)
headline (string) – The headline at the beginning of the ad
content (string) – The main text of the ad
cta (string) – The call to action at the end of the ad
image (string) – A URL of the ad’s image (if any)
link (string) – The URL of the ad’s landing page
ad_types (array) – The names of this ad’s ad types
live (bool) – Whether the ad is enabled
created (date) – The date the ad was created
modified (date) – The date the ad was last modified