Interact with the Open Ad Stream (OAS) API from R
Features:
- oas_build_credentials(): One-time create authentication credentials and re-use
- oas_list(): List OAS Objects into data.frame
- oas_read(): Read all fields on an OAS Object
- oas_add(): Add new OAS Objects
- oas_update(): Update fields on an OAS Object
- oas_copy(): Copy an OAS Object (Campaigns and Creative Targets Only)
- oas_run_live(): Perform 3 Run Live Campaign Operations
- oas_report(): Run over 800 different template reports
- Campaign Delivery
- Account Revenue
- More...
- oas_basic_inventory(): Run inventory reports over 18 different types
- Site
- Section
- Campaign
- More...
- oas_search_inventory(): Run inventory reports based on keyword search terms
- oas_geo_inventory(): Run Site or Secton inventory across geography types
- Country
- State
- Postal Code
- DMA
- More...
- oas_zone_inventory(): Run zone inventory reports for a site
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')