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. 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

  7. 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

  8. 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

  9. This comment has been removed by the author.

  10. 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

  11. 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

  12. 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

  13. 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

  14. 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

  15. We've been working in the field of creating counterfeit archives and cash for quite a while. That is the reason we realize every one of the traps and how to keep away from them. We give cautious consideration to our clients' requirements and give a valiant effort to furnish them with the ideal phony cash safely. We take every one of the vital measures to keep your character classified, so you ought not concern that somebody will realize that you purchased our items
    counterfeit notes for sale

  16. The vast majority of us have an enthusiasm for driving. Nonetheless, with tight guidelines set up, it is regularly considered as an advantage. deiver's license Since you own the vehicle doesn't mean you can take off. Regardless of whether you have a SUV, hatchback, or car, you need a driving permit to work an engine vehicle.

  17. It is so nice blog. I was really satisfied by seeing this blog.
    workday course
    workday online course

  18. Studyprovider has experts team are giving the homework help, assignment help, report, thesis, research writing services and psychology homework help available 24/7 seven days a week contact now.

  19. Superb blog! I did not know that freelancing could help me out in such miraculous ways. Satisfactory success is slow as far as the career in a job as a blockchain developer is concerned. The Blockchain developer salary greatly varies from one to another, but freelancing overcomes these in-house hiring limitations.
    Please share some valuable platforms to work with good freelancing income.

  20. When you have a lot of debt, it can seem like there’s no end in sight. If you’re struggling to keep up with your loan payments, a debt management licensing plan may be the answer. A debt management plan helps you manage your financial obligations by consolidating your loans into one payment and reducing the amount you owe on each loan.

  21. Your insights on your article are very informative and well-written. Thank you for sharing this knowledge.

    Java fullstack training in hyderabad


  22. I am thoroughly impressed by your excellent post and review. Please continue to produce such remarkable content. Thank you!

    CMA Colleges in Hyderabad

  23. I'm delighted to express that your post is quite captivating. I've gained fresh insights from your write-up, and you're doing an exceptional job. Keep up the good work. For More Visit the below website

    Best Colleges in Hyderabad for BBA

  24. I haven't come across such a valuable resource in a long time. It is excellently written and contains incredibly useful information. I truly cannot express my gratitude enough for sharing it.

    Colleges for BBA in Hyderabad

  25. Your blog is truly amazing. The content is informative and full of knowledge. I had a great time reading your article. Please continue to share more content like this. Thank you.

    Best Colleges in Hyderabad For BBA

  26. "I love how your articles break down complex tech concepts into easily digestible pieces. It makes staying updated on the latest trends so much more enjoyable!"
    Python full stack training institute in KPHB