Awesome

foursquare

Python client for the foursquare API.

Philosophy:

Map foursquare's endpoints one-to-one
Clean, simple, Pythonic calls
Only handle raw data, you define your own models

Features:

Python 2+3 compatibility (via @youngrok)
OAuth dance
Automatic retries
Full endpoint coverage (non-merchant)
Full test coverage
Useful exception classes
Multi support (via @benneic)

Dependencies:

requests

Installation

pip install foursquare

PyPi page

Usage

Authentication

# Construct the client object
client = foursquare.Foursquare(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', redirect_uri='http://fondu.com/oauth/authorize')

# Build the authorization url for your app
auth_uri = client.oauth.auth_url()

Redirect your user to the address auth_uri and let them authorize your app. They will then be redirected to your redirect_uri, with a query parameter of code=XX_CODE_RETURNED_IN_REDIRECT_XX. In your webserver, parse out the code value, and use it to call client.oauth.get_token()

# Interrogate foursquare's servers to get the user's access_token
access_token = client.oauth.get_token('XX_CODE_RETURNED_IN_REDIRECT_XX')

# Apply the returned access token to the client
client.set_access_token(access_token)

# Get the user's data
user = client.users()

Instantiating a client

Userless Access

client = foursquare.Foursquare(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET')

Authenticated User Access (when you already have a user's access_token)

client = foursquare.Foursquare(access_token='USER_ACCESS_TOKEN')

Specifying a specific API version

client = foursquare.Foursquare(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', version='20111215')

client = foursquare.Foursquare(access_token='USER_ACCESS_TOKEN', version='20111215')

Examples

Users

Getting your own user object

client.users()

Getting another user

client.users('1183247')

Get your checkins

client.users.checkins()

Get your most recent checkin

client.users.checkins(params={'limit': 1})

Get all of your checkins (not a native 4sq call)

client.users.all_checkins()

Approve a friend's friend request

client.users.approve('1183247')

Venues

Get details about a venue

client.venues('40a55d80f964a52020f31ee3')

Search for a coffee place

client.venues.search(params={'query': 'coffee', 'll': '40.7233,-74.0030'})

Edit venue details

client.venues.edit('40a55d80f964a52020f31ee3', params={'description': 'Best restaurant on the city'})

Checkins

Returns a list of recent checkins from friends

client.checkins.recent()

Tips

Get a specific tip

client.tips('53deb1f6498e0d374af17ca7')

Full endpoint list

Note: endpoint methods map one-to-one with foursquare's endpoints

users()
users.requests()
users.checkins()
users.all_checkins() [*not a native endpoint*]
users.friends()
users.lists()
users.mayorships()
users.photos()
users.tips()
users.venuehistory()
users.venuelikes()
users.approve()
users.deny()
users.setpings()
users.unfriend()
users.update()

venues()
venues.add()
venues.categories()
venues.explore()
venues.managed()
venues.search()
venues.suggestcompletion()
venues.trending()
venues.events()
venues.herenow()
venues.links()
venues.listed()
venues.menu()
venues.photos()
venues.similar()
venues.stats()
venues.tips()
venues.nextvenues()
venues.likes()
venues.hours()
venues.edit()
venues.flag()
venues.proposeedit()
venues.setrole()

checkins()
checkins.add()
checkins.recent()
checkins.addcomment()
checkins.addpost()
checkins.deletecomment()

tips()
tips.add()
tips.listed()
tips.unmark()

lists()
lists.add()
lists.followers()
lists.suggestphoto()
lists.suggesttip()
lists.suggestvenues()
lists.additem()
lists.deleteitem()
lists.follow()
lists.moveitem()
lists.share()
lists.unfollow()
lists.update()
lists.updateitem()

photos()
photos.add()

settings()
settings.all()
settings.set()

specials()
specials.search()
specials.add()
specials.flag()

events()
events.categories()
events.search()

pages()
pages.venues()

multi()

Testing

In order to run the tests:

Copy foursquare/tests/_creds.example.py to foursquare/tests/_creds.py
Fill in your personal credentials to run the tests (_creds.py is in .gitignore)
Run nosetests
- If you are hitting quota or rate-limiting errors, try setting the FOURSQUARE_TEST_THROTTLE env variable to an integer like 5. It will pause for this many seconds after every test.

Improvements

Feel free to send pull requests for any improvements you make.

TODO

Bring in new endpoints as they emerge
Test coverage for write methods

Code status

Packaging

pip install twine wheel
python setup.py sdist bdist_wheel
twine upload dist/*