ayeT-Studios Publisher Reporting APIv2 Documentation (v2.0)


Updates

2020-05-19: Initial release of the Publisher Reporting API


Introduction

Our Publisher Reporting API allows publishers with and without adserver functionality to retrieve detailed statistics on their placement & adslot performance.

We use a REST API with JSON encoded data.
The examples in this documentation rely on PHP with mod_curl and have to be adapted for other languages if required.



Topics

  1. Obtain API Key and Getting Started
  2. Reporting Module





1. Obtain API Key and Getting Started


To obtain your API Key, log into your dashboard.
In the sidebar on the left you'll find the menu entry Account Settings where you will find a menu with the subitem API Token. It will show your current API Key and the option to renew your key if neccessary.

We've built a simple example function in PHP using mod_curl to send a request to our server and fetch the response. This function will be used throughout the documentation:
        function ayetRequest($command, $requestData = array()) {
            $apiKey = "XXX"; // TODO: Replace with your API key

            if (!is_array($requestData)) {
                $requestData=array();
            }

            $requestData['apiKey'] = $apiKey;

            $curl = curl_init();
            curl_setopt_array($curl, array(
                CURLOPT_RETURNTRANSFER => 1,
                CURLOPT_URL => 'https://www.ayetstudios.com/api2/'.$command,
                CURLOPT_POST => 1,
                CURLOPT_POSTFIELDS => $requestData)
                );

            if (($responseData = curl_exec($curl))===false) {
                curl_close($curl);
                /* echo "cURL error: ".curl_error($curl); */
                return null;
            }

            return json_decode($responseData, true);
        }
        

2. Reporting Module


Daily statistics by country

Summary:

Retrieves all statistics for the account for the given date range and filtered by optional parameters.
The returned data includes the impressions, clicks, conversions, revenue etc. statistics for the specified date range for each day grouped by country. If optional parameters (placements, adslots, etc.) are set, only metrics matching those parameters will be returned.

Attention: Requests to the reporting module are limited to 20 calls per hour.

Call:

        publisher/reporting
        

Parameters:

	STRING startDate (required, the start date for the statistics retrieval)
	STRING endDate (required, the end date for the statistics retrieval)
	ARRAY placements (optional, e.g. [102, 105])
	ARRAY adslots (optional, e.g. [525, 526])
	ARRAY adsource (optional, the names of your configured partner networks e.g. [adscendmedia, adgatemedia], for adserver customers only)
	ARRAY adformat (optional, e.g [offerwall])
	ARRAY countries (optional, e.g. [DE, US])
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
103Parameter out of range: Start date is greater than end date.
103Parameter out of range: Maximum date interval range is 31 days.
401Unauthorized access: You don't have permission to access publisher api using current API key.
403Placement(s) xx, xx don't belong to publisher #xxxx
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("publisher/reporting", array( 'startDate' => '2020-05-05',
                                                                'endDate' => '2020-05-06',
                                                                'placements' => array (1, 5)));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example as Plain HTTP GET Request:

	https://www.ayetstudios.com/api2/publisher/reporting?startDate=2020-05-05&endDate=2020-05-06&placements[]=1&placements[]=5&apiKey=XXX
        

Example Output:

        Array
        (
            [status] => success  // string, either success or error
            [filters] => Array
                (
                    [startDate] => 2020-05-05
                    [endDate] => 2020-05-06
                    [placements] => Array
                        (
                            [0] => 1
                            [1] => 5
                        )

                )

            [data] => Array
                (
                    [2020-05-05] => Array
                        (
                            [1] => Array // Placement ID, unique id for this placement
                                (
                                    [type] => android // Placement type
                                    [adslots] => Array
                                        (
                                            [1] => Array // Adslot ID, unique id for this adslot
                                                (
                                                    [adformat] => offerwall // Adslot type
                                                    [statistics] => Array // Adslot statistics per country
                                                        (
                                                            [US] => Array
                                                            (
                                                                  [impressions] => 10 // Total adslot impressions for this date, only available for offerwall adslots
                                                                  [clicks] => 21 // Total clicks on ayetstudios offers for this date
                                                                  [adserver_clicks] => 4 // Total clicks on adserver offers for this date
                                                                  [conversions] => 2 // Conversions for ayetstudios offers for this date
                                                                  [adserver_conversions] => 0 // Conversions for adserver offers for this date
                                                                  [revenue] => 5.026 // Total adslot revenue from ayetstudios offers for this date
                                                                  [adserver_revenue] => 0 // Total adslot revenue from adserver offers for this date
                                                                  [mediation_fees] => 0 // Adserver mediation fees for this date
                                                                  [DAU] => 0 // Unique users for this date, only available for offerwall adslots
                                                                  [EPC] => 0.201 // Earnings per Click (average EPC throughout all offers from this adslot)
                                                                  [eCPM] => 502.5 // Average revenue per 1000 adslot impressions, only available for offerwall adslots
                                                            )
                                                        )
                                                    [network_statistics] => Array
                                                        (
                                                          [US] => Array
                                                                (
                                                                  [ayetstudios] => Array
                                                                      (
                                                                          [offer_impressions] => 60 // Total offer impressions from this network / date / country, not available for static_api and live_api adslots
                                                                          [clicks] => 21 // Total offer clicks from this network / date / country
                                                                          [conversions] => 2 // Total conversions from this network / date / country
                                                                          [revenue] => 5.026 // Total revenue from this network / date / country
                                                                          [EPC] => 0.239 // Earnings per Click (average EPC for this network / date / country)
                                                                          [eCPM] => 83.77 // Average revenue per 1000 offer impressions, not available for static_api and live_api adslots
                                                                      )
                                                                  [adscendmedia] => Array  // Additional custom networks might be available for adserver clients
                                                                      (
                                                                          [offer_impressions] => 15
                                                                          [clicks] => 4
                                                                          [conversions] => 0
                                                                          [revenue] => 0
                                                                          [EPC] => 0
                                                                          [eCPM] => 0
                                                                      )
                                                                )
                                                        )

                                                )

                                        )

                                )

                            [5] => Array
                                (
                                    [type] => api
                                    [adslots] => Array
                                        (
                                            [7] => Array
                                                (
                                                    [adformat] => static_api
                                                    [statistics] => Array
                                                        (
                                                            [US] => Array
                                                                (
                                                                    [clicks] => 4
                                                                    [adserver_clicks] => 20
                                                                    [conversions] => 1
                                                                    [adserver_conversions] => 5
                                                                    [revenue] => 1.56
                                                                    [adserver_revenue] => 2.35
                                                                    [mediation_fees] => 0.118
                                                                    [DAU] => 0
                                                                    [EPC] => 0.163
                                                                )

                                                        )

                                                    [network_statistics] => Array
                                                        (
                                                            [US] => Array
                                                                (
                                                                    [ayetstudios] => Array
                                                                        (
                                                                            [clicks] => 4
                                                                            [conversions] => 1
                                                                            [revenue] => 1.56
                                                                            [EPC] => 0.39
                                                                        )
                                                                    [adgatemedia] => Array
                                                                        (
                                                                            [clicks] => 20
                                                                            [conversions] => 5
                                                                            [revenue] => 2.35
                                                                            [EPC] => 0.118
                                                                        )

                                                                )

                                                        )

                                                )

                                        )

                                )

                        )
                    [2020-05-06] => Array
                        (
                            [1] => Array
                                (
                                    [type] => android
                                    [adslots] => Array
                                        (
                                            [1] => Array
                                                (
                                                    [adformat] => offerwall
                                                    [statistics] => Array
                                                        (
                                                        )

                                                    [network_statistics] => Array
                                                        (
                                                        )

                                                )

                                        )

                                )

                            [5] => Array
                                (
                                    [type] => api
                                    [adslots] => Array
                                        (
                                            [7] => Array
                                                (
                                                    [adformat] => static_api
                                                    [statistics] => Array
                                                        (
                                                            [US] => Array
                                                                (
                                                                    [clicks] => 6
                                                                    [adserver_clicks] => 0
                                                                    [conversions] => 2
                                                                    [adserver_conversions] => 0
                                                                    [revenue] => 1.14
                                                                    [adserver_revenue] => 0
                                                                    [mediation_fees] => 0
                                                                    [DAU] => 0
                                                                    [EPC] => 0.19
                                                                )

                                                        )

                                                    [network_statistics] => Array
                                                        (
                                                            [US] => Array
                                                                (
                                                                    [ayetstudios] => Array
                                                                        (
                                                                            [clicks] => 6
                                                                            [conversions] => 2
                                                                            [revenue] => 1.14
                                                                            [EPC] => 0.19
                                                                        )

                                                                )

                                                        )

                                                )

                                        )

                                )

                        )

                )

        )