Playing with Foursquare API with Python

Wednesday, December 21, 2011

Hi all,

I'd like to share a project that I am developing that it may be useful for anyone who wants to create datasets from mobile location networks.  Specifically, I developed a wrapper in Python for accessing the Foursquare API called PyFoursquare

For anyone who doesn't know what is Foursquare, it is a popular mobile social-location network with more 10.000.000 of users around the world. The idea is that you can share your current location with your friends and as result discover new places, find where your friends are and even check some tips and recommendations about a place and what to do when you arrive there. It is an amazing project with lots of data available for anyone who wants to develop new apps for connect or mine (data mining) its data!

Foursquare Mobile Application

This Python API is one of the results of my master degree project where I proposed a new architecture for mobile recommenders that fetches reviews from social networks to improve the explanation and the quality of the given recommendations.  I  used this library to collect tips (text reviews) from Foursquare from places at my neighborhood Recife, Brazil.  This API was a little messy, so I decided to clean it up, organize and documment it for publish for the open-source community.

One of advantages of this API is that you can handle each entity from the Foursquare data as Model object. So instead of handling with json dictionaries, I encapsulate the results in the respective models (Venue, Tips, User, etc.) and access its attributes as common object in Python!

I inspired myself at the work of Joshua at Tweepy, which is a Python library for Twitter.  In this version released 0.0.1 I only implemented some API's such as search/venues,  venue_details and venue_tips.  In future releases I pretend to add more models and support for more API methods available at Foursquare.

How can you use it at your project ?

It is simple! Just install it by downloading at the Github's home project, extract the source from the tar.gz and  at the directory of the project run the command below:

$ python install

or the easier way is to install by the command easy_install:

$ easy_install pyfoursquare

After that, you can  simple test by running the command below at your Python Shell

>>> import pyfoursquare

Now let's see how you can get started with the PyFoursquare:

First you need to create an application at Foursquare. The link is this.  There  you can also get further information about the API, another libraries and several applications using the Foursquarw API's.  

The Foursquare Developer's Settings

After creating your application, you must get the client_id and your client_secret. Those keys will be important to connect the app to the users' accounts.  Foursquare uses the secure authentication based on OAuth2.  In PyFoursquareAPI, you won't need to handle with all steps provided by OAuth2.  It already encapsulates all the steps and handshakes between your app and Foursquare servers. \m/ 

Below the  code you must write for authenticate an user to connect to your app:

After the user  authorized, you now can instantiate the PyFoursquare API.  It will give you access to the Foursquare API methods.  I implemented several methods, but feel free to add new ones! Don't forget to submit the final results as pull requests at the project's repository at Github.

In this example I fetched a venue by giving as input the latitude and longitude and querying for the place with the name 'Burburinho'.  Burburinho is a popular bar nearby where I work!

Source code

Now you can access the result and access the Venue as a Python Object. All elements of the Venue are represented as attributes of the object Venue at PyFoursquare. The goal is to make easier the life of the developer when he access the Foursquare API by parsing all the JSON (the result) and placing in the correct model for him.

I expect you enjoyed this API. Feel free to use it at your applications or research!  I'd like to thank the Foursquare team for expose their data by providing those API's!  For data mining researchers instered in mobile location data, it is a mine of gold!

Further information about PyFoursquare, you can find here.

Feel free to give sugestions, improvements and comments,


Marcel Caraciolo


  1. Awesome work Marcel!
    Thanks for sharing it!


  2. Marcel i had trouble with the installation:
    "Traceback (most recent call last):
    File "", line 20, in
    from setuptools import setup, find_packages"

    Seems that some models are missing. Or i did something wrong?

  3. It was a trouble with my setup;
    Solved downloading a x64 version on:

  4. I will check at another computer and give a feedback! THanks for the reply!

  5. Having problem with import. Did easy_install and still getting

    File "", line 1, in
    import foursquare
    ImportError: No module named foursquare

  6. Welcome to Wiztech Automation - Embedded System Training in Chennai. We have knowledgeable Team for Embedded Courses handling and we also are after Job Placements offer provide once your Successful Completion of Course. We are Providing on Microcontrollers such as 8051, PIC, AVR, ARM7, ARM9, ARM11 and RTOS. Free Accommodation, Individual Focus, Best Lab facilities, 100% Practical Training and Job opportunities.

    Embedded System Training in chennai
    Embedded System Training Institute in chennai
    Embedded Training in chennai
    Embedded Course in chennai
    Best Embedded System Training in chennai
    Best Embedded System Training Institute in chennai
    Best Embedded System Training Institutes in chennai
    Embedded Training Institute in chennai
    Embedded System Course in chennai
    Best Embedded System Training in chennai

  7. WIZTECH Automation, Anna Nagar, Chennai, has earned reputation offering the best automation training in Chennai in the field of industrial automation. Flexible timings, hands-on-experience, 100% practical. The candidates are given enhanced job oriented practical training in all major brands of PLCs (AB, Keyence, ABB, GE-FANUC, OMRON, DELTA, SIEMENS, MITSUBISHI, SCHNEIDER, and MESSUNG)

    PLC training in chennai
    Automation training in chennai
    Best plc training in chennai
    PLC SCADA training in chennai
    Process automation training in chennai
    Final year eee projects in chennai
    VLSI training in chennai

  8. Embedded system training: Wiztech Automation Provides Excellent training in embedded system training in Chennai - IEEE Projects - Mechanical projects in Chennai. Wiztech provide 100% practical training, Individual focus, Free Accommodation, Placement for top companies. The study also includes standard microcontrollers such as Intel 8051, PIC, AVR, ARM, ARMCotex, Arduino, etc.

    Embedded system training in chennai
    Embedded Course training in chennai
    Matlab training in chennai
    Android training in chennai
    LabVIEW training in chennai
    Robotics training in chennai
    Oracle training in chennai
    Final year projects in chennai
    Mechanical projects in chennai
    ece projects in chennai

  9. WIZTECH Automation, Anna Nagar, Chennai, has earned reputation offering the best automation training in Chennai in the field of industrial automation. Flexible timings, hands-on-experience, 100% practical. The candidates are given enhanced job oriented practical training in all major brands of PLCs (AB, Keyence, ABB, GE-FANUC, OMRON, DELTA, SIEMENS, MITSUBISHI, SCHNEIDER, and MESSUNG)

    PLC training in chennai
    Automation training in chennai
    Best plc training in chennai
    PLC SCADA training in chennai
    Process automation training in chennai
    Final year eee projects in chennai
    VLSI training in chennai

  10. Thanks for sharing this precious information. I like your concern in the post which is very useful for me.
    I like your information which is very useful for me. Thanks.

    Embedded systems chandigarh

  11. Wiztech Automation Solutions is that the best PLC SCADA Marketing Communication Management: A Holistic Approach for Increased Profitability Training institute in Chennai and it's generating variety of PLC Engineers through its robust pillars like quality education, effective coaching, intimate with staffs to guide each student, spacious laboratories, Un-limited sensible sessions to boost their data as per the conditions of Automation trade.

    PLC, SCADA training in chennai
    PLC training in chennai
    Automation training in chennai

  12. Wiztech Automation Research and Development Unit, is one of front line training organizations in Kerala. Started in the year 2006, Wiztech is on the verge of completing one decade in the field of training in industrial automation. Wiztech Automation is focused on imparting quality training to the newly graduated engineers and also those employed in industrial units, who look for skill up-gradation. Being an IAO and ISO certified organization; the company's directors have been focusing on the mission to engage their time and energies to develop facilities for providing quality training to inculcate employable engineering skills.

    PLC training in Cochin, Kerala
    Automation training in Cochin, Kerala
    Embedded System training in Cochin, Kerala
    VLSI training in Cochin, Kerala
    PLC training institute in Cochin, Kerala
    Embedded training in Cochin, Kerala
    Best plc training in Cochin, Kerala

  13. Nice blogs about Mastering Python With Mobile Testing at The
    Mastering Python With Mobile Testing training in bangalore

  14. Thanks for providing good information,Thanks for your sharing python Online Training

  15. Gaining Python certifications will validate your skills and advance your career.
    python certification

  16. This comment has been removed by the author.

  17. myTectra the Market Leader in Artificial intelligence training in Bangalore
    myTectra offers Artificial intelligence training in Bangalore using Class Room. myTectra offers Live Online Design Patterns Training Globally.Read More

  18. I have read this blog it amazing blog; it’s providing more information about "Playing with Foursquare API with Python" topic. Thanks for sharing, Keep share more post.

    PHP industrial training mohali
    web designing training mohali
    SEO training in mohali
    6/Six months PHP industrial training in mohali

  19. very useful and informative blog . Thank you for your information.If you are searching for Python training institute in kochi visti us
    python training in kochi ,
    python course in kochi

  20. It’s hard to come by experienced people about this subject, but you seem like you know what you’re talking about! Thanks.
    Java Training in Bangalore
    Python Training In Bangalore

  21. Usually I never comment on blogs but your article is so convincing that I never stop myself to say something about it. You’re doing a great job Man learn Python Online Course

  22. Hey there, You have done a fantastic job. I’ll definitely digg it and personally suggest to my friends. I am confident they will be benefited from this web site.This is most informative and also this post most user friendly and super navigation to all posts... Thank you so much for giving this information to me.Really you have done great job,There are may person searching about that now they will find enough resources by your post.
    DevOps Training in Chennai

    DevOps Online Training in Chennai

    DevOps Training in Bangalore

    DevOps Training in Hyderabad

    DevOps Training in Coimbatore

    DevOps Training

    DevOps Online Training

  23. Really it is very useful for us..... the information that you have shared is really useful for everyone.Nice article i have ever read information's like's really awesome the way you have delivered your ideas.i hope you will add more content in your blog.PHP Training in Chennai

    PHP Online Training in Chennai

    Machine Learning Training in Chennai

    iOT Training in Chennai

    Blockchain Training in Chennai

    Open Stack Training in Chennai

  24. Very interesting to read this article.I would like to thank you for the efforts you had made for writing this awesome article. This article inspried me to read more. keep it up.

    AWS training in Chennai

    AWS Online Training in Chennai

    AWS training in Bangalore

    AWS training in Hyderabad

    AWS training in Coimbatore

    AWS training

  25. Thanks for sharing an informative blog keep rocking bring more details.I like the helpful info you provide in your articles. I’ll bookmark your weblog and check again here regularly. I am quite sure I will learn much new stuff right here! Good luck for the next!
    Artificial Intelligence Training in Chennai

    Ai Training in Chennai

    Artificial Intelligence training in Bangalore

    Ai Training in Bangalore

    Artificial Intelligence Training in Hyderabad | Certification | ai training in hyderabad

    Artificial Intelligence Online Training

    Ai Online Training

    Blue Prism Training in Chennai

  26. Java is not easy or hard. ... Many beginners had problem in concepts of java but once you start programming and playing with it's GUI features you will love java. Java is a strong language which run fast and supports almost all platforms like windows, Linux, mac. You just have to install JVM (java virtual machine).
    Java training in Chennai

    Java Online training in Chennai

    Java Course in Chennai

    Best JAVA Training Institutes in Chennai

    Java training in Bangalore

    Java training in Hyderabad

    Java Training in Coimbatore

    Java Training

    Java Online Training

  27. Thanks for one marvelous posting! I enjoyed reading it; you are a great author. I will make sure to bookmark your blog and may come back someday. I want to encourage that you continue your great posts.
    oracle training in chennai

    oracle training institute in chennai

    oracle training in bangalore

    oracle training in hyderabad

    oracle training

    oracle online training

    hadoop training in chennai

    hadoop training in bangalore

  28. This professional hacker is absolutely reliable and I strongly recommend him for any type of hack you require. I know this because I have hired him severally for various hacks and he has never disappointed me nor any of my friends who have hired him too, he can help you with any of the following hacks:

    -Phone hacks (remotely)
    -Credit repair
    -Bitcoin recovery (any cryptocurrency)
    -Make money from home (USA only)
    -Social media hacks
    -Website hacks
    -Erase criminal records (USA & Canada only)
    -Grade change
    -funds recovery

    Email: onlineghosthacker247@ gmail .com