Advanced Venue filtering using collections

The goal of this tutorial is to demonstrate advanced venue filtering using the BestTime API. The besttime venues can be filtered using the Venue Filter by default on certain types like BAR, RESTAURANT, CLUB, PARK, etc. However, in some use cases, you may want to create custom filters to, for example, filter venues that meet the filter criteria only on a custom subset of venues, like your favorite venues, venues with regular live music, or any other type. We accomplish this by combining multiple 'collections' and the 'venue filter' API functionality.

Note: Please check the beginners API tutorial if you are new.

Collections

By default, all venues in your account that match the filters will be returned by the Venue Filter API (therefore you first need to add all your desired venues using the Venue Foot Traffic Forecast OR Venue Search API endpoint). Collections can be used to group venues in your account together. After that, one or multiple collection_ids can be passed in the venue filter to further narrow down a search based on your custom collections. Collections can therefore be used to 'tag' venues in a certain group.

Live Music - Karaoke Example

So, let's say you have 100 bars and restaurants in New York City in your account and you want to filter busy bars on Thursday evening that are known to have live music or karaoke. Currently, BestTime does not have enough information on which venues have live music or karaoke. However, you can manually create multiple collections yourself—one for venues that are known as karaoke places and a separate collection for the venues that are known for live music. This way we can use the collections as additional filter to only return karaoke and live music venues in the venue filter API.

Steps:

1. Create a new collection through the API with the name 'live-music' (the name can be anything you like), and save the collection_id.

import requests

url = "https://besttime.app/api/v1/collection"

params = {
    'api_key_private': 'pri_s43661721b084d36b8f469a2c012e754',
    'collection_id': 'col_90387131543761435650505241346a40',
    'name': 'live-music'
}

response = requests.request("POST", url, params=params)
print(response.json())

2.   Add the desired venues that are known for live music to the collection using the API in combination with the venue_id and the collection_id.

import requests

url = "https://besttime.app/api/v1/collection/col_90387131543761435650505241346a40/ven_51387131543761435650505241346a394a6432395362654a496843"

params = {
    'api_key_private': 'pri_s43661721b084d36b8f469a2c012e754',
}

response = requests.request("POST", url, params=params)
print(response.json())

3.   Do the same for venues that are known to have karaoke nights.

Venues can be added to multiple lists. This is useful when a venue is, for example, known for both live music and karaoke nights.

Venue Filter

Now you can filter venues using the Venue Filter parameters that are busy (busy_min 60%) on Thursday (day_int=3) evening (hour_min=18/6PM, hour_max=3/3AM). By adding the IDs of our two newly created collections to collection_ids, the result will contain only venues tagged as (karaoke OR live music) AND are busy on Thursday evening.

Note: The URL parameter collection_id can be used for only a single ID, and collection_ids for multiple collection IDs—as a comma-separated string.

import requests

url = "https://besttime.app/api/v1/venues/filter"

params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
    'day_int': 3,    # Thursday
    'busy_min': 60,  # 60%
    'busy_max': 100, # 100%
    'hour_min': 18,  # 6PM
    'hour_max': 03,  # 3AM
    'order_by': 'reviews', 
    'order': 'desc',
    'limit': 20,
    'page': 0,
    'collection_ids': 'col_90387131543761435650505241346a40,col_303871315437614356505052413105b2
}

response = requests.request("GET", url, params=params)
print(response.json())

Alternative Methods to Add Venues to a Collection

Besides adding venues one by one to a collection, you can also:

• Pass in a single existing collection_id to a New Foot Traffic Forecast API call.
• Add an existing collection_id to a Venue Search request to add the matching venues to the given collection_id.

Click here for more BestTime tutorials