README

Find the Symfony Bundle for this library here.

Why?

There is no library currently built to interact with the foursquare api using the fantastic Guzzle HTTP Client library. Guzzle is awesome and supplies a lot of great things for building web service clients. Guzzle is fully unit tested which allows this library to be a light wrapper around the Guzzle core. You can read more about Guzzle here.

Installation

The JcrollFoursquareApiClient is available on Packagist (jcroll/foursquare-api-client) and as such installable via Composer.

If you do not use Composer, you can grab the code from GitHub, and use any PSR-4 compatible autoloader (e.g. the Symfony ClassLoader component) to load the library's classes.

Guzzle Versioning

This package is compatible with different versions of Guzzle (see below):

Guzzle Version	Foursquare Client Version
~3	~1
~4, ~5	~2
~6	~3

Composer example

Add JcrollFoursquareApiBundle in your composer.json:

{
    "require": {
        "jcroll/foursquare-api-client": "~3"
    }
}

Download the library:

$ php composer.phar update jcroll/foursquare-api-client

After installing, you need to require Composer's autoloader somewhere in your code:

require_once 'vendor/autoload.php';

Usage

use Jcroll\FoursquareApiClient\Client\FoursquareClient;

$client = FoursquareClient::factory([
    'client_id'     => 'your_foursquare_client_id',     // required
    'client_secret' => 'your_foursquare_client_secret', // required
    'version'       => 20140806,                        // optional
    'mode'          => 'foursquare',                    // optional (one of 'foursquare' or 'swarm')
]);

$client->setToken($oauthToken);  // optionally pass in for user specific requests

$client->setMode('swarm');       // switch from mode 'foursquare' to 'swarm'

$command = $client->getCommand('venues/search', [
    'near'  => 'Chicago, IL',
    'query' => 'sushi'
]);

$results = (array) $client->execute($command); // returns an array of results

You can find a list of the client's available commands in the bundle's client.json but basically they should be the same as the api endpoints listed in the docs.

Oauth Integration

Endpoints in the foursquare API that are user specific will require authorization with foursquare using the Oauth 2.0 protocol.

If you're using the HWIOAuthBundle with Symfony you can install the JcrollFoursquareApiBundle for automatic integration with your oauth requests.

Otherwise oauth protocol authorization is beyond the scope of this library but you can find a list of possible libraries here. After authorization you can pass the access token into the client for user specific access.

jcroll / foursquare-api-client

Maintainers

Details