To help you get started, we provide a sample SDK in PHP for a server-side flow. You may download the files from this article.
The SDK manages the communication with forWhereiAm Authorization Servers to gain an access token.
You will need your client credentials to initialize the SDK, which you can obtain from the 'API' page of your business account.
Installation and instantiation
To install the SDK, extract the downloaded files and copy the files to a directory on the server where you will host your app, for example forwhereiam_php_sdk. Then just include forwhereiam_php_sdk/forwhereiam.php wherever you want to use the SDK.
You use the SDK by instantiating a new forwhereiam object with your client id and client secret, and an optional token scope:
require_once("forwhereiam.php"); $config = array(); $config['clientId'] = 'YOUR_CLIENT_ID'; $config['clientSecret'] = 'YOUR_CLIENT_SECRET'; $config['tokenScope'] = 'read rate announce'; $forwhereiam = new forwhereiam($config);
Making API requests
The SDK is designed to seamlessly handle the management of access tokens. If an access token is found in persistent store, then it will use that access token to make an API request. If no access token is found, it will request a new token from the Authorization server.
If an access token was found and used for an API request, but was rejected by our resource servers for being invalid or expired, then the SDK requests a new access token from the Authorization server and performs the API request one more time with the new access token before giving up.
The sample SDK provided stores the access token in a primitive form of a persistent store (PHP sessions). We strongly recommend you create your own custom subclasses in forwhereiam_sdk_php/forwhereiam.php to override the abstract methods called setPersistentData() and getPersistentData(). Your version of the subclass should store a copy of the access token in your database, as the access token have a long lifespan (currently one year) and need not be re-requested often.
After the instantiation of the forwhereiam object as described above, you may simply make API requests as follows.
Request all relevant announcements
$params = array(); $params['location'] = 'YOUR LOCATION'; $params['lastCheckAt'] = 'OPTIONAL lastCheckAt VALUE FROM PREVIOUS RESPONSE (IF ANY)'; $params['keywords'] = 'OPTIONAL KEYWORDS'; $params['radius'] = 'OPTIONAL RADIUS IN METERS, E.G. 100M'; $params['fields'] = 'OPTIONAL COMMA-SEPARATED LIST OF FIELDS FOR A PARTIAL RESPONSE'; $output = $forwhereiam->api('/v1/announcements.json', 'GET', $params);
Request an announcement's details
$id = 'ANNOUNCEMENT_ID'; $params = array(); $params['fields'] = 'OPTIONAL COMMA-SEPARATED LIST OF FIELDS FOR A PARTIAL RESPONSE'; $output = $forwhereiam->api('/v1/announcements/'. $id .'.json', 'GET', $params);
Rate an announcement
$id = 'ANNOUNCEMENT_ID'; $params = array(); $params['vote'] = 'INTEGER VALUE BETWEEN 1 AND 5'; $params['ip'] = 'IP ADDRESS OF USER GIVING THE RATING'; $output = $forwhereiam->api('/v1/announcements/'. $id .'/rate.json', 'POST', $params);
Find postcode for GPS coordinates
$params = array(); $params['lat'] = $lat; $params['lon'] = $lon; $output = $forwhereiam->api('/v1/find.json', 'GET', $params);
Create an announcement
$params = array(); $params['business_id'] = $business_id; $params['title'] = $title; $params['description'] = $description; $params['conditions'] = $conditions; $params['visible_from'] = $visible_from; $params['visible_until'] = $visible_until; $params['coordinates'] = $coordinates; $params['share'] = $share; $params['rate'] = $rate; $params['timer'] = $timer; $params['announcement_url'] = $url; $params['twitter'] = $twitter; $params['facebook'] = $facebook; $params['coverage'] = $target_coverage['coverage']; $params['tags'] = $tags; $params['sticky'] = $sticky; if (!empty($image_path)) $params['media'] = "@".$image_path; $output = $forwhereiam->api('/v1/announcements.json', 'POST', $params);