##Summary Multiple products (AdStage, Automate, Report) are built on the AdStage API. We are now making the API available for third parties who wish to use the API to build applications that need to consume data from or interact with the major ad networks: Google, Bing, Facebook, LinkedIn and Twitter.
##Access Levels
There are two levels of access.
Read Only access allows API consumers to request:
- lists of advertising entities (e.g. campaings, ad groups/set, ads, keywords)
- network performance data (e.g. spend, clicks, impressions)
- metadata describing the advertising entities (e.g. Campaign status, objective type, ad name, ad image)
Read Only access is commonly used to provide data to machine learning algos, dashboarding tools, or niche marketing tools.
Read/Write access allows API consumers to:
- update the status of an advertising entity (e.g. Pause Campaign, Activate Ad Group, Delete Ad)
- change campaign and ad group/set budgets.
- change bids of advertising entities. (e.g. Google keyword bids, Facebook Ad Set bids, LinkedIn Campaign Bids)
Read/Write access is commonly used by bidding tools, budget pacing tools, or automation tools.
##AdStage API Notifications
Be sure to subscribe to http://status.adstage.io/ for alerts on any issues we're having with the API
This is a request/response example to pull a list of ads from adstage with data for a provided date range.
Possible query parameters:
- statuses - By default, the endpoint will filter out deleted entities (
statuses=all_visible
). To change this to include deleted you can usestatuses=all_with_deleted
- limit - page size limit, it is recommended this number does not exceed 250
- offset - page offset, it is recommended you use the previous and next links described below for pagination
- order - default
desc
, which will sort the sort_by field in descending order. Useasc
for ascending order - sort_by - default
clicks
, which metric or metadata field to sort_by
AdStage's API uses HAL to structure responses - for the HAL specification, see: http://stateless.co/hal_specification.html. You may be able to find standard libraries for more easily parsing/interacting with HAL data: https://github.com/mikekelly/hal_specification/wiki/Libraries.
Make sure to request data in JSON or HAL format (Use Accept header to request application/json or application/hal+json)
All metrics endpoints have the same basic structure which is used to build the tables visible within the AdStage interface (a lot of the metadata within a response is information to help build those tables):
Embedded data:
_embedded["adstage:metrics"]
- [array] Each item represents a row of data in the report. Important subkeys are:meta
- metadata for the given entity, useful subkeys include:headline
destination_url
campaign_name
ad_group_name
remote_campaign_id
(The unique identifier the advertising network assigned to the campaign)remote_ad_id
(The unique identifier the advertising network assigned to the ad)remote_ad_group_id
(The unique identifier the advertising network assigned to the ad group)text
/post_text
(Text of a promoted tweet/other social post)currency_code
data
- metrics for the entity, useful subkeys include:clicks
(note that some networks may addiitionally break this number into several submetrics as well, twitter has:promoted_tweet_timeline_clicks
,promoted_tweet_timeline_url_clicks
, andpromoted_tweet_search_clicks
, along with many other click types)impressions
spend
(returned as a raw number in displayable units for the currency_code, forUSD
, this10.09999
is$10.10
)ctr
(computed byclicks/impressions
)
_embedded["adstage:metrics/totals"]
- [array] Each item represents totals across the data set, differentiated byname
. Name can be "filtered", "overall" and "page", overall being everything, filtered being totals for everything except filtered entities (by default, a filter is applied to remove deleted entities), and page being totals for the current page._embedded["adstage:table_column"]
- [array] Each item represents metadata about the type of column for display purposes
Links:
_links["next"]
- URL info to advance to the next page of data - this is the preferred method of pagination. The next link will not exist at the last page of information._links["prev"]
- URL info to advance to the previous page of data - this is the preferred method of pagination. The previous link will not exist at the first page of information.
Possible error status codes:
- 422 - Indicates invalid input
- 402 - Indicates AdStage account has expired/requires payment to continue
- 401 - Indicates the token is no longer valid
- 500 - General server error, but most likely cause is an importing error that we must resolve on our side - if encountered, report to support+api@adstage.io with URL to reproduce and we'll try to fix as quickly as possible
- 503 - Timeout - indicates too much data was selected to be returned in a reasonable amount of time - contact support+api@adstage.io and we'll help you implement per-account ads lists.
This API was created mainly for frontend use and includes a lot of extra metadata that is probably not necesary for exporting to external data stores, as such, performance may be limited, and can be affected by our overall platform response times. For best results, attempting to pull data at off-peak hours (8:00PM PST to 3:00AM PST) is recommended. Limit request usage by requesting one page at a time - during trial period we are shooting for a soft query limit of up to 10 requests per minute, but may request you scale back usage if it causes too many issues. We are experimenting with better bulk export options suited for automated requests.
Contact support@adstage.io for details on how to get a token.