knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "README-" )
Interact with the Open Ad Stream (OAS) API from R
Features:
devtools::install_github('ReportMort/roas')
library('roas')
There is a set of 8 package options. These may need to be configured
based on your API instance. Set them using the options()
function.
# defaults roas.account = NULL roas.username = NULL roas.password = NULL roas.url_endpoint = "https://openadstream18.247realmedia.com/oasapi/OaxApi" roas.namespace = "https://api.oas.tfsm.com/" roas.service_name = "OaxApiService" roas.port_name = "OaxApiPort" roas.method_name = "OasXmlRequest" # setting authentication parameters options(roas.account = "myaccountname") options(roas.username = "myusername") options(roas.password = "mypassword") # setting a new endpoint to use for requests options(roas.url_endpoint = "https://openadstream11.247realmedia.com/oasapi/OaxApi")
The functions are named to mimic each OAS request action ('Add', 'List', 'Update', 'Delete', 'Read', 'Copy', 'Upload', 'Run Live', 'Reports', 'Inventory'), but many of these actions are reserved words, so the functions are named {oas_action}(). For example, running the 'List' action is done with the function oas_list().
Build credentials for authorization and pass them into subsequent request function calls. The credentials can be reused as many times as needed.
my_credentials <- oas_build_credentials('myaccount', 'myusername', 'mypassword')
List all sites in your account.
list_of_sites <- oas_list(credentials=my_credentials, request_type='Site')
List all pages with a particular search criteria.
list_w_criteria <- oas_list(credentials=my_credentials, request_type='Page', search_criteria_attributes = c(pageSize=100), search_criteria=list(newXMLNode("Domain", "mySite"), newXMLNode("Url", "001"), newXMLNode("SectionId", "Ar%ves"), newXMLNode("SiteId", "ApiSite"), newXMLNode("Description", "My Page"), newXMLNode("LocationKey", "7"), newXMLNode("WhenCreated", attrs = c(condition = "GT"), '2014-12-31'), newXMLNode("WhenModified", attrs = c(condition = "GT"), '2013-12-31')))
List DMA Codes
dma_codes <- oas_list_code(credentials=my_credentials, code_type='DMA')
List City Codes for the US
search_criteria_node <- NULL country_criteria_node <- newXMLNode("Country", parent = search_criteria_node) country_code_node <- newXMLNode("Code", "US", parent = country_criteria_node) us_city_codes <- oas_list_code(credentials=my_credentials, code_type='City', search_criteria_attributes = c(pageSize="20000"), search_criteria=list(country_code_node))
Retrieve all available fields on a site and a particular campaign
site_details <- oas_read(credentials=my_credentials, request_type='Site', id='www.mysite.com') campaign_details <- oas_read(credentials=my_credentials, request_type='Campaign', id='one_campaign_id')
Add a new Advertiser
adver_add <- oas_add(credentials=my_credentials, request_type='Advertiser', update_data=list(addChildren( newXMLNode('Advertiser'), list(newXMLNode('Id', 'MyAdvertiserId'), newXMLNode('ContactTitle', 'new Title')))))
Update an Advertiser or Update a Campaign
adver_update <- oas_update(credentials=my_credentials, request_type='Advertiser', update_data=list(addChildren( newXMLNode('Advertiser'), list(newXMLNode('Id', 'thisadvertiserid'), newXMLNode('ContactTitle', 'new Title'))))) campaign_update <- oas_update(credentials=my_credentials, request_type='Campaign', update_data=list(addChildren( newXMLNode('Overview'), list(newXMLNode('Id', 'myExistingCampaignId'), newXMLNode('Status', 'L'), addChildren( newXMLNode('CompetitiveCategories'), list(newXMLNode('CompetitiveCategoryId','Airlines'), newXMLNode('CompetitiveCategoryId','Travel')))))))
Copy an existing campaign
campgn_copy <- oas_copy(credentials=credentials, request_type='Campaign', copy_data=list(newXMLNode('Id', 'oldCampaignId'), newXMLNode('NewId', 'newCampaignId'), newXMLNode('CopyCreatives', 'Y'), newXMLNode('CopyNotifications', 'Y'), newXMLNode('CopyScheduling', 'Y'), newXMLNode('CopyTargeting', 'Y'), newXMLNode('CopyBilling', 'Y'), newXMLNode('CopyPages', 'Y'), newXMLNode('CopySiteTiers', 'Y'), newXMLNode('CopyConversionProcesses', 'Y')))
Use the Test Live Campaigns Operation
tlc_details <- oas_run_live(credentials=my_credentials, action='TestLiveCampaigns')
Retrieve a template executive summary report on campaign delivery
campaign_delivery <- oas_report(credentials=my_credentials, report_type='Campaign Delivery', report_name='Executive Summary', start_date='2015-09-01', end_date='2015-09-30')
Retrieve an inventory forecast for all sites
# Note that start and end dates must be greater than or equal to # Sys.Date() otherwise forecast reprots will return a 0 row data.frame overview <- oas_basic_inventory(credentials=my_credentials, report_type='Overview', report_name='All Sites Forecast', start_date='2015-12-01', end_date='2015-12-31')
Retrieve booked inventory based on two keywords (Kw1, Kw2) for a particular campaign on a site
booked <- oas_search_inventory(credentials=my_credentials, report_type='KeywordBooked', report_name='Campaign Targets', keywords='Kw1,Kw2', campaign_id=c('Test_Campaign'), site_domain=c('www.mysite.com'), start_date='2015-12-01', end_date='2015-12-31')
Retrieve an inventory forecast for two positions on the "Books" section broken down by DMA
section_geo <- oas_geo_inventory(credentials=my_credentials, report_type='Section', report_geo='DMA', report_outlook='Forecast', id='Books', max_row="20000", position=c('Bottom', 'Bottom1'), start_date='2015-12-01', end_date='2015-12-31')
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.