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