whockey / node-foursquare

Foursquare API v2 for NodeJS

node-foursquare

Fault-tolerant Foursquare API wrapper for Node JS.

Install

npm install node-foursquare

Version History

• v0.0.1 - First release
• v0.0.2 - Bug Fixes and Downstream Merges
• v0.1.0 - Suggested Refactoring and latest endpoints from Foursquare (VERY NON-PASSIVE)
  • Surround results with field name.
  • Userless Access Tokens (for Venues.explore, etc).
  • Ability to load single portions of the library, (e.g. only import Venues).
  • Users - Leaderboard, Requests
  • Venues - Categories, Explore
• v0.1.1 - Support for Foursquare API Version + Deprecation Warnings (via configuration).
• v0.1.2 - Added new mayorships endpoint, removed extraneous field from User.getBadges (non-passive).
• v0.1.3 - Added Updates endpoint, updated to log4js v0.3.x.
• v0.1.4 - Added Lists and Events endpoints.
• v0.2.0 - Overhaul
  • Replaced log4js with winston.
  • Added new endpoints, modules, methods.
  • Refactored testing suite.

Use

The Foursquare module takes a configuration parameter containing logging and client keys. It also supports alternate Foursquare URLs if necessary, (but that is unlikely).

var config = {
  'secrets' : {
    'clientId' : 'CLIENT_ID',
    'clientSecret' : 'CLIENT_SECRET',
    'redirectUrl' : 'REDIRECT_URL'
  }
}

var foursquare = require('node-foursquare')(config);

Once instantiated, you just need to set up endpoints on your own server that match your OAuth configuration in Foursquare. Using Express, for example:

var app = express();

app.get('/login', function(req, res) {
  res.writeHead(303, { 'location': foursquare.getAuthClientRedirectUrl() });
  res.end();
});


app.get('/callback', function (req, res) {
  foursquare.getAccessToken({
    code: req.query.code
  }, function (error, accessToken) {
    if(error) {
      res.send('An error was thrown: ' + error.message);
    }
    else {
      // Save the accessToken and redirect.
    }
  });
});

Foursquare API Version and Deprecation Warnings

Foursquare allows consumers to specify a 'version' of their API to invoke, based on the date that version became active. For example, passing a version string of '20110101' uses the API as of Jan 1, 2011. By default, this library will use a version of today's date.

To enable a different version of the API, add the following to configuration.

var config = {
  ...
  'foursquare' : {
    ...
    'version' : '20110101',
    ...
  }
  ...
}

When using an older API, Foursquare will provide deprecation warnings, (if applicable). By default, this library will write these warnings to the log, which will only be visible if logging for 'node-foursquare' is turned on, (see 'Logging', below).

You can configure this library to throw an error instead:

var config = {
  ...
  'foursquare' : {
    ...
    'warnings' : 'ERROR',
    ...
  }
  ...
}

Logging

This module uses winston to log events. By default, the logging level is set to 'none'. If you want to output logging messages from the different modules of this library, you can add overrides to your configuration object. For example, to log debug (and higher) messages in Venues and warnings in Core to the console:

var config = {
  'winston' : {
    'loggers': {
       'core': {
         'console': {
           'level': 'warn'
         }
       },
       'venues': {
         'console': {
           'level': 'debug'
         }
       }
     }
  ...
}

var foursquare = require('node-foursquare')(config);

For a list of existing logging points, refer to config-default.js.

For more information, see: https://github.com/flatiron/winston

Testing

To test, you need to create a config.js file in the /test directory as follows:

module.exports = {
  'secrets' : {
    'clientId' : 'YOUR_CLIENT_ID',
    'clientSecret' : 'YOUR_CLIENT_SECRET',
    'redirectUrl' : 'http://localhost:3000/callback' // This should also be set in your OAuth profile.
  }
};

Then, simply invoke the test.js file with Node.JS:

node test.js

If you hit http://localhost:3000, you'll be redirected for an authentication token.

If you hit http://localhost:3000/test, you'll test the entire library with no authentication, (and get appropriate errors for protected endpoints).

Testing results will be logged to the console.

All tests use examples as suggested by the Foursquare Endpoint Explorer.

Documentation

Detailed documentation is available in the /docs directory.

(In the latest version of JSDoc 3, the file names are replaced with random identifiers. Not sure why, we'll see if they can get that fixed soon.)

Notes

This module is a read-only subset of the full Foursquare API, but further capability, (adding, posting, updating, etc), is forthcoming. Bugs and Pull Requests are, of course, accepted! :-)

This project is a refactoring and enhancement of: https://github.com/yikulju/Foursquare-on-node