Install roas Library

devtools::install_github("StevenMMortimer/roas")

Setup and Authenticate

The only required authentication parameters are the Account, Username, and Password for the OAS instance you’d like to access. There is another option if you have a different URL endpoint.

library(roas)
options(stringsAsFactors = FALSE)

# setting authentication parameters
options(roas.account = "myaccountname")
options(roas.username = "myusername")
options(roas.password = "mypassword")

# setting a new endpoint to use for requests
# only required if you need to
options(roas.url_endpoint = "https://openadstream11.247realmedia.com/oasapi/OaxApi")

Authenticate with oas_build_credentials()

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')

Listing OAS Objects

# list all of the sites in my account
list_my_sites <- oas_list(credentials = my_credentials, 
                          request_type = 'Site')

Here is a more complicated list example that will list all pages from the “mySite” domain and have a URL containing “001”, but they must be from the section matching the wildcard “Ar%ves” and created after Dec. 31st, 2016 and modified after Jan.  31st, 2017. This example is very specific, but we’re using this example to show how you can specify multiple difference criteria all at once to narrow down your resultset.

my_criteria <- list(newXMLNode("Domain", "mySite"), 
                    newXMLNode("Url", "001"), 
                    newXMLNode("SectionId", "Ar%ves"), 
                    newXMLNode("WhenCreated", 
                               attrs = c(condition = "GT"), 
                               '2016-12-31'), 
                    newXMLNode("WhenModified", 
                               attrs = c(condition = "GT"), 
                               '2017-01-31')
                    ) 
list_w_criteria <- oas_list(credentials = my_credentials, 
                            request_type = 'Page',
                            search_criteria = my_criteria)

The OAS system also contains codes for enumerated fields. For example, there is a finite list of Designated Market Areas (DMAs) that your campaigns can target. Each DMA has a code that corresponds to a longer, more descriptive name. The campaigns only show the code, so you’ll need this list of DMA codes to figure out more descriptive names of the targeting that your campaign is implementing.

dma_codes <- oas_list_code(credentials = my_credentials, 
                           code_type = 'DMA')

Reading an OAS Object

OAS objects are uniquely identified by their Id. Typically, you use the oas_list() function to pull down a list and figure out the Ids of objects you’d like to read. Once you’ve identified those individual objects you can use the oas_read() function to retrieve all available fields the object. In the examples below you can see how we pull back the details on a site with the Id: “www.mysite.com” and we also pull back details on a campaign with the Id: “one_campaign_id”.

# details for "www.mysite.com"
site_details <- oas_read(credentials = my_credentials, 
                         request_type ='Site', 
                         id = 'www.mysite.com')
                             
# details for "one_campaign_id"                             
campaign_details <- oas_read(credentials = my_credentials, 
                             request_type = 'Campaign', 
                             id = 'one_campaign_id')

Running Reports

The OAS API supports over 800 different template reports. These reports cover a wide range of things, such as, Campaign Delivery, Account Revenue, and many more. You must specify the report_type, report_name, and a date range. You can view all the different report types and names by running data(available_reports). Simply pick an item from the list and plug its type and name into the oas_report() function.

data(available_reports)

# List out all the Campaign Delivery reports
available_reports[available_reports$report_type == 'Campaign Delivery', ]

# 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 = '2016-01-01', 
                                end_date = '2016-12-31')

Getting Inventory Forecasts

The OAS API supports inventory checking on various levels: Basic, Search, Geography. For example, if you need to see the available inventory for a particular search keyword, then you can do that by using the function oas_search_inventory(). If you need to see the available inventory for a particular geography, then use oas_geo_inventory(). Note, these functions may take awhile to run and may only support simplistic pulls that may need to be combined or averaged to come up with a reasonable estimate of available inventory. These issues are related to how the OAS API functions and not how this package operates. This package is only a wrapper to more easily retrieve the data from OAS. This is no intermediate logic.

# Retrieve an inventory forecast for all sites
# Note that start and end dates must be greater than or equal to 
# Sys.Date() otherwise forecast reports will return a 0 row data.frame
overview <- oas_basic_inventory(credentials = my_credentials, 
                                report_type = 'Overview', 
                                report_name = 'All Sites Forecast',
                                start_date = '2020-01-01', 
                                end_date = '2020-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 = 'Test_Campaign',
                               site_domain = 'www.mysite.com',
                               start_date = '2020-01-01', 
                               end_date = '2020-12-31')