Our partner publishers consider their websites as the primary income source. With multiple domains linked to Adsterra, they always have to check the statistics reports or download the CSV files. Even a slight CPM change may affect their revenue as well as impressions or CTR metrics. With Adsterra Publishers API, website owners save hours on pulling the right data like CPM, clicks, or even GEOs. They simply automate the process of getting stats from Adsterra and aggregating them into neat reports.
In this quick guide, we will see how a webmaster can pull statistics out of the Adsterra account with the help of Publishers API. Look through and see how you can use it in your business.
What is API?
Before we move further, let’s figure out what API is in general. That will make all the following examples much more transparent.
API — the acronym for Application Programming Interface — is a means of communication between applications. Rephrasing this, API can request data from one app and send it to another.
Let’s make it more realistic. Imagine you’re sitting in a cafe. You ask a waiter for a cup of coffee and one chocolate muffin. The waiter writes down your order and then asks the kitchen staff to prepare your breakfast. After some time, the waiter will bring your coffee and a muffin. Here the waiter acts like an API getting your query with some parameters and pulling the data needed to complete it.
But unlike dialogs between people, in the digital world, you need to know how to call out to the API and how to make it pull the stats you need. Simply put, you’ll need a set of commands or instructions.
And now, we are going to find out how to communicate with Adsterra Publishers API.
What is Adsterra Publishers API for?
With our API for publishers, you can automatically fetch your account’s data without building another report or exporting a CSV file.
This might be helpful when you use analytics dashboards outside Adsterra. You connect your account’s statistics with a tracking system to save you time digging through the same data and building reports.
API method we use
APIs can use various methods to request and transfer data. For now, Adsterra Publishers API supports only the GET method. It means that you can get the data without making any changes in its structure or quantity.
Data you can retrieve
- Websites you added to Adsterra, including their names and unique IDs.
- Your ad placements on each domain added to your account.
- The full list of your placements on all websites.
- A report containing the following metrics: impressions, clicks, CTR, CPM, and revenue by date.
*You can also make API specify domain_id, placement_id, start and finish dates, as well as a specific GEO.
How to start using Adsterra Publishers API?
Now that we’ve captured the basics, let’s move on and practice a bit. Our goal now is to learn how to start using Adsterra Publishers API.
1. Getting the Adsterra API token
First of all, you need to create a unique token (also: API Key). This token will allow various applications to access your Adsterra account’s data without sharing your credentials.
To generate the token, open the API tab from your dashboard. Click GENERATE API TOKEN. Copy the unique code to the clipboard.
2. Using the token to call up Adsterra API
Basically, when you request data, you address our server:
https://api3.adsterratools.com/publisher
IMPORTANT UPDATE: Instead of adding a token to the URL, you will need now to pass it in the header of your request. This update ensures a safer and more reliable experience. So, you will
place the API token in a special x-api-key header.
3. Learning types of requests you can use to get data
Now that we have learned to use your unique token to address Adsterra URI, we are moving to the types of requests that help get statistics.
Below is the list of endpoints you should enter to pull out data. You will also need to specify the format in which you would like to have the data. JSON, XML, and CSV formats are supported.
The endpoints are
- /domains.{format} — returns the websites you added to Adsterra, including their names and unique IDs
- /domain/{domain_id}/placements.{format} — your placements on a specified domain; note that you’ll need the domain_id retrived via the /domains/{format} request
- /placements.{format} — returns the full list of your placements
- /stats.{format} — a report comprising impressions, clicks, CTR, CPM, and revenue by date; you can specify domain_id, placement_id, start and finish dates, as we as a specific GEO.
In the example below, we used a cURL (Client URL) request for domains:
cURL --request GET\
--url https://api3.adsterratools.com/publisher/domains.json \
--header 'Accept: application/json' \ --header 'X-API-Key: 123'
Pulling data with Adsterra Publishers API
To make all our examples more illustrative, we will see how data retrieving looks in real life.
You can jump to Adsterra’s documentation and test various requests. You will need now to paste the API key (or token) obtained before to the appropriate field:
1. Getting domain names and IDs
First, let’s imagine you need to get a collection of all your domains. A possible Javascript request (jQuery framework) can be:
const settings = { async: true, crossDomain: true, url: 'https://api3.adsterratools.com/publisher/domains.json', method: 'GET', headers: { Accept: 'application/json', 'X-API-Key': '123' } }; $.ajax(settings).done(function (response) { console.log(response); }); Then, the response you will get from Adsterra can look like this:
In our case, we have two domains with their IDs listed.
2. Getting placements’ IDs
Now you can track your placement IDs across domains you added to Adsterra. We need to enter specific parameters to the request.
Now let’s choose a request example in Python:
import http.clientconn = http.client.HTTPSConnection("api3.adsterratools.com")
headers = { 'Accept': "application/json", 'X-API-Key': "123"
}
conn.request("GET", "/publisher/domain/domain_id/placements.format", headers=headers)
res = conn.getresponse()
data = res.read()print(data.decode("utf-8"))
You’ll get a new response where you’ll see all the placements with their IDs and names. Here below is a piece of such a response.
3. Getting full statistical reports
Just like we sent requests for pulling a domain ID and placements, we can get the full stats reports that will include CPM, CR, clicks, and revenues metrics.
Ok, to generate a stats report, we will add specific parameters: start and finish date, country, domain, placement. You can also group data by parameters needed. Let’s repeat our example in Python:
import http.client
conn = http.client.HTTPSConnection("api3.adsterratools.com")
headers = { 'Accept': "application/json", 'X-API-Key': "123"
}
conn.request("GET", "/publisher/stats.json?start_date=2022-03-06&finish_date=2022-03-06&group_by=date", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
When done right, in the Response field, you get all stats relevant to the domain and placements you entered. Data can be grouped by date, domain, placement, country, or placement subID.
Here is how a stats report grouped by date might look like.
4. Dealing with errors
When it all works fine, you will get a 200 server respose, which means “Success.” However, sometimes pitfalls occur. So here are the most common errors and their meaning. Use those tips to deal with them by yourself or to ask for help from our support team.
- 401 — the token is incorrect. Please use the token from your account (see the API tab)
- 403 — the token is no longer valid. Please generate a new token
- 404 — not found. Make sure the URL is correct
- 405 – not allowed
- 422 – the server can’t interpret the instructions, however the syntax is correct
Conclusion
Working with plenty of statistical data, you will find the ad network’s API for publishers very helpful.
These are some tangible benefits you can enjoy:
- Monitor the key metrics and update them automatically.
- Compare the efficiency of Adsterra ad formats for publishers.
- Save plenty of time on building dynamic reports, collecting stats for specific periods.
- Control your core metrics — CPM and revenue — and react faster than ever.
But enough theory. It’s time to make the most of Adsterra Publishers API 
