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

Issues
  • 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
  • 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
  • Coverage n ujson monkey patch

    Coverage n ujson monkey patch

    opened by woozyking 6
  • 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
  • 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
  • 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 45 Nov 18, 2021
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 17 Jan 4, 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 3 Jan 4, 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 148 Dec 14, 2021
🖥️ Python - P1 Monitor API Asynchronous Python Client

??️ Asynchronous Python client for the P1 Monitor

Klaas Schoute 2 Jan 10, 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 51 Jan 30, 2021
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 24 Jan 14, 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 488 Jan 7, 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 Jan 11, 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 234 Jan 9, 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 342 Dec 30, 2021
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 648 Dec 23, 2021
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 644 Jan 16, 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 260 Jan 18, 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 46 Jan 10, 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 5.9k Jan 12, 2022
Python client library for Google Maps API Web Services

Python Client for Google Maps Services Description Use Python? Want to geocode something? Looking for directions? Maybe matrices of directions? This l

Google Maps 3.5k Jan 12, 2022
A very simple Salesforce.com REST API client for Python

Simple Salesforce Simple Salesforce is a basic Salesforce.com REST API client built for Python 3.5, 3.6, 3.7 and 3.8. The goal is to provide a very lo

simple salesforce 1.2k Jan 18, 2022