PHP Examples

Overview

The code samples in this section all use the following classes.

The Request class uses cURL to make the requests to the API.

The Response class contains the API response and returned status code info.

Request and Response classes

class Request {

        /**
         * @var resource
         */
        protected $_request;

        /**
         * @var integer
         */
        protected $_method;

        /**
         * @var string
         */
        protected $_url;

        /**
         * @var array
         */
        protected $_headers = array(
            'Content-type: application/json'
        );

        /**
         * @var string|array
         */
        protected $_params;

        /**
         * @var object Response
         */
        protected $_reponse;

        /**
         * Constructor
         *
         * @param   string      $url
         * @param   string      $method
         * @param   array       $params
         */
        public function __construct($url, $method, $params = array()) {

            $this->_url = $url;

            // Set the method
            $this->_method = $method;

            // Set the params
            $this->_params = $params;
        }

        /**
         * Determine the Request method
         *
         * @param   string  $method
         */
        private function setMethod() {

            switch($this->_method) {
                case 'GET':
                    break;
                case 'POST':
                    curl_setopt($this->_request, CURLOPT_POST, 1);
                    break;
                case 'PUT':
                    curl_setopt($this->_request, CURLOPT_CUSTOMREQUEST, 'PUT');
                    break;
                case 'DELETE':
                    curl_setopt($this->_request, CURLOPT_CUSTOMREQUEST, 'DELETE');
                    break;
            }
        }

        /**
         * Add authorization header
         *
         * @param   string  $type
         * @param   string  $token
         */
        public function setAuthorizationHeader($type, $token) {

            $authorization = $type . ' ' . $token;

            $this->_headers[] = 'Authorization: ' . $authorization;
        }

        /**
         * Add body to request
         */
        private function addBody() {

            if($this->_method != 'GET' && empty($this->_params) == false) {

                if(is_array($this->_params)) {
                    // JSON Encode the array
                    $this->_params = json_encode($this->_params);
                }

                curl_setopt($this->_request, CURLOPT_POSTFIELDS, $this->_params);

                // Add a content-length header
                $this->_headers[] = 'Content-length: ' . strlen($this->_params);
            }
        }

        /**
         * Add a query string to the request
         */
        private function addQueryString() {

            if($this->_method == 'GET' && is_array($this->_params) && count($this->_params) > 0) {

                $query_string = '?';

                foreach($this->_params as $param => $value) {

                    $query_string = $query_string . $param . '=' . $value . '&';
                }

                trim($query_string, '&');

                $this->_url = $this->_url . $query_string;
            }
            else {

                if(is_array($this->_params) && count($this->_params) > 0 && strpos($this->_url, '{') !== false) {
                    // Pattern match params against the url
                    foreach($this->_params as $param => $value) {
                        $this->_url = preg_replace('/{' . $param . '}/', $value, $this->_url);
                    }
                }
            }
        }

        /**
         * Send the request
         */
        public function send() {

            // Initialise cUrl request
            $this->_request = curl_init();

            // Return the response as a string
            curl_setopt($this->_request, CURLOPT_RETURNTRANSFER, 1);

            // Add a query string
            $this->addQueryString();

            // Set the URL
            curl_setopt($this->_request, CURLOPT_URL, $this->_url);

            // Set request method
            $this->setMethod();

            // Add a body
            $this->addBody();

            if(empty($this->_headers) == false) {
                // Set the headers
                curl_setopt($this->_request, CURLOPT_HTTPHEADER, $this->_headers);
            }

            // Disable SSL checks
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYHOST, false);

            // Send the request and store the body
            $this->_response = new Response(curl_exec($this->_request));

            // Set the status code
            $this->_response->setStatusCode(curl_getinfo($this->_request, CURLINFO_HTTP_CODE));

            // Close the connection
            curl_close($this->_request);
        }

        /**
         * Get the response
         *
         * @return object
         */
        public function getResponse() {

            return $this->_response;
        }
    }

    class Response {

        /**
         * @var array
         */
        protected $_reason_phrases = array(
            //Informational 1xx
            100 => "Continue",
            101 => "Switching Protocols",

            // Successful 2xx
            200 => "OK",
            201 => "Created",
            202 => "Accepted",
            203 => "Non-Authoritative Information",
            204 => "No Content",
            205 => "Reset Content",
            206 => "Partial Content",

            // Redirection 3xx
            300 => "Multiple Choices",
            301 => "Moved Permanently",
            302 => "Found",
            303 => "See Other",
            304 => "Not Modified",
            305 => "Use Proxy",
            306 => "(Unused)",
            307 => "Temporary Redirect",

            // Client Error 4xx
            400 => "Bad Request",
            401 => "Unauthorized",
            402 => "Payment Required",
            403 => "Forbidden",
            404 => "Not Found",
            405 => "Method Not Allowed",
            406 => "Not Acceptable",
            407 => "Proxy Authentication Required",
            408 => "Request Timeout",
            409 => "Conflict",
            410 => "Gone",
            411 => "Length Required",
            412 => "Precondition Failed",
            413 => "Request Entity Too Large",
            414 => "Request-URI Too Long",
            415 => "Unsupported Media Type",
            416 => "Requested Range Not Satisfiable",
            417 => "Expectation Failed",

            // Server Error 5xx
            500 => "Internal Server Error",
            501 => "Not Implemented",
            502 => "Bad Gateway",
            503 => "Service Unavailable",
            504 => "Gateway Timeout",
            505 => "HTTP Version Not Supported"
        );

        /**
         * @var integer
         */
        protected $_status_code;

        /**
         * @var string
         */
        protected $_body;

        /**
         * Constructor
         *
         * @param   string      $body
         */
        public function __construct($body) {

            $this->_body = $body;
        }

        /**
         * Constructor
         *
         * @param   string      $status_code
         */
        public function setStatusCode($status_code) {

            $this->_status_code = $status_code;
        }

        /**
         * Get status code
         *
         * @return  integer
         */
        public function getStatusCode() {

            return $this->_status_code;
        }

        /**
         * Get body
         *
         * @return  string
         */
        public function getBody() {

            return $this->_body;
        }

        /**
         * Get body JSON Decoded
         *
         * @return  object|null
         */
        public function getBodyDecoded() {

            return json_decode($this->_body);
        }

        /**
         * Get reason phrase
         *
         * @return string|boolean
         */
        public function getReasonPhrase() {

            if(array_key_exists($this->_status_code, $this->_reason_phrases)) {

                return $this->_reason_phrases[$this->_status_code];
            }
            else {

                return false;
            }
        }
    }

Login

There are two options to request the login route:

• with username and password
• with api token (access token)

Example of login with username and password parameters.

<?php

    // Include Request and Response classes

    $url = 'https://api.example.com/v2/login';

    $params = array(
        'username'  => 'sample_username',
        'password'  => 'sample_password'
    );

    // Create a new Request object
    $request = new Request($url, 'POST', $params);

    // Send the request
    $request->send();

    // Get the Response object
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Retrieve the session token details
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody() . PHP_EOL;
    }
?>

Example of login with API token (access token)

<?php

    // Include Request and Response classes

    $url = 'https://api.example.com/v2/login';

    $params = array(
            'api_token'  => 'sample_token_2bb447abb71b69368901a....'
        );

    // Create a new Request object
    $request = new Request($url, 'POST', $params);

    // Send the request
    $request->send();

    // Get the Response object
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Retrieve the session token details
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody() . PHP_EOL;
    }
?>

Authentication

Each request to user related content requires an Authorization header to be set, with the value containing the token type and Session token received from the API Login request.

A valid /login request to the API will return the following json payload.

{
  "token": "",
  "type": "",
  "expires_in": 0
}

The Session token should be included in all subsequent user related content requests to the API.

The type is to be prepended to the the token, separated by a single space.

Bearer 4e63518d383d8fcaefb516fe708b893727463031

The expires_in is the time in seconds that the token will be valid for. When this time expires, a new token will need to be attained via the /login request.

Example of Getting and Setting Authorization Header with username and password

<?php

    // Include Request and Response classes

    // Login
    $url = 'https://api.example.com/v2/login';

    $params = array(
        'username'  => 'sample_username',
        'password'  => 'sample_password'
    );

    // Create a new Request object
    $request = new Request($url, 'POST', $params);

    // Send the request
    $request->send();

    // Get the Response object
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Retrieve the session token details
        $token = $response->getBodyDecoded();

        // Get Campaigns
        $url = 'https://api.example.com/v2/campaigns';

        // Create a new Request object
        $request = new Request($url, 'GET');

        // Set the Authorization Header
        $request->setAuthorizationHeader($token->type, $token->token);

        // Send the request
        $request->send();

        // Get the Response object
        $response = $request->getResponse();

        if($response->getStatusCode() == 200) {

            // Retrieve the campaigns
            $campaigns = $response->getBodyDecoded();

            foreach($campaigns->result as $campaign) {
                // Display the campaign names
                echo $campaign->name . PHP_EOL;
            }
        }
        else {
            // Campaigns request error
            echo $response->getStatusCode() . PHP_EOL;
            echo $response->getReasonPhrase() . PHP_EOL;
            echo $response->getBody();
        }
    }
    else {
        // Invalid Login
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Example of Getting and Setting Authorization Header with API token

<?php

    // Include Request and Response classes

    // Login
    $url = 'https://api.example.com/v2/login';

    $params = array(
        'api_token'  => 'sample_token_2bb447abb71b69368901a....'
    );

    ...

?>

Collections

The following is an example of a request to get the Browsers collection.

<?php

    // Include Request and Response classes

    $url = 'https://api.example.com/v2/collections/browsers';

    // Create a new Request object
    $request = new Request($url, 'GET');

    // Set the Authorization Header retrieved from earlier Login request
    $request->setAuthorizationHeader($token->type, $token->token);

    // Send the request
    $request->send();

    // Get the Response object
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $browsers = $response->getBodyDecoded();

        foreach($browsers as $browser) {

            echo $browser->id . ': ' . $browser->name . PHP_EOL;
        }
    }
    else {
        // Collection not found
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Statistics

The following is an example of an advertiser request to statistics/a/date.

In case additional_group_by value is defined, the request will be grouped by the main route field and the extra one(s).

Example of statistics per date filtered by campaign ID 1234.

<?php

    // Include Request and Response classes

    $url = 'https://api.example.com/v2/statistics/a/date';

    // Specify the campaign id
    $params = array(
       'campaignid'  => 1234
    );

    $request = new Request($url, 'GET', $params);

    // Set the Authorization Header, retrieved from earlier Login request
    $request->setAuthorizationHeader($token->type, $token->token);

    // Send the request
    $request->send();

    // Get the response object
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {

            echo $statistic->ddate . ': ' . $statistic->value . PHP_EOL;
        }
    }
    else {
        // Campaign statistics not found
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Example of statistics per date with additional group by campaign.

<?php

    // Include Request and Response classes

    $url = 'https://api.example.com/v2/statistics/a/date';

    // Specify the campaign id
    $params = array(
       'additional_group_by'  => 'campaign'
    );

    $request = new Request($url, 'GET', $params);

    // Set the Authorization Header, retrieved from earlier Login request
    $request->setAuthorizationHeader($token->type, $token->token);

    // Send the request
    $request->send();

    // Get the response object
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo $statistic->ddate . ' - ' . $statistic->idcampaign . ': ' . $statistic->value . PHP_EOL;
        }
    }
    else {
        // Campaign statistics not found
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

post /statistics/a/global

Get global advertiser statistics

Example 1 of global statistics

Example for global statistics request.

Only the group_by parameter is mandatory. The default values for the other parameters can be found Here.

Please note that the global statistic routes (statistics/a/global, statistics/p/global) have different parameters format.

<?php

    // Include Request and Response classes

    $url = 'https://api.example.com/v2/statistics/a/global';

    // Specify the group_by
    $params = [
        "group_by" => ["date"]
    ];

    $request = new Request($url, 'POST', $params);

    // Set the Authorization Header, retrieved from earlier Login request
    $request->setAuthorizationHeader($token->type, $token->token);

    // Send the request
    $request->send();

    // Get the response object
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Date: ' . $statistic->group_by->date->date . ' -  Impressions: ' . $statistic->impressions .' - Cost: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Campaign statistics not found
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Example 2 of global statistics

Get statistics per date including sum totals.

<?php

    // Include Request and Response classes

    $url = 'https://api.example.com/v2/statistics/a/global';

    // Specify the campaign id
    $params = [
        "filter" => [
            "date_from" => "2019-01-10",
            "date_to" => "2019-01-31",
        ],
        "totals" => 1,
        "group_by" => ["date"]
    ];

    $request = new Request($url, 'POST', $params);

    // Set the Authorization Header, retrieved from earlier Login request
    $request->setAuthorizationHeader($token->type, $token->token);

    // Send the request
    $request->send();

    // Get the response object
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Date: ' . $statistic->group_by->date->date . ' -  Impressions: ' . $statistic->impressions .' - Cost: ' .  $statistic->cost . PHP_EOL;
        }

        echo 'Total cost:' . $statistics->result_total->cost . PHP_EOL;
    }
    else {
        // Campaign statistics not found
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Example 3 of global statistics

Get statistics per campaign and country filtered by specific date ordered by impressions.

<?php

    // Include Request and Response classes

    $url = 'https://api.example.com/v2/statistics/a/global';

    $params = [
        "filter" => [
            "date_from" => "2019-01-30",
            "date_to" => "2019-01-30",
        ],
        "group_by" => ["country_iso", "campaign_id"],
        "order_by" => [
            ["field" => "impressions", "order" => "desc"]
        ]
    ];


    $request = new Request($url, 'POST', $params);

    // Set the Authorization Header, retrieved from earlier Login request
    $request->setAuthorizationHeader($token->type, $token->token);

    // Send the request
    $request->send();

    // Get the response object
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Country: ' . $statistic->group_by->country_iso->country_iso . ' -  Campaign ID: ' . $statistic->group_by->campaign_id->id .' - Cost: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Campaign statistics not found
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Example 4 of global statistics

Get publisher statistics per zone and country filtered by specific operating system.

<?php

    // Include Request and Response classes

    $url = 'https://api.example.com/v2/statistics/p/global';

    $params = [
        "filter" => [
            "date_from" => "2019-01-30",
            "date_to" => "2019-01-30",
            "operating_system_id" => [11, 12]
        ],
        "group_by" => ["zone_id", "country_iso"]
    ];


    $request = new Request($url, 'POST', $params);

    // Set the Authorization Header, retrieved from earlier Login request
    $request->setAuthorizationHeader($token->type, $token->token);

    // Send the request
    $request->send();

    // Get the response object
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo ' Zone ID:' . $statistic->group_by->zone_id->id . ' - Country: ' . $statistic->group_by->country_iso->country_iso .' - Revenue: ' .  $statistic->revenue . PHP_EOL;
        }
    }
    else {
        // Campaign statistics not found
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>