Learn Foursquare API Basic Application in Python
Foursquare is an independent location data platform for understanding how people move through the real world, which provides data describing places and venues, such as geographical location, category, working hours, full address, and so on. Creating a developer account to use their API is quite straightforward and the easiest compared to other providers. Therefore, let’s start learning how to use the Foursquare API to leverage location data.
Below topics will be introduced in this article:
- Some rules need to know before using
- Search for a specific venue category
- Explore a particular venue
- Explore a geographical location
- Get trending venues around a location
- During the process, learn how to construct a URL to send a request to API
Let’s start!
1. Some rules need to know before using
Type of user
There are two tiers of users for Foursquare API: for developers or for enterprises. This article will focus on developers.
Under developers, there are three types of developers: sandbox user and personal user are free, starts-up user will be charged. Let’s focus on the two free developers.
Rate limit
When signing in, the default setting is a sandbox user, there are some limitations people need to know:
- There is a limit of 950 Regular API Calls per day and 50 Premium API Calls per day for Sandbox Tier Accounts.
- Only one photo and one tip can be retrieved per venue.
Once you verified your personal info, means input your valid credit card information, you will be upgraded to personal account, with it:
- 99,500 regular calls and 500 premium calls per day. That is actually 100 times more calls than the default sandbox account.
- You’ll also get access to over 105 million venues or points of interest.
- But you still only get two photos and two tips per venue.
You can still stay with sandbox users for this part, but please keep in mind the limitation of the following process.
Types of calls
What are regular and premium calls?
Regular endpoints include basic venue firmographic data, category, and ID. Premium endpoints include rich content such as ratings, URLs, photos, tips, menus, etc. For example, search for a specific venue around a given location is regular, but learn more about a specific venue is Premium.
Error codes
Once the limits are exceeded, there are various codes to show the status, like error code 403, if the rate limit this hour exceeded,429 if the daily call quota exceeded. If there is no venue in your query, but there should have usually, it might be better to check the response code.
After you sign in with your count, doesn’t matter sandbox or personal, you will get the client ID and client secret, keep them to you, you will need to pass these credentials every time when you make a call to the API.
Once signing in, everything being prepared, let’s take a real venue as an example.
Let’s assume that I stay at the citizenM Zurich hotel, want to search for a restaurant to have dinner nearby, around 500 meters, with maximum 30 restaurants. Let’s start.
2. Query for a specific venue category
Let’s define some parameters before sending a request
search_query = ‘restaurant’
radius = 500
limit=30
Below codes to get data for a specific venue category:
url = 'https://api.foursquare.com/v2/venues/search?client_id={}&client_secret={}&ll={},{}&v={}&query={}&radius={}&limit={}'.format(CLIENT_ID, CLIENT_SECRET, latitude, longitude, VERSION, search_query, radius, LIMIT)
results = requests.get(url).json()
venues = results['response']['venues']After the data being cleaned, it will be looked like below:
Let’s visualize the 30 location of the results in the map:
3. Explore a Given Venue
3.1 Explore a specific venue
Out of the 30 results, I want to choose a Swiss Restaurant, which has the highest rating to have dinner, now let’s investigate on Swiss Restaurant.
There are 9 Swiss restaurants out of 30 various restaurants according to the category. Now I want to explore the rating of the 9 Swiss restaurants. Remember that the rating is Premium, 50 calls per day, and be careful to making the call.
Below codes to get data for a given venue:
url = 'https://api.foursquare.com/v2/venues/{}?client_id={}&client_secret={}&v={}'.format(venue_id, CLIENT_ID, CLIENT_SECRET, VERSION)
result = requests.get(url).json()3.2 Get the rating of the venue
result[‘response’][‘venue’][‘rating’]After the process of data wrangling, below are the ratings for the nine results:
3.3 Get the number of tips for a specific venue
url = 'https://api.foursquare.com/v2/venues/{}?client_id={}&client_secret={}&v={}'.format(venue_id, CLIENT_ID, CLIENT_SECRET, VERSION)
result = requests.get(url).json()
result['response']['venue']['tips']['count']3.4 Get the venue’s tip
limit = 13 # set limit to be greater than or equal to the total number of tips
url = ‘https://api.foursquare.com/v2/venues/{}/tips?client_id={}&client_secret={}&v={}&limit={}'.format(venue_id, CLIENT_ID, CLIENT_SECRET, VERSION, limit)
results = requests.get(url).json()
tips = results[‘response’][‘tips’][‘items’]As explained at the beginning, there is only one tip per venue for sandbox user, although there is 13 limit for the tips, only one tip will be retrieved as below:
4. Explore a location
Now, I just finished the gourmet dish at restaurant Zum Kropf, and am curious about the popular spots around the restaurant, let’s explore the location, instead of a specific venue.
Using explore function to explore a location:
url = 'https://api.foursquare.com/v2/venues/explore?client_id={}&client_secret={}&ll={},{}&v={}&radius={}&limit={}'.format(CLIENT_ID, CLIENT_SECRET, latitude, longitude, VERSION, radius, LIMIT)
results = requests.get(url).json()The visualization of the results in the map as below:
5. Explore Trending Venues
Now, instead of simply exploring the area around restaurant zum Kropf, I am interested in knowing the venues that are trending at that time, meaning the places with the highest foot traffic. So let’s do that and get the trending venues around it.
Use trending to explore trending venues:
url = 'https://api.foursquare.com/v2/venues/trending?client_id={}&client_secret={}&ll={},{}&v={}'.format(CLIENT_ID, CLIENT_SECRET, latitude, longitude, VERSION)
results = requests.get(url).json()The result is: ‘No trending venues are available at the moment!’. Well, depending on when you run the above code, you might get different venues since the venues with the highest foot traffic are fetched live.
Now, you might be familiar with how to use the Foursquare API.
Have fun.
