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 0000000000000000000000000000000000000000Where 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 thead_types
- ad_types (string) – A
|
delimited string of ad types. The number and order must correspond to thediv_ids
. - priorities (string) – An optional
|
delimited string of priorities for different ad types. The number and order matter, applying todiv_ids
andad_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|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
- 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
, optionalheadline
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" }
- publisher (string) – Required. The slug of the publisher.
If using the ethical-ad-client, this comes from
-
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
, andpriorities
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
-