Sample Code

Jumpstart your coding with these snippets of code. Code samples are currently available for C# and PHP, and we'll be adding more languages soon. The samples on this page show some of the basics, but we also have more complete code samples for specific use cases in our aWhereAPI Github repository

Getting an OAuth Access Token

All API requests require an OAuth access token, which you generate with your API key and secret. Here's an example of how to do that:

PHP  C#  cURL  R
//put your API Key and Secret in these two variables.
$api_key = "";
$api_secret = ""; 
 
//When called this function will request an Access Token and then return just
//the token value. 
function GetOAuthToken(){ 
    global $api_key,$api_secret;  
 
    $ch = curl_init("http://api.awhere.com/oauth/token");
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
    curl_setopt($ch, CURLOPT_POSTFIELDS, "grant_type=client_credentials");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
                                                "Content-Type: application/x-www-form-urlencoded",
                                                "Authorization: Basic ".base64_encode($api_key.":".$api_secret)
                                            ));
 
    $result = CurlExecute($ch); 
    $result = json_decode($result);
    return $result->access_token;
}

Making an API Request

Making API requests is as simple as firing off an HTTP request. Here are examples of how to make basic API requests. The code samples on Github will have more specific examples and different use cases to explore.

When making API calls, always remember to send along your Access Token (see previous example) in an HTTP header named Authorization. Read more about Authentication.

PHP  C#  cURL  R
 
// Define variables
$verb = "GET"; 
$host = "https://api.awhere.com"; 
$uri  = "/v2/fields"; 
 
$access_token = "" //You'll need to follow the example above to get an access token.
 
$http_headers = array("Authorization: Bearer ".$access_token); 
 
 
// Set up the cURL request
$curl = curl_init($host.$uri);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $verb);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, true);                           
 
 
// Normally you should not use these cURL options. They disable the SSL Cert 
// verification. But many local development environments are not built with
// the standard chain authority certificates, and so cannot verify the Cert.
// If you have troubles making cURL requests, you can uncomment the next two
// lines, but don't put them into production. 
 
// curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
// curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
 
 
 
// This fires the cURL request
$response = curl_exec($curl);
 
 
if($response === false){
    // if the curl_exec() fails for reason, it means it could not even reach the aWhere server
    // and the function returns FALSE 
    echo 'cURL Transport Error (HTTP request failed): '.curl_error($curl); 
    die(); 
} else { 
    // curl_getinfo() returns information about the HTTP transaction, used
    // mainly here for getting the status code. 
    $info = curl_getinfo($curl);
    $httpStatusCode = $info['http_code']; 
 
    //The cURL settings above will include the HTTP headers in the response
    //This next command explodes the headers into one variable and the actual API response in another
    list($responseHeaders, $responseBody) = explode("\r\n\r\n", $response, 2); 
 
    //Finally, we use json_decode to transform the API response into a native PHP object.
    $result = json_decode($responseBody); 
} 
curl_close($curl);