Adthena API
Any instance where an entry in the below configuration has a leading $ represents a parameter that needs to be replaced with a static value.
Parameters in this document:
- $api_key - The API Key will provide access to the Adthena API. To get an API Key, you will need to request one by emailing
support@adthena.com.- Note: You will need a different API Key for each Adthena account/location, so be sure to receive and document each key if you have multiple accounts/locations.
- $account_id - The Account ID is a unique identifier for your Adthena account. If you do not know your Account ID value, you can request this by emailing
support@adthena.com. - $resource_name - The Resource Name represents the name of the resource to be appended and used as part of the Destination Table name. The value that should be used here can be found in the API Resources table below.
- $endpoint - The Endpoint represents the data that you would like to ingest into Panoply from the Adthena API. The value that should be used here can be found in the API Resources table below.
- $primary_key - Primary keys are used to ensure the uniqueness of the rows in a table. The Primary Key is comprised of one or more columns that can be used to identify the row in the data warehouse. The process guarantees that no two rows have the same value in their primary key. The value that should be used here can be found in the API Resources table below.
- $period_start - The Start Date of the data that you would like to receive, given in
yyyy-mm-DDformat. If this date is 30 days in the past, data by week (Sunday-Saturday) will be returned instead of data by day. If this date is more than 13 months in the past, data by month will be returned. - $period_end - The End Date of the data that you would like to receive, given in
yyyy-mm-DDformat. - $attribution_window - The Attribution Window represents the number of days in which an ad publisher can claim credit for a click or impression that leads to a conversion. This can impact some of the metric values in terms of which ad they apply to, and which day they are considered occurring on. This parameter should always be set as a negative number, and at least have a value of -1.
- $incremental_starting_value - The Incremental Starting Value represents the earliest date that data should be collected for, given in
yyyy-mm-DDformat. For example, if you would like your historical data to go back to the start of 2021, this value would be set to2021-01-01.
API Resources
For a list of API Resources available for Adthena, please refer to the list of endpoints found below:
| Resource | $resource_name | $endpoint | $primary_key |
|---|---|---|---|
| Average CPC | average_cpc | average-cpc-trend/all | {competitor}-{data_date} |
| Average Position | average_position | average-position-trend/all | {competitor}-{data_date} |
| Frequency | frequency | frequency-trend/all | {competitor}-{data_date} |
| Google Shopping | google_shopping | top-pla/all | {adid} |
| Infringements | infringements | infringement/all | {competitor}-{infringementid}-{date}-{time} |
| Market Share | market_share | market-share/all | {competitor} |
| Market Share for Groups and Locations | market_share_for_groups_locations | market-share/groups-and-locations | {competitor}-{locationname}-{groupname}-{device}-{adtype} |
| Search Term Detail | search_term_detail | search-term-detail/all | {searchterm} |
| Search Term Opportunities | search_term_opportunities | search-term-opportunities/all | {searchterm} |
| Share of Clicks | share_of_clicks | share-of-clicks-trend/all | {competitor}-{data_date} |
| Share of Impression | share_of_impression | impression-share-trend/all | {competitor}-{data_date} |
| Share of Spend | share_of_spend | share-of-spend-trend/all | {competitor}-{data_date} |
| Top Ads | top_ads | top-adverts/all | {adid} |
Connector configuration
- Base url: https://api.adthena.com/wizard/$account_id / $endpoint
- Method: GET
- URL Parameters: periodstart={periodstart}&periodend={periodend}
In addition to the above values (periodstart and periodend), additional URL Parameters can be provided as part of the URL Parameters entry to further specify the API call and impact the response that is ultimately ingested into Panoply. For a full list of these additional URL Parameters, see the Query Parameters section under the Resource that you are ingesting, with each Resource page being linked above in the API Resources section.
Destination Table naming convention is ultimately up to you as the data owner. One common structure used for this API is adthena_$resource_name.
Authorization
- Authorization: API Key
- Key: adthena-api-key
- Value: $api_key
- Add to: Headers
Variables
- Variables
| Variable name | Variable value |
|---|---|
| periodstart | $period_start |
| periodend | $period_end |
When initially collecting historical data, set the periodstart and periodend variables to capture back to the start of data you'd like to ingest. For example, if you would like to collect back to the start of 2021 through the current date, the parameters would be the following:
| Variable name | Variable value |
|---|---|
| periodstart | 2021-01-01 |
| periodend | <<date_format(utcnow(),'%Y-%m-%d')>> |
Upon completion of the backfill of data, you can set the periodstart and periodend parameters to the following values in order to capture incremental data moving forward:
| Variable name | Variable value |
|---|---|
| periodstart | <<date_format(date_add({incval}, 'days', $attribution_window),'%Y-%m-%d')>> |
| periodend | <<date_format(utcnow(),'%Y-%m-%d')>> |
Advanced Settings
For the Average CPC, Average Position, Frequency, Share of Clicks, Share of Impression and Share of Spend resources, this value should be set to Data. For all other resources this will be left empty.
- Primary Key: $primary_key
- Incremental Key:
Column name Column value lastTimeSucceed $incremental_starting_value - Incremental value date format: yyyy-dd-MM
When entering a column value to the incremental key feature, you will need to use the following format: yyyy-dd-MM. For example, if you'd like to start ingesting data from January 1, 2021 forward, set the column value to 2021-01-01 for the initial collection. Upon success, Panoply will automatically update this value to collect only new data, so you will not need to adjust this value moving forward.