💡 If you are in the process of ditching the spreadsheets or already have a proper analytics system, you can use our API to fetch the data you need automatically, without having to import a CSV file every now and again.
💡 Bear in mind that our API supports the GET method only. It means that you won't be able to delete or add domains or ad formats using the API.
Getting an API token
To get an API token, go to the API page from the left-hand menu and click Generate new token. You can also access the API documentation from that page and see all the tokens you've used before.
❗ Note that there can only be one valid token at a time. So once you generate a new token, you have to make a change to all API requests you've made.
Include the token in a header parameter called X-API-Key:
Available endpoints and URI
All requests are made to the following URI:
<https://api3.adsterratools.com/publisher>
Below you will find the list of available endpoints:
/domains/{format}— returns the websites you've added to Adsterra, including their names and unique IDs;/domain/{domain_id}/placements.{format}— your placements on the specified domain; note that you'll need the domain_id retrieved via the/domains/{format}request first;/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 well as a specific GEO.
The data can be retrieved as JSON, XML, and CSV. Make sure to specify the data format you need in the URI:
<https://api3.adsterratools.com/publisher/domains.json>
Example requests on how to get Adsterra statistics via API
We'll walk you through a few requests using Postman — a popular API testing tool. You can use it to get the idea of how we format the data and to test the requests you are planning to make.
First, we need to get the IDs of our domains from the following URI:
<https://api3.adsterratools.com/publisher/domains.json>
In the response body, we can see the following:
Let's find placement_id's from the first website (domain_id 1385226):
Now, we can use domain_id and placement_id to fetch this placement's stats:
The response:
Possible errors and ways to fix them
401 — the token is incorrect. Please use the token available in your dashboard.
403 — the token is no longer valid. Please generate a new token.
404 — not found. Make sure the URI is correct.