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

A custom Discord Rich Presence to display when you're studying so you're stupid friends won't disturb you when you're studying.

Studying RPC Description A custom Discord Rich Presence to display when you're studying so you're stupid friends won't disturb you when you're studyin

John Edmerson Pizarra 4 Nov 19, 2022
JAKYM, Just Another Konsole YouTube-Music. A command line based Youtube music player written in Python with spotify and youtube playlist support

Just Another Konsole YouTube-Music Overview I wanted to create this application so that I could use the command line to play music easily. I often pla

Mayank Jha 73 Jan 01, 2023
A telegram bot writen in python for mirroring files on the internet to Google Drive

owner of this repo :- AYUSH contact me :- AYUSH Slam Mirror Bot This is a telegram bot writen in python for mirroring files on the internet to our bel

Thanusara Pasindu 1 Nov 21, 2021
The Most advanced and User-Friendly Google Collab NoteBook to download Torrent directly to Google Drive with File or Magnet Link support and with added protection of Timeout Preventer.

Torrent To Google Drive (UI Added! 😊 ) A Simple and User-Friendly Google Collab Notebook with UI to download Torrent to Google Drive using (.Torrent)

Dr.Caduceus 33 Aug 16, 2022
Discord bot do sprawdzania ceny pizzy.

Discord bot do sprawdzania ceny pizzy w pizzeri Bombola. Umieszczony jest na platformie Heroku, dzięki czemu działa 24/7. Commands List Info: Jako com

1 Sep 18, 2021
Filters to block and remove copycat-websites from DuckDuckGo and Google. Specific to dev websites like StackOverflow or GitHub.

uBlock-Origin-dev-filter Filters to block and remove copycat-websites from DuckDuckGo and Google. Specific to dev websites like StackOverflow or GitHu

1.7k Dec 30, 2022
Бот Telegram для Школы в Капотне (ЦО № 1858)

co1858 Telegram Bot Активно разрабатывался в 2015-2016 году как учебный проект, с целью научиться создавать ботов для Telegram. Бот автоматически парс

Ilya Pavlov 4 Aug 30, 2022
Estimate the total emissions for popular CryptoArt platforms.

cryptoart-footprint Estimate the total CO2 footprint for popular CryptoArt platforms. The goal is to accurately quantify the ecological damage of Ethe

Kyle McDonald 182 Oct 12, 2022
A discord bot for tracking Iranian Minecraft servers and showing the statistics of them

A discord bot for tracking Iranian Minecraft servers and showing the statistics of them

MCTracker 20 Dec 30, 2022
Trading bot - A Trading bot With Python

Trading_bot Trading bot intended for 1) Tracking current prices of tokens 2) Set

Tymur Kotkov 29 Dec 01, 2022
A simple program to display current playing from Spotify app on your desktop

WallSpot A simple program to display current playing from Spotify app on your desktop How to Use: Linux: Currently Supports GNOME and KDE. If you want

Nannan 4 Feb 19, 2022
Anime Streams Scrapper for Telegram Publicly Available for everyone to use

AniRocks Project Structure: ╭─ bot ├──── plugins: directory stored all the plugins ├──── utils: a directory of Utilities to help bot Client to create

ポキ 11 Oct 28, 2022
discord bot made in discord.py

udeline discord bot made in discord.py, which's main features include: general use server moderation fun commands other cool commands dependencies dis

1 Feb 08, 2022
A mood based crypto tracking application.

Crypto Bud - API A mood based crypto tracking application. The main repository is private. I am creating the API before I connect everything to the ma

Krishnasis Mandal 1 Oct 23, 2021
Tickergram is a Telegram bot to look up quotes, charts, general market sentiment and more.

Tickergram is a Telegram bot to look up quotes, charts, general market sentiment and more.

Alberto Ortega 25 Nov 26, 2022
Production Ontology Merging (PrOM) Framework

Production Ontology Merging (PrOM) Framework OWL 2 DL ontology merging framework tailored to the production domain Features preprocessing: translation

4 Nov 02, 2022
Modified Version Of Media Search bot

Modified Version Of Media Search bot

1 Oct 09, 2021
Export Statistics for a Telegram Group Chat

Telegram Statistics Export Statistics for a Telegram Group Chat How to Run First, in main repo directory, run the following code to add src to your PY

Ali Hejazizo 22 Dec 05, 2022
Eva Maria Bot With Python

Eva Maria Bot Features Auto Filter Manual Filter IMDB Admin Commands Broadcast Index IMDB search Inline Search Random pics ids and User info Stats, Us

Aadhi 3 Jan 06, 2022
A simple Discord bot that can fetch definitions and post them in chat.

A simple Discord bot that can fetch definitions and post them in chat. If you are connected to a voice channel, the bot will also read out the definition to you.

Tycho Bellers 4 Sep 29, 2022