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.
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();
}
?>