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. 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 a specific URL or URI to be correct.
URI stands for Uniform Resource Identifier. It is a string of characters that identifies a website (or any other web resource) by its location, unique name, or both. While URL — a Uniform Resource Locator — identifies only a web resource’s location on the Internet.
That’s why we talk here about Adsterra URI as we identify both location and the unique name.
All requests are made to the following URI, where you should add your token. Just paste it instead of {token} . See the example below.
https://api3.adsterratools.com/publisher/{token} 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}](//domain/{domain_id}/placements.{format}) — your placements on the 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 URI below, we used an example of a token, an endpoint, and a format.
Pulling data with Adsterra Publishers API
To make all our examples more illustrative, we will see how data retrieving looks in real life.
We’ll be using Postman, a popular API testing service. You can also sign up there and carry out some tests with your API token or just examine the examples below.
On the Postman account, we choose Create a request option. By default, a new request window with the GET method will open.
Â
1. Getting websites’ IDs
First, you will need to get the IDs of your domains from the following URI.
Put a slash sign after the token and enter ‘domains’. Don’t forget to choose the format. Here we’ll be using JSON.
Click Send.
Postman will return the results in the Response field below. In our case, we have four domains with their IDs listed. Here how it might look like:
2. Getting placements’ IDs
Now you can track your domains (or websites) with their IDs. It’s time to get placements’ IDs. Let’s find those for one of the domains listed in the response field above. Supposing, our ID is 1385226.
We need to add specific parameters to the same URI we have already used.
Again, we put a slash after the token and type in the required parameters. Then we click Send.
You’ll get a new response where you’ll see all the placements with their IDs and names.
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 endpoints to the very same URI. On the sample URI below, you can see a template request where you should enter the parameters you need.
https://api3.adsterratools.com/publisher/{token}/stats.(json/xml/csv)?domain={domain_id}&country={country}&placement={placement_id}&start_date={start_date}&finish_date={finish_date}&group_by[]={date/domain/placement/country/placement_sub_id}
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 domains might look like.
4. Dealing with errors
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 URI 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 
