The Foursquare API client for Python

Mike Lewis

Last update: Dec 19, 2022

Related tags

Third-party APIs Wrappers foursquare

Overview

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 paramater 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/*

License

Comments

Pip package version

Hey,

I noticed that for me installing from pip fetches an outdated version of the library, so I defaulted to pip install from a git commit - would it be possible to update the version available via pip, surely this might confuse other users as well, when they try use features documented here, but not available in the latest version installed via pip?

Thanks for the great package :)

opened by kontur 13
SSL error

I updated to the latest api version and now I am getting these ssl errors -

FoursquareException: Error connecting with foursquare API: [Errno 1] _ssl.c:507: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

Any idea what is going on?

I am OS X 10.9

opened by szs8 12

FoursquareException: you are using automation tools to browse the website

Starting yesterday, I can no longer retrieve Foursquare data with this library.

client.users.checkins() is raising a FoursquareException, which appears to contain HTML instead of a JSON response:

Invalid response: <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Access to this page has been denied.</title> <link href="https://fonts.googleapis.com/css?family=Open+Sans:300" rel="stylesheet"> <style> html, body { margin: 0; padding: 0; font-family: 'Open Sans', sans-serif; color: #000; } a { color: #c5c5c5; text-decoration: none; } .container { align-items: center; display: flex; flex: 1; justify-content: space-between; flex-direction: column; height: 100%; } .container > div { width: 100%; display: flex; justify-content: center; } .container > div > div { display: flex; width: 80%; } .customer-logo-wrapper { padding-top: 2rem; flex-grow: 0; background-color: #fff; visibility: hidden; } .customer-logo { border-bottom: 1px solid #000; } .customer-logo > img { padding-bottom: 1rem; max-height: 50px; max-width: 100%; } .page-title-wrapper { flex-grow: 2; } .page-title { flex-direction: column-reverse; } .content-wrapper { flex-grow: 5; } .content { flex-direction: column; } .page-footer-wrapper { align-items: center; flex-grow: 0.2; background-color: #000; color: #c5c5c5; font-size: 70%; } @media (min-width: 768px) { html, body { height: 100%; } } </style> <!-- Custom CSS -->  </head> <body> <section class="container"> <div class="customer-logo-wrapper"> <div class="customer-logo"> <img src="" alt="Logo"/> </div> </div> <div class="page-title-wrapper"> <div class="page-title"> <h1>Please verify you are a human</h1> </div> </div> <div class="content-wrapper"> <div class="content"> <div id="px-captcha"> </div> <p> Access to this page has been denied because we believe you are using automation tools to browse the website. </p> <p> This may happen as a result of the following: </p> <ul> <li> Javascript is disabled or blocked by an extension (ad blockers for example) </li> <li> Your browser does not support cookies </li> </ul> <p> Please make sure that Javascript and cookies are enabled on your browser and that you are not blocking them from loading. </p> <p> Reference ID: #4d499fa0-d9ec-11e8-8e00-8d9b5d67cafa </p> </div> </div> <div class="page-footer-wrapper"> <div class="page-footer"> <p> Powered by <a href="https://www.perimeterx.com/whywasiblocked">PerimeterX</a> , Inc. </p> </div> </div> </section> <!-- Px --> <script> window._pxAppId = 'PX0UqK4c76'; window._pxJsClientSrc = '/0UqK4c76/init.js'; window._pxFirstPartyEnabled = true; window._pxVid = ''; window._pxUuid = '4d499fa0-d9ec-11e8-8e00-8d9b5d67cafa'; window._pxHostUrl = '/0UqK4c76/xhr'; </script> <script src="/0UqK4c76/captcha/captcha.js?a=c&u=4d499fa0-d9ec-11e8-8e00-8d9b5d67cafa&v=&m=0"></script> <!-- Custom Script -->  </body> </html>

with the relevant part of the message being:

Access to this page has been denied because we believe you are using automation tools to browse the website. This may happen as a result of the following:

Javascript is disabled or blocked by an extension (ad blockers for example)

Your browser does not support cookies

Please make sure that Javascript and cookies are enabled on your browser and that you are not blocking them from loading.

Is there anything this library can do to mitigate this?

opened by jacebrowning 9

Python 3?

Hello, I'm getting an when trying to install for Python 3.

\foursquare__init__.py", line 690 except FoursquareException, e: SyntaxError: invalid syntax

Love the library! Any idea on when a Python 3 compatible version will be ready?

opened by dodger487 8
Fails to install with pip 1.4

The package appears to fail with the recently released pip 1.4. Looking at the verbose output it appears to consider all of the releases as pre-release and the new pip will not install these by default.

From their changelog: BACKWARD INCOMPATIBLE pip now only installs stable versions by default, and offers a new --pre option to also find pre-release and development versions. (Pull #834)

It then complains that no version can be found to install.

verbose logging below: Downloading/unpacking foursquare Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20120429.tar.gz#md5=f5bd955d24fafa00b65b18c65f811c26 (from https://pypi.python.org/simple/foursquare/), version 20120429 is a pre-release (use --pre to allow). Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20120608.tar.gz#md5=ae562f2b7defca967e21ba2130d53271 (from https://pypi.python.org/simple/foursquare/), version 20120608 is a pre-release (use --pre to allow). Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20120430.tar.gz#md5=681626986a6118af72e74285ee2b5f47 (from https://pypi.python.org/simple/foursquare/), version 20120430 is a pre-release (use --pre to allow). Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20130212.tar.gz#md5=b92011db77f4d53ddb4023da2ff86908 (from https://pypi.python.org/simple/foursquare/), version 20130212 is a pre-release (use --pre to allow). Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20120418.tar.gz#md5=1d5ef2fccde05d84c7dc612f106b9bd8 (from https://pypi.python.org/simple/foursquare/), version 20120418 is a pre-release (use --pre to allow). Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20130131.tar.gz#md5=ec4260d459df0cd6931d1957af641ae3 (from https://pypi.python.org/simple/foursquare/), version 20130131 is a pre-release (use --pre to allow). Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20120716.tar.gz#md5=4cb485f3ad489e89dba5e44f2c7075df (from https://pypi.python.org/simple/foursquare/), version 20120716 is a pre-release (use --pre to allow). Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20130402.tar.gz#md5=162bbc21203e9527e552e1694d596b6e (from https://pypi.python.org/simple/foursquare/), version 20130402 is a pre-release (use --pre to allow). Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20130707.tar.gz#md5=80d4c753161672a69160dd36d77c93eb (from https://pypi.python.org/simple/foursquare/), version 20130707 is a pre-release (use --pre to allow). Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20130626.tar.gz#md5=4e6f10a0c5f40e94ce6bc036d3fd30a1 (from https://pypi.python.org/simple/foursquare/), version 20130626 is a pre-release (use --pre to allow). Ignoring link https://pypi.python.org/packages/source/f/foursquare/foursquare-20130702.tar.gz#md5=d9a4023a7ee1718f14bd62a103a76232 (from https://pypi.python.org/simple/foursquare/), version 20130702 is a pre-release (use --pre to allow). Could not find a version that satisfies the requirement foursquare (from versions: 20120429, 20120608, 20120430, 20130212, 20120418, 20130131, 20120716, 20130402, 20130707, 20130626, 20130702)

opened by pg1671 7
Can we get a new PyPI release?

It appears to be a couple years since the last release, but there are newer commits.

Additionally the 1!2016.9.12 format does not appear to be compatible with PEP 440.

opened by jacebrowning 6
Error with queries
Hi, i'm not sure that i'm doing all is right. But, as simple instance - userless query:

import foursquare credentials = foursquare.Foursquare(client_id='CLIENT_ID',client_secret='CLIENT_SECRET') detail = credentials.tips('4b5e662a70c603bba7d790b4')

And i receive:

foursquare.FoursquareException: Error connecting with foursquare API: [Errno 1] _ssl.c:504: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

I tried with access token, as i know my acceess token. import foursquare

credentials = foursquare.Foursquare(client_id='CLIENT_ID',client_secret='CLIENT_SECRET') credentials = foursquare.Foursquare(access_token='MY_ACCESS_TOKEN) detail = credentials.tips('4b5e662a70c603bba7d790b4')

Same error.

P.S. Oh, i solved my problem. I installed from pip, instead install from github. Thank you.
opened by Rukomoynikov 6

unicode error?

lat=37.800577
lng=-122.438385
radius=250

1
File "./server/provider.py" line 140 in get
venues = Foursquare.get(lat, lng, radius, intent="checkin")
2
File "./server/fsq.py" line 33 in get
result = cls.handle.venues.search(params)
3
File "/var/www/myapp/env/local/lib/python2.7/site-packages/foursquare/__init__.py" line 388 in search
return self.GET('search', params, multi=multi)
4
File "/var/www/myapp/env/local/lib/python2.7/site-packages/foursquare/__init__.py" line 248 in GET
return self.requester.GET(self._expanded_path(path), *args, **kwargs)
5
File "/var/www/myapp/env/local/lib/python2.7/site-packages/foursquare/__init__.py" line 172 in GET
return _get(url, headers=headers, params=params)['response']
6
File "/var/www/myapp/env/local/lib/python2.7/site-packages/foursquare/__init__.py" line 745 in _get
return _process_response(response)
7
File "/var/www/myapp/env/local/lib/python2.7/site-packages/foursquare/__init__.py" line 773 in _process_response
errmsg = u'Invalid response: {0}'.format(response.text())
TypeError: 'unicode' object is not callable

I'm not quiet sure why this happens? but this happens every once-in-a-while.

opened by jamesonjlee 5

urlencoding params causing zero results
I have this case where if I query the API directly from browser like this -

https://api.foursquare.com/v2/venues/search?client_id=RACMYEFHCDSJBZETAJL1F4TRXBJX245NPRH0M1T1FEE&client_secret=VV1J5CPJHXHOTRMXF1DLBVL3VYU3XNSR2KGQX2RNDDETH5&query=Mirch%20Masala%20Restaurant%20&%20Bar&ll=22.523152,88.364743&v=20130815&radius=1000&count=1

I get results. But when I use this library and form this query -

fsq.venues.search(params={'query': 'Mirch Masala Restaurant & Bar', 'll': '22.523152,88.364743', 'radius': 1000, 'count': 1, "v": "20130815"})

this URL is being requested by the library -

https://api.foursquare.com/v2/venues/search?count=1&ll=22.523152%2C88.364743&radius=1000&client_id=RACMYEFHCDSJBZETAJL1F4TRXBJX245NPRH0M1T1FEE&v=20130730&query=Mirch+Masala+Restaurant+%26+Bar&client_secret=VV1J5CPJHXHOTRMXF1DLBVL3VYU3XNSR2KGQX2RNDDETH5

Which returns no result.

This library is urlencoding the query like Mirch+Masala+Restaurant+%26+Bar instead of Mirch%20Masala%20Restaurant%20&%20Bar which is causing it to return zero results.

PS: stripping few characters from the token, please use your own.
opened by iambibhas 5
Remove debug statement containing access_token
The removed statement was logging the following message:

GET url: https://api.foursquare.com/v2/users/self/checkins?oauth_token=XXXXXXXXXXXXXXXXXXXXXX&v=20130402 headers:{} data:

Logging sensitive user credentials (in this case OAuth v2 access token) is dangerous
opened by ahmetb 5
Changed 'response_type' to 'token'

'&response_type=code' no longer works for the auth_uri, foursquare's oauth docs state to use '&response_type=token' instead (https://developer.foursquare.com/overview/auth)

opened by jasminegao 5
Unavailable for accessing venue

When I try the example code "client.venues('40a55d80f964a52020f31ee3')", an error occures: foursquare.Deprecated: Usage of the V2 Places API has been deprecated for new Projects. Please see our updated documentation for V3 for more details: https://docs.foursquare.com/reference

opened by zelo2 1
Provide access to rate_reset, a response header

Foursquare API returns a 403 error, and the response object returned by their API will be empty, if user is over their quota limits. They will also include a X-RateLimit-Reset header in the response, which is a timestamp that corresponds to when the rate limits will reset. This info can be found here: https://developer.foursquare.com/docs/places-api/rate-limits/. The proposed changes are a start, there may be additional exception handling that needs to be done to fully implement this change. However, I think the author of this library may know better where changes need to be made. However, for this library to be useful for users with quotas, I think this change is necessary. Feel free to add to, make comments, and build off of this proposal.

opened by petros-p 1

Owner

Mike Lewis

GitHub https://pypi.python.org/pypi/foursquare/

Beyonic API Python official client library simplified examples using Flask, Django and Fast API.

46 Sep 1, 2022

Python API Client for Twitter API v2

?? Python Client For Twitter API v2 ?? Why Twitter Stream ? Twitter-Stream.py a python API client for Twitter API v2 now supports FilteredStream, Samp

31 Nov 19, 2022

Dns-Client-Server - Dns Client Server For Python

Dns-client-server DNS Server: supporting all types of queries and replies. Shoul

1 Feb 15, 2022

Raphtory-client - The python client for the Raphtory project

Raphtory Client This is the python client for the Raphtory project Install via p

5 Apr 28, 2022

Drcom-pt-client - Drcom Pt version client with refresh timer

drcom-pt-client Drcom Pt version client with refresh timer Dr.com Pt版本客户端可用于网页认

4 Nov 16, 2022

Official Python client for the MonkeyLearn API. Build and consume machine learning models for language processing from your Python apps.

MonkeyLearn API for Python Official Python client for the MonkeyLearn API. Build and run machine learning models for language processing from your Pyt