NAV
json xml csv

Introduction

Welcome to the Adthena API! You can use our API to access Adthena API endpoints, in order to programmatically retrieve data for your Adthena domain(s).

Use the “json”, “xml” and “csv” tabs on the right to show example response data in those formats.

FAQ

How do I access the API?

Accessing the API requires you to have the unique authentication key for each Adthena domain. Speak to your Adthena contact for further information.

Do we stream the response?

Yes. We recommend that you use a streaming client to handle responses from the API as data sets can be large. This will help avoid the issues associated with processing large amounts of data such as out of memory exceptions or application crashes.

Is there a way to test my credentials?

One simple way is to use a free tool such as onlinecurl.com

  1. Enter your URL beginning https://
  2. Click Add Option, select Header, enter adthena-api-key:my-api-key
  3. Click Start Your Curl

At what time can I download yesterday’s data?

Yesterday’s data is available by 9am local time for that country

How can I better understand the data each End Point is returning and how Parameters affect the data?

Try our Knowledge Base, which has descriptions and screengrabs. Alternatively contact us: support@adthena.com.

Why do I not get daily data returned when my periodstart and periodend dates are the same?

Adthena stores data daily for 30 days, so if periodstart date is with last 30 days then you will get daily data returned. If your periodstart date is older then 30 days then your call will return weekly data (Sunday-Saturday) and if your periodstart date is older than 13 months then your call will return monthly data.

Why do my calls return identical data even though I am changing my periodstart and periodend dates?

Adthena stores data daily for 30 days, so if periodstart date is older than last 30 days then you will get weekly daily data returned, even if your periodend date is the same date. So requesting data for Tues, Wed, Thurs of the same week 3 months ago will return the same weekly data for each request.

I discovered an issue what shall I do?

Email the details to support@adthena.com and we will investigate

Authentication

To authorize, use this code:

curl -i "api_endpoint_here" -H "adthena-api-key: my-api-key"

Make sure to replace my-api-key with your API key.

Adthena uses API keys to allow access to the API. You can register here for a new Adthena API key.

Adthena expects for the API key to be included in all API requests to the server in a header that looks like the following:

adthena-api-key: my-api-key

Infringements

The response has the following structure:

[{
  "RuleName" : "rulename",
  "InfringementId" : "e6e85566-5a25-43f8-aad5-96181d9ld955",
  "Date" : "17/10/17",
  "Time" : "20:01:19",
  "SearchTerm" : "search term",
  "Position" : "T1",
  "Competitor" : "competitor.com",
  "Title" : "First ad title",
  "Description" : "First ad description",
  "DisplayUrl" : "competitor.com",
  "DestinationUrl" : "http://competitor.com/ad",
  "AdClickUrl" : "https://adclickurl.com/ad",
  "EvidenceLink" : "http://application.adthena.com/#report-settings/id?country=UK&scrapeid=e6e85566-5a25-43f8-aad5-96181d9ld955&infringementtime=2017-10-17T20:1:19&infringementdate=2017-10-17"
},
{
  "RuleName" : "rulename",
  "InfringementId" : "e6e85566-5a25-43f8-aad5-96181d9ld6w6",
  "Date" : "20/10/17",
  "Time" : "10:00:34",
  "SearchTerm" : "search term 2",
  "Position" : "B1",
  "Competitor" : "competitor2.com",
  "Title" : "Second ad title",
  "Description" : "Second ad description",
  "DisplayUrl" : "competitor2.com",
  "DestinationUrl" : "http://competitor2.com/ad",
  "AdClickUrl" : "https://ad2clickurl.com/ad",
  "EvidenceLink" : "http://application.adthena.com/#report-settings/id?country=UK&scrapeid=e6e85566-5a25-43f8-aad5-96181d9ld6w6&infringementtime=2017-10-20T10:0:34&infringementdate=2017-10-20"
}]
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Infringements>
  <Item>
    <RuleName>rulename</RuleName>
    <InfringementId>e6e85566-5a25-43f8-aad5-96181d9ld955</InfringementId>
    <Date>17/10/17</Date>
    <Time>20:01:19</Time>
    <SearchTerm>search term</SearchTerm>
    <Position>T1</Position>
    <Competitor>competitor.com</Competitor>
    <Title>First ad title</Title>
    <Description>First ad description</Description>
    <DisplayUrl>competitor.com</DisplayUrl>
    <DestinationUrl>http://competitor.com/ad</DestinationUrl>
    <AdClickUrl>https://adclickurl.com/ad</AdClickUrl>
    <EvidenceLink>"http://application.adthena.com/#report-settings/id?country=UK&scrapeid=e6e85566-5a25-43f8-aad5-96181d9ld955&infringementtime=2017-10-17T20:1:19&infringementdate=2017-10-17"</EvidenceLink>
  </Item>
  <Item>
    <RuleName>rulename</RuleName>
    <InfringementId>e6e85566-5a25-43f8-aad5-96181d9ld6w6</InfringementId>
    <Date>20/10/17</Date>
    <Time>10:00:34</Time>
    <SearchTerm>search term 2</SearchTerm>
    <Position>B1</Position>
    <Competitor>competitor2.com</Competitor>
    <Title>Second ad title</Title>
    <Description>Second ad description</Description>
    <DisplayUrl>competitor2.com</DisplayUrl>
    <DestinationUrl>http://competitor2.com/ad</DestinationUrl>
    <AdClickUrl>https://ad2clickurl.com/ad</AdClickUrl>
    <EvidenceLink>"http://application.adthena.com/#report-settings/id?country=UK&scrapeid=e6e85566-5a25-43f8-aad5-96181d9ld6w6&infringementtime=2017-10-20T10:0:34&infringementdate=2017-10-20"</EvidenceLink>
  </Item>
<Infringements>
RuleName,InfringementId,Date,Time,SearchTerm,Position,Competitor,Title,Description,DisplayUrl,DestinationUrl,AdClickUrl,EvidenceLink
"rulename","e6e85566-5a25-43f8-aad5-96181d9ld955",17/10/17,20:01:19,search term,T1,competitor1.com,"First ad title","First ad description","competitor.com",http://competitor.com/ad,"https://adclickurl.com/ad","http://application.adthena.com/#report-settings/id?country=UK&scrapeid=e6e85566-5a25-43f8-aad5-96181d9ld955&infringementtime=2017-10-17T20:1:19&infringementdate=2017-10-17"
"rulename","e6e85566-5a25-43f8-aad5-96181d9ld6w6",20/10/17,10:00:34,search term 2,B1,competitor2.com,"Second ad title","Second ad description","competitor2.com",http://competitor2.com/ad,"https://ad2clickurl.com/ad","http://application.adthena.com/#report-settings/id?country=UK&scrapeid=e6e85566-5a25-43f8-aad5-96181d9ld6w6&infringementtime=2017-10-20T10:0:34&infringementdate=2017-10-20"

Curl Request

curl -i 'https://api.adthena.com/wizard/{id}/infringement/all' -H 'adthena-api-key: my-api-key' -H 'accept: application/json'

HTTP Request

GET /wizard/{id}/infringement/all HTTP/1.1
Host: api.adthena.com
Adthena-api-key: my-api-key
Accept: application/json

Market Share

The response has the following structure:

[{
    "Competitor": "competitor1.com",
    "SearchTerms": 49,
    "EstimatedImpressions": 3421,
    "AveragePosition": 2.1,
    "ShareOfClicks": "16.17%",
    "ShareOfSpend": "15.24%"
}, {
    "Competitor": "competitor2.com",
    "SearchTerms": 13,
    "EstimatedImpressions": 2395,
    "AveragePosition": 3.1,
    "ShareOfClicks": "12.97%",
    "ShareOfSpend": "14.12%"
}]
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DesktopMarketShare>
  <Item>
    <Competitor>competitor1.com</Competitor>
    <SearchTerms>49</SearchTerms>
    <EstimatedImpressions>3421</EstimatedImpressions>
    <AveragePosition>2.1</AveragePosition>
    <ShareOfClicks>16.17%</ShareOfClicks>
    <ShareOfSpend>15.24%</ShareOfSpend>
  </Item>
  <Item>
    <Competitor>competitor2.com</Competitor>
    <SearchTerms>13</SearchTerms>
    <EstimatedImpressions>2395</EstimatedImpressions>
    <AveragePosition>3.1</AveragePosition>
    <ShareOfClicks>12.97%</ShareOfClicks>
    <ShareOfSpend>14.12%</ShareOfSpend>
  </Item>
</DesktopMarketShare>
Competitor,SearchTerms,EstimatedImpressions,AveragePosition,ShareOfClicks,ShareOfSpend
competitor1.com,49,3421,2.1,"16.17%","15.24%"
competitor2.com,13,2395,3.1,"12.97%","14.12%"

Curl Request

curl -i 'https://api.adthena.com/wizard/{id}/market-share/all?periodstart=2016-08-17&periodend=2016-08-18' -H 'adthena-api-key: my-api-key' -H 'accept: application/json'

HTTP Request

GET /wizard/{id}/market-share/all?periodstart=2016-08-17&periodend=2016-08-18 HTTP/1.1
Host: api.adthena.com
Adthena-api-key: my-api-key
Accept: application/json

Market Trends

The response has the following structure:

[{
  "Competitor" : "competitor1.com",
  "Data" : [{
    "Date" : "2016-08-17",
    "Value" : 0.20252793391991963
  }, {
    "Date" : "2016-08-18",
    "Value" : 0.17226717371649275
  }]
}, {
  "Competitor" : "competitor2.com",
  "Data" : [{
    "Date" : "2016-08-17",
    "Value" : 0.1251964689111161
  }, {
    "Date" : "2016-08-18",
    "Value" : 0.1525691616591276
  }]
}]
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ShareOfClicksTrends>
  <Item>
    <Competitor>competitor1.com</Competitor>
    <Point>
      <Date>2016-08-17</Date>
      <Value>0.20252793391991963</Value>
    </Point>
    <Point>
      <Date>2016-08-18</Date>
      <Value>0.17226717371649275</Value>
    </Point>
  </Item>
  <Item>
    <Competitor>competitor2.com</Competitor>
    <Point>
      <Date>2016-08-17</Date>
      <Value>0.1251964689111161</Value>
    </Point>
    <Point>
      <Date>2016-08-18</Date>
      <Value>0.1525691616591276</Value>
    </Point>
  </Item>
</ShareOfClicksTrends>
Competitor,2016-08-17,2016-08-18
competitor1.com,0.20252793391991963,0.17226717371649275
competitor2.com,0.1251964689111161,0.1525691616591276

There are six different Market Trend reports and each is called from a different API endpoint:

Report Type Endpoint
Market Trends - Share of Clicks /share-of-clicks-trend
Market Trends - Share of Impressions /impression-share-trend
Market Trends - Frequency /frequency-trend
Market Trends - Average Position /average-position-trend
Market Trends - Share of Spend /share-of-spend-trend
Market Trends - Average CPC /average-cpc-trend

Curl Request

curl -i 'https://api.adthena.com/wizard/{id}/share-of-clicks-trend/all?periodstart=2016-08-17&periodend=2016-08-18' -H 'adthena-api-key: my-api-key' -H 'accept: application/json'

HTTP Request

GET /wizard/{id}/share-of-clicks-trend/all?periodstart=2016-08-17&periodend=2016-08-18 HTTP/1.1
Host: api.adthena.com
Adthena-api-key: my-api-key
Accept: application/json

Search Term Detail

The response has the following structure:

[{
  "SearchTerm": "my first search term",
  "Competitors": 12,
  "EstimatedImpressions": 46455,
  "EstimatedClicks": 253,
  "AveragePosition": 3.5504277823493,
  "TopCompetitor": "competitor1.com",
  "MinCPC": 2.8611486814916,
  "MaxCPC": 4.9838882334564
},
{
  "SearchTerm": "my second search term",
  "Competitors": 10,
  "EstimatedImpressions": 157446,
  "EstimatedClicks": 176,
  "AveragePosition": 3.3850404530201,
  "TopCompetitor": "competitor2.com",
  "MinCPC": 3.8769243528258,
  "MaxCPC": 7.7723931232345
}]
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SearchTermDetail>
  <Item>
    <SearchTerm>my first search term</SearchTerm>
    <Competitors>12</Competitors>
    <EstimatedImpressions>46455</EstimatedImpressions>
    <EstimatedClicks>253</EstimatedClicks>
    <AveragePosition>3.5504277823492885</AveragePosition>
    <TopCompetitor>competitor1.com</TopCompetitor>
    <MinCPC>2.8611486814916</MinCPC>
    <MaxCPC>4.9838882334564</MaxCPC>
  </Item>
  <Item>
    <SearchTerm>my second search term</SearchTerm>
    <Competitors>10</Competitors>
    <EstimatedImpressions>157446</EstimatedImpressions>
    <EstimatedClicks>176</EstimatedClicks>
    <AveragePosition>3.3850404530201317</AveragePosition>
    <TopCompetitor>competitor2.com</TopCompetitor>
    <MinCPC>3.8769243528258</MinCPC>
    <MaxCPC>7.7723931232345</MaxCPC>
  </Item>
</SearchTermDetail>
SearchTerm,Competitors,EstimatedImpressions,EstimatedClicks,AveragePosition,TopCompetitor,MinCPC,MaxCPC
"my first search term",12,46455,253,3.5504277823492885,competitor1.com,2.8611486814916,4.9838882334564
"my second search term",10,157446,176,3.3850404530201317,competitor2.com,3.8769243528258,7.7723931232345

Curl Request

curl -i 'https://api.adthena.com/wizard/{id}/search-term-detail/all?periodstart=2016-08-17&periodend=2016-08-18' -H 'adthena-api-key: my-api-key' -H 'accept: application/json'

HTTP Request

GET /wizard/{id}/search-term-detail/all?periodstart=2016-08-17&periodend=2016-08-18 HTTP/1.1
Host: api.adthena.com
Adthena-api-key: my-api-key
Accept: application/json

Search Term Opportunities

The response has the following structure:

[{
  "SearchTerm": "my first search term",
  "Competitors": 12,
  "EstimatedClicks": 253,
  "AveragePosition": 3.5504277823493,
  "TopCompetitor": "competitor1.com",
  "MinCPC": 2.8611486814916,
  "MaxCPC": 4.9838882334564
},
{
  "SearchTerm": "my second search term",
  "Competitors": 10,
  "EstimatedClicks": 176,
  "AveragePosition": 3.3850404530201,
  "TopCompetitor": "competitor2.com",
  "MinCPC": 3.8769243528258,
  "MaxCPC": 7.7723931232345
}]
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SearchTermOpportunities>
  <Item>
    <SearchTerm>my first search term</SearchTerm>
    <Competitors>12</Competitors>
    <EstimatedClicks>253</EstimatedClicks>
    <AveragePosition>3.5504277823492885</AveragePosition>
    <TopCompetitor>competitor1.com</TopCompetitor>
    <MinCPC>2.8611486814916</MinCPC>
    <MaxCPC>4.9838882334564</MaxCPC>
  </Item>
  <Item>
    <SearchTerm>my second search term</SearchTerm>
    <Competitors>10</Competitors>
    <EstimatedClicks>176</EstimatedClicks>
    <AveragePosition>3.3850404530201317</AveragePosition>
    <TopCompetitor>competitor2.com</TopCompetitor>
    <MinCPC>3.8769243528258</MinCPC>
    <MaxCPC>7.7723931232345</MaxCPC>
  </Item>
</SearchTermOpportunities>
SearchTerm,Competitors,EstimatedClicks,AveragePosition,TopCompetitor,MinCPC,MaxCPC
"my first search term",12,253,3.5504277823492885,competitor1.com,2.8611486814916,4.9838882334564
"my second search term",10,176,3.3850404530201317,competitor2.com,3.8769243528258,7.7723931232345

Curl Request

curl -i 'https://api.adthena.com/wizard/{id}/search-term-opportunities/all' -H 'adthena-api-key: my-api-key' -H 'accept: application/json'

HTTP Request

GET /wizard/{id}/search-term-opportunities/all HTTP/1.1
Host: api.adthena.com
Adthena-api-key: my-api-key
Accept: application/json

Top Adverts

The response has the following structure:

[{
  "AdId": "20c340ec-7c42-4972-bc96-99149c80f023",
  "Competitor": "competitor1.com",
  "Title": "First ad title",
  "Description": "First ad Description",
  "DisplayUrl": "www.competitor1.com/ad",
  "EstimatedImpressions": 10715,
  "AveragePosition": "3.5",
  "BestPosition": "T1",
  "SearchTerms": 6,
  "Frequency": "86.39%",
  "DisplayLength": 31,
  "FirstSeen": "2016-08-21",
  "LastSeen": "2016-09-20"
},
{
  "AdId": "3c8772e0-8b51-4557-8409-7a718c0eeb3a",
  "Competitor": "competitor2.com",
  "Title": "Second ad title",
  "Description": "Second ad Description",
  "DisplayUrl": "www.competitor2.com/ad",
  "EstimatedImpressions": 8804,
  "AveragePosition": "3.5",
  "BestPosition": "T1",
  "SearchTerms": 11,
  "Frequency": "66.48%",
  "DisplayLength": 31,
  "FirstSeen": "2016-08-21",
  "LastSeen": "2016-09-20"
}]
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TopDesktopAds>
  <Item>
    <AdId>20c340ec-7c42-4972-bc96-99149c80f023</AdId>
    <Competitor>competitor1.com</Competitor>
    <Title>First ad title</Title>
    <Description>First ad Description</Description>
    <DisplayUrl>www.competitor1.com/ad</DisplayUrl>
    <EstimatedImpressions>10715</EstimatedImpressions>
    <AveragePosition>3.5</AveragePosition>
    <BestPosition>T1</BestPosition>
    <SearchTerms>6</SearchTerms>
    <Frequency>86.39%</Frequency>
    <DisplayLength>31</DisplayLength>
    <FirstSeen>2016-08-21</FirstSeen>
    <LastSeen>2016-09-20</LastSeen>
  </Item>
  <Item>
    <AdId>3c8772e0-8b51-4557-8409-7a718c0eeb3a</AdId>
    <Competitor>competitor2.com</Competitor>
    <Title>Second ad title</Title>
    <Description>Second ad Description</Description>
    <DisplayUrl>www.competitor2.com/ad</DisplayUrl>
    <EstimatedImpressions>8804</EstimatedImpressions>
    <AveragePosition>3.5</AveragePosition>
    <BestPosition>T1</BestPosition>
    <SearchTerms>11</SearchTerms>
    <Frequency>66.48%</Frequency>
    <DisplayLength>31</DisplayLength>
    <FirstSeen>2016-08-21</FirstSeen>
    <LastSeen>2016-09-20</LastSeen>
  </Item>
</TopDesktopAds>
AdId,Competitor,Title,Description,DisplayUrl,EstimatedImpressions,AveragePosition,BestPosition,SearchTerms,Frequency,DisplayLength,FirstSeen,LastSeen
"20c340ec-7c42-4972-bc96-99149c80f023",competitor1.com,"First ad title","First ad description","www.competitor1.com/ad",10715,3.5,T1,6,"86.39%",31,2016-08-21,2016-09-20
"3c8772e0-8b51-4557-8409-7a718c0eeb3a",competitor2.com,"Second ad title","Second ad description","www.competitor2.com/ad",8804,3.5,T1,11,"66.48%",31,2016-08-21,2016-09-20

Curl Request

curl -i 'https://api.adthena.com/wizard/{id}/top-adverts/all' -H 'adthena-api-key: my-api-key' -H 'accept: application/json'

HTTP Request

GET /wizard/{id}/top-adverts/all HTTP/1.1
Host: api.adthena.com
Adthena-api-key: my-api-key
Accept: application/json

Top PLAs

The response has the following structure:

[{
  "CompetitorDomain" : "competitor1.com",
  "Title" : "First ad title",
  "DisplayText" : "First ad display text",
  "Frequency" : 0.11629480124093172,
  "MarketCoverage" : 0.0368013835780703,
  "Price" : "$95.96",
  "FirstAppearance" : "2017-09-16",
  "LastAppearance" : "2017-09-25",
  "Image" : "https://api.adthena.com/static/images/123025b9-892e-ddc7-faa2-e1a8429b0011.jpg",
  "AdId" : "b436fd94-aba2-f635-a1f3-9d9e33ed12p0",
  "AppearanceDuration" : 10
},
{
  "CompetitorDomain" : "competitor2.com",
  "Title" : "Second ad title",
  "DisplayText" : "Second ad display text",
  "Frequency" : 0.01629480124093172,
  "MarketCoverage" : 0.0268013835780703,
  "Price" : "$45.90",
  "FirstAppearance" : "2017-09-18",
  "LastAppearance" : "2017-09-25",
  "Image" : "https://api.adthena.com/static/images/587025b9-892e-ddc7-faa2-e1a8429b1335.jpg",
  "AdId" : "7896fd94-aba2-f635-a1f3-9d9e33ed129b",
  "AppearanceDuration" : 8
}]
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TopPlas>
  <Item>
    <CompetitorDomain>competitor1.com</CompetitorDomain>
    <Title>First ad title</Title>
    <DisplayText>First ad display text</DisplayText>
    <Frequency>0.11629480124093172</Frequency>
    <MarketCoverage>0.0368013835780703</MarketCoverage>
    <Price>$95.96</Price>
    <FirstAppearance>2017-09-16</FirstAppearance>
    <LastAppearance>2017-09-25</LastAppearance>
    <Image>https://api.adthena.com/static/images/123025b9-892e-ddc7-faa2-e1a8429b0011.jpg</Image>
    <AdId>b436fd94-aba2-f635-a1f3-9d9e33ed12p0</AdId>
    <AppearanceDuration>10</AppearanceDuration>
  </Item>
  <Item>
    <CompetitorDomain>competitor2.com</CompetitorDomain>
    <Title>Second ad title</Title>
    <DisplayText>Second ad display text</DisplayText>
    <Frequency>0.01629480124093172</Frequency>
    <MarketCoverage>0.0268013835780703</MarketCoverage>
    <Price>$45.90</Price>
    <FirstAppearance>2017-09-18</FirstAppearance>
    <LastAppearance>2017-09-25</LastAppearance>
    <Image>https://api.adthena.com/static/images/587025b9-892e-ddc7-faa2-e1a8429b1335.jpg</Image>
    <AdId>7896fd94-aba2-f635-a1f3-9d9e33ed129b</AdId>
    <AppearanceDuration>8</AppearanceDuration>
  </Item>
</TopPlas>
CompetitorDomain,Title,DisplayText,Frequency,MarketCoverage,Price,FirstAppearance,LastAppearance,Image,AdId,AppearanceDuration
competitor1.com,"First ad title","First ad display text",0.11629480124093172,0.0368013835780703,"$95.96",2017-09-16,2017-09-25,"https://api.adthena.com/static/images/123025b9-892e-ddc7-faa2-e1a8429b0011.jpg","b436fd94-aba2-f635-a1f3-9d9e33ed12p0", 10
competitor2.com,"Second ad title","Second ad display text",0.01629480124093172,0.0268013835780703,"$45.90",2017-09-18,2017-09-25,"https://api.adthena.com/static/images/587025b9-892e-ddc7-faa2-e1a8429b1335.jpg","7896fd94-aba2-f635-a1f3-9d9e33ed129b", 8

Curl Request

curl -i 'https://api.adthena.com/wizard/{id}/top-pla/all' -H 'adthena-api-key: my-api-key' -H 'accept: application/json'

HTTP Request

GET /wizard/{id}/top-pla/all HTTP/1.1
Host: api.adthena.com
Adthena-api-key: my-api-key
Accept: application/json

Query parameters

These parameters can be applied in the query string section of the request URI, eg:

https://api.adthena.com/wizard/{id}/share-of-clicks-trend?periodstart=2016-08-17&periodend=2016-08-18&searchterm=one&searchterm=two

For parameters that support multiple values (arrays), repeat the parameter for each value. For example, to specify a list of competitors using the competitor parameter:

competitor=competitor1.com&competitor=competitor2.com&competitor=competitor3.com

Parameter Required Default Multiple Description
periodstart - Start date for data in format yyyy-mm-dd. If the date is more than 30 days in the past, then weekly data (Sunday - Saturday) will be returned.
periodend - End date for data in format yyyy-mm-dd.
device desktop desktop / mobile / total.
traffictype paid paid / organic / total / totalpaid (where totalpaid = PLA + Text Ads, and total includes everything.)

Note: Only applicable to the Market Share and Market Trends endpoints.
wholemarket false Results will be taken from “Whole Market” or “My Terms”.
competitor - Include a COMPETITOR in results.
searchterm - Include a SEARCH TERM in results.
redshiftadwordscampaign - Include a ADWORDS CAMPAIGN from results.
exclude-competitor - Exclude a Competitor from results.
exclude-searchterm - Exclude a Search Term from results.
exclude-redshiftadwordscampaign - Exclude a Adwords Campaign from results.
cg - Include a COMPETITOR GROUP in results.
kg - Include a SEARCH TERM GROUP in results.
exclude-cg - Exclude a Competitor Group from results.
exclude-kg - Exclude a Search Term Group from results.
adtext - Include only adverts containing specific text string. Unlike other parameters, multiple values will be treated as an AND, so adverts containing both ‘$’ and ‘less than.

Note: Only applicable to Top Adverts end point.
adid - Include only search terms appearing on a specific ad.

Note: Only applicable to Search Term Detail end point.
exclude-text Exclude any adverts containing specific text string.

Note: Only applicable to Top Adverts end point.
isNew false Include only adverts where first seen date is less than 7 days.

Note: Only applicable to Top Adverts end point.
isCurrent false Include only adverts where last seen date is less than 7 days.

Note: Only applicable to Top Adverts end point.
infringementrule - Include only infringements found as part of the specified rule.

Note: Only applicable to Infringements end point.

Content Negotiation

All Adthena endpoints return data in JSON, XML or CSV form. In order to return the appropriate content type, use one of the following accept headers:

Accept: application/json
Accept: application/xml
Accept: text/csv

Errors

The Adthena API uses the following error codes:

Error Code Meaning
400 Bad Request - Something is wrong with the request format
401 Unauthorized - API key not found or domain disabled
403 Forbidden - The API key does not allow access to this endpoint
404 Not Found
405 Method Not Allowed - Endpoint does not support the supplied HTTP method
406 Not Acceptable - the requested format isn’t supported (see Content Negotiation)
429 Too Many Requests - Slow down your request rate
500 Internal Server Error - We had a problem with our server. Try again later.
503 Service Unavailable - We’re temporarially offline for maintanance. Please try again later.