Many websites, many ads, and many stats. It’s easy to get confused by the data and waste hours checking every ad code. Adsterra Publisher API is a solution for those who need to flawlessly track every ad placement.
With API, website owners save hours pulling metrics like CPM, clicks, or revenue. They use a fantastic hack of using one Direct Link on several pages! If you, too, want to enhance your monetization strategy, check out this post and grab practical tips!
What is the Adsterra Publisher API?
API — the acronym for Application Programming Interface — is a means of communication between applications. Rephrasing this, API requests data from Adsterra and displays it in a publisher’s application or platform.
Publishers automate monetization tasks by only telling Adsterra to send the correct data to the right place in the correct order and at the correct frequency. You keep control over the core metrics across all domains.
To make it all happen, you need to know how to call out to the API and how to make it pull the stats. So let’s dive into some tech stuff and find out which datasets you can get.
Data you can retrieve with API
- Websites you added to Adsterra, including their names and unique IDs.
- Ad placements on every website added to your account.
- The full list of placements on all websites.
- A report containing the following metrics: impressions, clicks, CTR, CPM, and revenue by date.
- You can also specify a domain_id, placement_id and placement_sub_id, start and finish dates, as well as a specific GEO.
For now, Adsterra Publishers API supports only the GET method. This means that you can get the data without changing its structure or quantity.
How to apply API: Top use cases from publishers
These are not only CPM rates you can monitor regularly. Let’s explore how publishers automate their business with the Adsterra Publisher API. Here are some of the popular use cases:
1. Control how every ad placement performs
Imagine you run 20 websites with 40 ad placements (Popunders and Banners). You add one more Banner on a main page of one of these sites. With API, you can get critical stats, grouping them by placements inside every domain: impressions, clicks, CTR, and revenue.
We’ll lay out a more detailed example for this case in the Practice chapter.
2. Check best-performing countries to add more traffic
Group stats by country to catch which geos deliver the highest revenue on every website.
Grouping filters will help you out when you need to focus on dates, domains, and placements, as well.
3. Place multiple Direct Links with no legwork
Many publishers monetize multi-page websites, putting Direct Links on all pages. They need to generate a unique code for every page to get correct stats. But with Adsterra Publisher API, you can easily create a unique code. Simply add a placement_sub_id parameter to any of your URLs.
Direct Link is a simple URL you place inside the content. It looks like a hyperlink. Every user click opens up a new advertisement. A placement_sub_id parameter will make one URL taken from Adsterra unique and easy to track.
Getting started with the Adsterra Publisher API
Our API is free of charge, and any publisher can benefit from it. To access all our features, follow this short instruction:
- To send API requests, first, register as Adsterra’s publisher.
- Add a website with any of the following ad units: Popunder, Social Bar, Native Banner, Banner, or Direct Link.
Check the guide for adding websites and generating ad codes if you’re new to Adsterra.
If you already run websites on Adsterra, skip this part and jump forward.
- The website and ad units you will track via API must be Active.
- Navigate the API page from your account and hit the GENERATE NEW TOKEN button.
Save this token. You will then add to an API request, connecting your platform with your Adsterra publisher’s account. In the following chapter, we’ll learn how to create such requests.
API requests basics
When you request data, you address the Adsterra server:
https://api3.adsterratools.com/publisher
Every request contains:
- A unique token you generate on your Adsterra account (see the previous chapter). It’s also called the API Key.
- Parameters, or which data you want Adsterra to return.
- Format (JSON, CSV, XML)
Here is an example of a request in PHP where we request a full list of websites (domains) added to Adsterra. We request the CSV format and place the X-API-Key (or token) in the Header part:
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api3.adsterratools.com/publisher/domains.csv', [
'headers' => [
'Accept' => 'application/json',
'X-API-Key' => '123',
],
]);
echo $response->getBody();
Practice: Common API requests
Let’s now walk through a couple more examples of common requests publishers send to our server. 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. Grouping stats by ad placements
Remember one of the use cases for controlling all placements’ performance? Let’s examine it in more detail. Go to the Get Statistics page of the Adsterra Publisher API documentation. Here, you can check all the parameters to modify the final response. Include domain ID and placement ID in your request, and finally, choose the group_by placement option.
The request you send to Adsterra may look like this (PHP):
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api3.adsterratools.com/publisher/stats.json??domain=domain_id&placement=placement_id&start_date=2022-03-06&finish_date=2022-03-06&group_by=placement&country=country', [
'headers' => [
'Accept' => 'application/json',
'X-API-Key' => '123',
],
]);
echo $response->getBody();
The same request when using JavaScript Fetch:
const settings = {
async: true,
crossDomain: true,
url: 'https://api3.adsterratools.com/publisher/stats.json?domain=domain_id&placement=placement_id&start_date=2022-03-06&finish_date=2022-03-06&group_by=placement&country=country',
method: 'GET',
headers: {
Accept: 'application/json',
'X-API-Key': '123'
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
2. Grouping stats by country
You can pull stats reports, grouping core metrics by country, in almost the same way we’ve just done. Include the group_by=country query parameter in your request.
Here’s how the final request may look like if sent in PHP:
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api3.adsterratools.com/publisher/stats.json?domain=domain_id&placement=placement_id&start_date=2022-03-06&finish_date=2022-03-06&group_by=country&country=country', [
'headers' => [
'Accept' => 'application/json',
'X-API-Key' => '123',
],
]);
echo $response->getBody();
The same request for JavaScript Fetch:
const settings = {
async: true,
crossDomain: true,
url: 'https://api3.adsterratools.com/publisher/stats.json?domain=domain_id&placement=placement_id&start_date=2022-03-06&finish_date=2022-03-06&group_by=country&country=country',
method: 'GET',
headers: {
Accept: 'application/json',
'X-API-Key': '123'
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
3. Placing one Direct Link on several site pages
API allows you to add a unique parameter to a Direct Link URL. You need to attach a placement_sub_id to the URL. Here’s a step-by-step guide.
The Sub ID parameter
A Sub ID parameter is a unique identifier you add to a URL link. The URL structure doesn’t change, it’s only one new parameter added. The Sub ID allows tracking the performance of the same Direct Link placed on different websites or pages.
Where to place the Sub ID parameter?
Put the &psid=sub_id_1 to the end of your Direct Link URL link, where sub_id_1 is your unique identifier. Compose it using letters, numbers, or both.
How to use the Sub ID in Publisher API requests
Here’s an example of a query to get statistics grouped by the Sub ID parameter:
1. Add Sub ID to URL:
- Append &psid=sub_id_1 to your URL.
- Ensure sub_id_1 is a unique identifier.
Example in Ruby:
https://yourdomain.com/path/to/ad?psid=home_page_1
2. Place a Direct Link with Sub ID on a web page
3. Ensure you generated different Sub IDs for every page
Examples:
- Home page: &psid=home_page_1
- About page: &psid=about_page_2
- Contact page: &psid=contact_page_3
4. Get stats:
- Use the Adsterra Publisher API to get the stats you need.
- Group results by the placement_sub_id parameter to see performance per location.
Example API Query (cURL):
curl --request GET \ --url 'https://api3.adsterratools.com/publisher/stats.json?domain=8356709&placement=28948612&start_date=2024-07-09&finish_date=2024-07-09&group_by%5B%5D=placement_sub_id' \ --header 'Accept: application/json' \ --header 'X-API-Key: {api_token}' Finishing up with practice, we encourage you to take a closer look at all Adsterra monetization ad formats. Choose the most beneficial for your business and target audience and start earning with or without API.
API requests errors
When everything works fine, you will get a 200 server response, which means “Success.” However, sometimes pitfalls occur. So here are the most common errors and their meanings. Use those tips to deal with them yourself or 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
Summarizing the benefits
Even a slight CPM change may affect your monetization strategy. With Adsterra Publishers API, you can automatically fetch important metrics from your account without building another report or exporting a CSV file.
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 and 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 
