The Foursquare API client for Python

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')

or

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

  • Build Status

Packaging

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

License

MIT License. See LICENSE Copyright (c) 2020 Mike Lewis

Comments
  • Pip package version

    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

    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

    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?

    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

    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?

    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

    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?

    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

    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

    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'

    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

    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

    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
Beyonic API Python official client library simplified examples using Flask, Django and Fast API.

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

Harun Mbaabu Mwenda 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

Twitivity 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

Nishant Badgujar 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

Raphtory 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版本客户端 可用于网页认

null 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

MonkeyLearn 157 Nov 22, 2022
🖥️ Python - P1 Monitor API Asynchronous Python Client

??️ Asynchronous Python client for the P1 Monitor

Klaas Schoute 9 Dec 12, 2022
Python API Client for Close

Close API A convenient Python wrapper for the Close API. API docs: http://developer.close.com Support: [email protected] Installation pip install clos

Close 56 Nov 30, 2022
Python client for CoinPayments API

pyCoinPayments - Python API client for CoinPayments Updates This library has now been converted to work with python3 This is an unofficial client for

James 27 Sep 21, 2022
DEPRECATED - Official Python Client for the Discogs API

⚠️ DEPRECATED This repository is no longer maintained. You can still use a REST client like Requests or other third-party Python library to access the

Discogs 483 Dec 31, 2022
Python Client for Instagram API

This project is not actively maintained. Proceed at your own risk! python-instagram A Python 2/3 client for the Instagram REST and Search APIs Install

Facebook Archive 2.9k Dec 30, 2022
A Python Client for News API

newsapi-python A Python client for the News API. License Provided under MIT License by Matt Lisivick. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRAN

Matt Lisivick 281 Dec 29, 2022
SmartFile API Client (Python).

A SmartFile Open Source project. Read more about how SmartFile uses and contributes to Open Source software. Summary This library includes two API cli

SmartFile 19 Jan 11, 2022
Python client for the Socrata Open Data API

sodapy sodapy is a python client for the Socrata Open Data API. Installation You can install with pip install sodapy. If you want to install from sour

Cristina 368 Dec 9, 2022
Python client for the Echo Nest API

Pyechonest Tap into The Echo Nest's Musical Brain for the best music search, information, recommendations and remix tools on the web. Pyechonest is an

The Echo Nest 655 Dec 29, 2022
A Python Tumblr API v2 Client

PyTumblr Installation Install via pip: $ pip install pytumblr Install from source: $ git clone https://github.com/tumblr/pytumblr.git $ cd pytumblr $

Tumblr 677 Dec 21, 2022
A super awesome Twitter API client for Python.

birdy birdy is a super awesome Twitter API client for Python in just a little under 400 LOC. TL;DR Features Future proof dynamic API with full REST an

Inueni 259 Dec 28, 2022
Cord Python API Client

Cord Python API Client The data programming platform for AI ?? Features Minimal low-level Python client that allows you to interact with Cord's API Su

Cord 52 Nov 25, 2022
Pure Python 3 MTProto API Telegram client library, for bots too!

Telethon ⭐️ Thanks everyone who has starred the project, it means a lot! Telethon is an asyncio Python 3 MTProto library to interact with Telegram's A

LonamiWebs 7.3k Jan 1, 2023