PHP Quick Start Guide

These examples work with PHP 5.2 and higher compiled with cURL support.

Creating A Link

In this example, the demo tool is creating a link intended to be shared on Twitter that redirects to http://developers.awe.sm/.

<?php
$params = array(
        'v' => 3,
        'url' => 'http://developers.awe.sm/',
        'key' => '5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9',
        'tool' => 'mKU7uN',
        'channel' => 'twitter'    
);

$new_link_request = curl_init();
curl_setopt($new_link_request, CURLOPT_URL, 'http://api.awe.sm/url.txt');
curl_setopt($new_link_request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($new_link_request, CURLOPT_TIMEOUT, 5);
curl_setopt($new_link_request, CURLOPT_POST, 1);
curl_setopt($new_link_request, CURLOPT_POSTFIELDS, $params);
$new_link = curl_exec($new_link_request);
$response_code = curl_getinfo($new_link_request, CURLINFO_HTTP_CODE);
curl_close($new_link_request);

if ($response_code == 200) { // Link created
    echo $new_link;
} else {                   // Error creating link
    echo "API error: HTTP {$response_code}: {$new_link}";
}

Output: http://demo.awe.sm/K8E

Retrieving Stats On A Link

Later, the stats for this link could be retrieved:

<?php
$params = array(
        'v' => 3,
        'key' => '5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9'
);

// Create and execute cURL request
$link_stats_request = curl_init();
curl_setopt($link_stats_request, CURLOPT_URL, 'http://api.awe.sm/stats/demo.awe.sm_K8E.json');
curl_setopt($link_stats_request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($link_stats_request, CURLOPT_TIMEOUT, 5);
curl_setopt($link_stats_request, CURLOPT_POST, 1);
curl_setopt($link_stats_request, CURLOPT_POSTFIELDS, $params);
$link_stats = curl_exec($link_stats_request);
$response_code = curl_getinfo($link_stats_request, CURLINFO_HTTP_CODE);
curl_close($link_stats_request);

if ($response_code == 200) {
    // Success. Convert JSON to PHP array.
    $link_stats = json_decode($link_stats, true);
    print_r($link_stats);
} else {
    // Error creating link
    echo "API error: HTTP {$response_code}: {$link_stats}";
}

Output hash:

Array
(
    [awesm_id] => demo.awe.sm_K8E
    [start_date] => 
    [end_date] => 
    [interval] => none
    [with_zeros] => 
    [with_metadata] => 
    [with_conversions] => 
    [clicks] => 1
)

Retrieving Aggregated Stats

Let's find out how many times http://developers.awe.sm/ has been shared and how much traffic social sharing created.

<?php
$params = array(
    'v' => 3,
    'key' => '5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9',
    'group_by' => 'service',
    'original_url' => 'http://developers.awe.sm/'
);

// Create and execute cURL request
$page_share_stats_request = curl_init();
curl_setopt($page_share_stats_request, CURLOPT_URL, 'http://api.awe.sm/stats/range.json');
curl_setopt($page_share_stats_request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($page_share_stats_request, CURLOPT_TIMEOUT, 5);
curl_setopt($page_share_stats_request, CURLOPT_POST, 1);
curl_setopt($page_share_stats_request, CURLOPT_POSTFIELDS, $params);
$page_share_stats = curl_exec($page_share_stats_request);
$response_code = curl_getinfo($page_share_stats_request, CURLINFO_HTTP_CODE);
curl_close($page_share_stats_request);

if ($response_code == 200) {
    // Success. Convert JSON to PHP array.
    $page_share_stats = json_decode($page_share_stats, true);
    echo "{$page_share_stats["totals"]["clicks"]} clicks from {$page_share_stats["totals"]["shares"]} shares";
} else {
    // Error creating link
    echo "API error: HTTP {$response_code}: {$page_share_stats}";
}

Outputs: 107 clicks from 4 shares

Let's find the top three social networks (service) shared to in September 2011.

<?php
$params = array(
    'v' => 3,
    'key' => '5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9',
    'group_by' => 'service',
    'sort_type' => 'shares',
    'per_page' => 3,
    'start_date' => '2011-09-01',
    'end_date' => '2011-10-01'
);

// Create and execute cURL request
$service_share_stats_request = curl_init();
curl_setopt($service_share_stats_request, CURLOPT_URL, 'http://api.awe.sm/stats/range.json');
curl_setopt($service_share_stats_request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($service_share_stats_request, CURLOPT_TIMEOUT, 5);
curl_setopt($service_share_stats_request, CURLOPT_POST, 1);
curl_setopt($service_share_stats_request, CURLOPT_POSTFIELDS, $params);
$service_share_stats = curl_exec($service_share_stats_request);
$response_code = curl_getinfo($service_share_stats_request, CURLINFO_HTTP_CODE);
curl_close($service_share_stats_request);

if ($response_code == 200) {
    // Success. Convert JSON to PHP array
    $service_share_stats = json_decode($service_share_stats, true);
    echo "#1: {$service_share_stats["groups"][0]["service"]}";
    echo "#2: {$service_share_stats["groups"][1]["service"]}";
    echo "#3: {$service_share_stats["groups"][2]["service"]}";
} else {
    // Error creating link
    echo "API error: HTTP {$response_code}: {$service_share_stats}";
}

Output:

#1: twitter
#2: facebook
#3: email

Last updated 2012-03-02

Have questions? Talk to us.

PHP Quick Start Guide

Creating A Link

Retrieving Stats On A Link

Retrieving Aggregated Stats