NAV Navbar
python javascript shell

Introduction

Welcome to the BestTime.app documentation! The documentation includes different sections.

What is BestTime.app?

BestTime.app is a foot traffic data (API) service that forecasts how busy a public business (venues) will be at any given hour of the week. The data is provided for 150+ countries using anonymous phone signals, and is available for retail, restaurants, bars, gyms, museums, and more. Foot traffic forecasts are based on average visits over the past weeks. Busyness for any given hour is predicted relative to the biggest peak of the week for this business. The foot traffic data is presented as percentages for each hour of the week from 0% (empty/ closed) to 100% (visitor peak of the week).

Highly recommended to read: - BestTime tools beginners tutorial - BestTime Software API beginners tutorial

Additional BestTime functionality:

You could compare it with a supercharged FourSquare foot traffic data/ Google Popular Times API with more footfall data analytic functionality.

Use cases

Below are a few example use-cases how the analyzed data can be used in real-world:

Forecasts

A forecast can be made by giving the name and the approximate address of the public business. BestTime.app will try to find the correct business. If there is enough data available it will analyse the data and create a forecast.

Public businesses

BestTime.app works in general only for public businesses. For example:

Results

A forecast is usually created within a few seconds and responds with all primary analyses. Additionally, a forecast is stored on the server so it can be queried later again without the need to forecast the business again.

The forecast results include:

Relative numbers

BestTime.app does not provide absolute business visitor numbers. Data in the forecasts represent an approximate how busy a business will be in a relative number. Each hour of the week is rated on a five-point scale from -2 to +2 (Low, below average, average, above average, high). The rating is also depending on the mean busyness of the week.

Coverage

BestTime.app has coverage in 150+ countries. It depends on multiple factors if a business can be forecasted. A rough guideline is that the business needs to be a public business and has at least 100 visitors per day.

Data retention

Forecast will only be stored on the server for a specific number of days. This depends on your subscription plan. Expired forecasts will be automatically deleted. Store a forecast response locally or upgrade your plan to keep using a forecast.

Updating a forecast

To update an existing business forecast you need to create a new forecast. Currently, only the latest forecast for each business is accessible through the API. It is up to the user to decide how often a forecast needs to be updated, but in general, we recommend to update a forecast every two to four weeks. Live data is the current relative activity for the current hour. It is therefore suggested to update the live data every hour.

Queries

Forecasting a (new) business takes a few seconds. Normally a forecast is accurate for at least several weeks (depending on the business), therefore the data from existing forecasts can still be used for a longer period. Queries are used to get data from an existing forecasted business. For example the whole forecast, or a specific analysis on a specific day.

A query response is almost instant, includes sometimes additional data, and makes it easier to answer specific questions.

Forecasts are based on visits to the business from the past few weeks. We recommend therefore to only forecast (update) a business once every few weeks. Queries should be used in between the forecasts. This reduces API forecast credits and improves the API performance.

Additional dynamic data

Some query responses include additional dynamic data on top of the stored forecast. The peak-, surge-, busy-, quiet analysis query responses include the time remaining until the next event (e.g. 2,5 hours until the first busy hour).

Query analysis

BestTime.app has several query endpoints:

Venue queries: - Query the details of a specific venue - Query all forecasted venues - Query all venues matching the busyness, location, time & day, and/or type filter

Forecast of a single venue queries: - Query the whole original forecast (includes all analysis) of a venue - Query a specific day of the week (includes all analysis) - Query a specific hour of the day - Query the current hour of the business with the local business timezone taken into account (or X hours ahead from the current hour) - Query the busy hours of today (or X days ahead from today) - Query the quiet hours of today (or X days ahead from today) - Query the peak hours of today (or X days ahead from today) - Query the surge hours of today (or X days ahead from today)

Forecast day window and weekdays

BestTime.app uses a 24-hour notation, displayed from 0 to 23. Where 0 indicates midnight and 23 indicates 11 PM. Important to know is that the foot traffic data time window ranges from 6 AM until 5 AM next day. Not from midnight to midnight. This is for example useful for public venues with late opening times like bars and nightclubs.

Below is an example how an array of 24 foot traffic percentages relate to the hour of the day , and the index of the array (from 0 - 23). The foot traffic data is just an example for a restaurant that opens at 9PM (array index 3) has a lunch peak 1 PM (array index 7), a dinner peak at 9 PM (array index 15) and closes at 3 AM (array index 21).

Hour Index Foot Traffic (Example)
6 AM 0 0
7 AM 1 0
8 AM 2 0
9 AM 3 10
10 AM 4 15
11 AM 5 35
12 PM 6 50
1 PM 7 65
2 PM 8 45
3 PM 9 35
4 PM 10 30
5 PM 11 35
6 PM 12 45
7 PM 13 60
8 PM 14 85
9 PM 15 90
10 PM 16 80
11 PM 17 55
12 AM 18 40
1 AM 19 30
2 AM 20 20
3 AM 21 0
4 AM 22 0
5 AM 23 0

API Reference

The API Reference explains how:

API Key

BestTime.app uses API keys to allow access to the API. You can find or generate API keys at the API keys Management page.

BestTime.app expects for the API key to be included in all API requests to the server.

Authentication for the API is done using API keys. There are two types of API keys; Private keys are used to create a new forecast, and public keys to query data from existing forecasted venues. The private key can be used to create, delete and list forecasts. As the name suggests, the private key should be kept secret, to avoid other people from forecasting new venues and abusing your limited forecast credits. The public key can be used to query existing venue forecasts. However, it can only be used to get existing forecast data (read-only).

API keys are generated in pairs, and you can generate multiple API key sets (pairs) in the API key management page. When using multiple API keys, you should remember that you can only query forecasts from the same key set.

All key set use credits from the same account. When an API key is compromised, you can delete the API key set through the API Key management page.

Highly recommended to read first: - BestTime tools beginners tutorial - BestTime Software API beginners tutorial

Authentication

To authorize, use this code:

import requests

url = "https://besttime.app/api/v1/keys/pri_a00de9e302662c0217a9cf08ab304122"

response = requests.request("GET", url)

print(response.json())

# cURL
curl --location --request GET 'https://besttime.app/api/v1/keys/pri_a00de9e302662c0217a9cf08ab304122'


fetch(`https://besttime.app/api/v1/keys/pri_a00de9e302662c0217a9cf08ab304122`, {
  method: 'GET'
}).then(function(data) { console.log(data); });

You can find or generate API keys at the API keys Management page.

The above command returns JSON structured like this:

  {
    "active": true,
    "api_key_private": "pri_a00de9e302662c0217a9cf08ab304122",
    "api_key_public": "pub_e11661721b084d36b8f469a2c012e754",
    "status": "OK",
    "valid": true
  }

Private and public API keys

Credits

For metered API subscription API credits are used to calculate your total monthly bill. See the pricing page for the price per API credit.

The number of credits per API call depends on the used API endpoint. The tools on the website also use the API internally and will therefore also count towards your total API usage.

Alternatively, you can buy a Package subscription. Then you always pay a fixed fee per month and can call the API as many times as you want (see the BestTime pricing page for more details on the packages).

 

API Endpoint Credits API Key required
New foot traffic forecasts (success) 2 Private
New foot traffic forecasts (unsuccessful) 1 Private
Live foot traffic data 1 Private
Venue (all/ filter/ update) 1 / 10 venues Private
Venue Search (Normal) 1 / 20 venues Private
Venue Search (Fast) 5 / 20 venues Private
Query (existing forecast) 1 Public

 

Unsuccessful forecasts are also counted as credits, with the exception of server errors. This is to prevent overloading the API servers with low quality address inputs.

It is the users responsibility to prevent api key abuse. Hide your API keys secure to prevent other people from using API credits resulting in higher monthly subscription fees.

The Venue Search functionality counts credits for finding matching venues, but this result does not include foot-traffic data. Therefore, the Venue Search function will automatically pushes the found venues to the 'New foot-traffic forecast' API endpoint. A 'normal' speed Venue search for max 20 venues will therefore cost: 1 Venue search normal credit + 20 * 2 New Forecast (successful) credit = 41 credits (equals to approximately $0.32 with the Premium plan). This is the maximum number of credits used. If the search result includes less venues, or if a venue does not have foot-traffic data the number will be lower. In a future version we will give the user the possibility to decide to not automatically forecast all found venues through the Venue Search tool.

Subscription plans

BestTime has two types of plans. Metered and packaged plans. The metered plans will automatically charge you depending on the credit usage at the end of a (monthly) billing cycle. The basic plan is the lowest-priced plan. All functionality is available in the basic plan,

BestTime also offers multiple 'packaged' plans if you don't like the uncertainty of a metered plan. The packaged plans have a fixed price per month and unlimited forecast, live, query and venue API calls. However, each package plan is limited to a certain number of new venues-, and venue search calls per calender month.

Old plans:  
Credits will be added at the start of every monthly invoice cycle, when you upgrade, or when you buy extra credit bundles (only for selected subscription plans). Credits don't expire and automatically roll over to the next month. If you cancel your subscription coins will stay in your account. However, all your API keys will be deactivated. This means you cannot create new forecasts and query existing forecasts. If you decide to re-subscribe on the same account you can use your old coins, but you cannot access the previous forecasts anymore.

HTTP (Error) API codes

BestTime uses the following HTTP codes

Code Meaning
200 OK
400 Bad Request - check your API parameters
401 Unauthorized
404 Not found - API resource not found
405 Method Not Allowed - You tried to access the API with an invalid route
429 Too Many Requests - You have been rate-limited
500 Internal Server Error - We have a problem with the server and the team has been automatically notified
503 Service Unavailable

 

By default the API is limited to 300 API requests per minute. The Venue Search API endpoint is limited to 30 request per minute and 300 requests per hour. The Venue Filter is limited to 30 request per minute. You will receive a HTTP 429 'too many requests' above this threshold. Contact us for if you need higher limits.

New foot-traffic forecast

Returns foot-traffic forecast for a venue based on a name and address

import requests

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

params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
    'venue_name': 'McDonalds',
    'venue_address': 'Ocean Ave, San Fransisco'
}

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

# cURL
curl --location --request POST 'https://besttime.app/api/v1/forecasts?
api_key_private=pri_50990bf1f8828f6abbf6152013113c6b&
venue_name=McDonalds&
venue_address=Ocean%20Ave%2C%20San%20Fransisco'

const params = new URLSearchParams({ 
 'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
  'venue_name': 'McDonalds',
  'venue_address': 'Ocean Ave, San Fransisco'
});

fetch(`https://besttime.app/api/v1/forecasts?${params}`, {
  method: 'POST'
}).then(function(data) { 
  console.log(data); 
});

The above request returns JSON structured like this:

  {
    "analysis": [
        {
            "day_info": {
                "day_int": 0,
                "day_rank_max": 6,
                "day_rank_mean": 4,
                "day_text": "Monday",
                "venue_closed": 6,
                "venue_open": 23
            },
            "day_raw": [
                10,
                25,
                40,
                55,
                65,
                75,
                75,
                75,
                75,
                75,
                70,
                65,
                50,
                40,
                30,
                25,
                25,
                25,
                20,
                15,
                10,
                0,
                5,
                5
            ],
            "hour_analysis": [
                {
                    "hour": 6,
                    "intensity_nr": -1,
                    "intensity_txt": "Below average"
                },
                ... Other hours hidden. See full JSON example link below
            ],
            "peak_hours": [
                {
                    "peak_start": 8,
                    "peak_max": 11,
                    "peak_end": 23,
                    "peak_intensity": 4
                }
            ],
            "quiet_hours": [
                6,
                1,
                2,
                3
            ],
            "busy_hours": [
                9,
                10,
                11,
                12
            ],
            "surge_hours": {
                "most_people_come": 8,
                "most_people_leave": 22
            },
        },
        ... Other days hidden. See full JSON example link below
    ],
    "epoch_analysis": "1583314752",
    "status": "OK",
    "venue_info": {
        "venue_address": "1201 Ocean Ave San Francisco, CA 94112 United States",
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_name": "McDonald's",
        "venue_timezone": "America/Los_Angeles",
        "venue_dwell_time_min": 20,
        "venue_dwell_time_max": 60,
        "venue_dwell_time_avg": 40,
        "venue_type": "FAST_FOOD",
        "venue_types": [
            "fast_food_restaurant",
            "breakfast_restaurant",
            "coffee_shop",
            "hamburger_restaurant",
            "restaurant",
            "sandwich_shop"
        ],
        "venue_lat": -8.6487349,
        "venue_lon": 115.13728069999999
    }
}}

Click here for the full JSON response

The 'new foot traffic forecast' endpoint is used to create a forecast of a venue based on the most recent available data. Forecasts are created using the venue name and address as input. The response includes the forecast (including different analysis), and venue information. The venue information includes the venue_id. This ID is the primary parameter to lookup previously forecasted venues, using the query endpoints. Forecasts are stored on the server for a certain number of days (see data retention)

Highly recommended to read first: - BestTime tools beginners tutorial - BestTime Software API beginners tutorial - HTML/ Javascript examples

Input attributes New Forecast

Response attributes New Forecast

Live foot-traffic data

Returns Live foot-traffic data for a venue based on the venue name and address:

import requests

url = "https://besttime.app/api/v1/forecasts/live"

params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
    'venue_name': 'McDonalds',
    'venue_address': 'Ocean Ave, San Fransisco'
}

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

# cURL
curl --location --request POST 'https://besttime.app/api/v1/forecasts/live?
api_key_private=pri_50990bf1f8828f6abbf6152013113c6b&
venue_name=McDonalds&
venue_address=Ocean%20Ave%2C%20San%20Fransisco'

const params = new URLSearchParams({ 
  'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
  'venue_name': 'McDonalds',
  'venue_address': 'Ocean Ave, San Fransisco'
});

fetch(`https://besttime.app/api/v1/forecasts/live?${params}`, {
  method: 'POST'
}).then(function(data) { 
  console.log(data); 
});

The 'live forecast' endpoint is used to get live information of the venue. Life forecasts are either created using the venue name and address, or the venue_id as input in the request. The response includes information regarding the live busyness at this moment compared to the forecasted busyness of the corresponding hour.

When creating a live forecast the normal forecast for the venue will NOT be updated. Use one of the other New Forecast endpoints

Highly recommended to read first: - BestTime tools beginners tutorial - BestTime Software API beginners tutorial

Input attributes Live foot traffic data

The above request returns JSON structured like this:

{
    "analysis": {
        "venue_forecasted_busyness": 60,
        "venue_live_busyness": 20,
        "venue_live_busyness_available": true,
        "venue_forecast_busyness_available": true,   
        "venue_live_forecasted_delta": -40
    },
    "status": "OK",
    "venue_info": {
        "venue_current_gmttime": "Friday 2021-04-23 07:19AM",
        "venue_current_localtime": "Friday 2021-04-23 03:19PM",
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_name": "McDonald's",
        "venue_timezone": "America/Los_Angeles",
        "venue_dwell_time_min": 20,
        "venue_dwell_time_max": 60,
        "venue_dwell_time_avg": 40
    }
}

Response attributes Live Forecast

Venue Search

Find and add new venues based on a search query.

import requests

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

params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
    'q': 'quiet supermarkets in sydney australia sunday morning',
    'num': 200,
    'fast': False,
    'format': 'raw'
}

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

# cURL
curl --location --request POST 'https://besttime.app/api/v1/venues/search?api_key_private=pri_50990bf1f8828f6abbf6152013113c6b&q=quiet%20supermarkets%20in%20sydney%20australia%20sunday%20morning&num=200&fast=false&format=raw'

const params = new URLSearchParams({ 
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
    'q': 'quiet supermarkets in sydney australia sunday morning',
    'num': 200,
    'fast': false,
    'format': 'raw'
});

fetch(`https://besttime.app/api/v1/venues/search?${params}`, {
  method: 'POST'
}).then(function(data) { 
  console.log(data); 
});

Find and add multiple new venues based on a search query. The search query can e.g. contain the name of a venue (e.g. McDonald's, Walmart,etc), or a type of venue (e.g. supermarkets, pizza, beach, things to do, etc).

The search query can be narrowed down with additional filters like the location (e.g. a neighborhood, city, or country), or add geographical data (lat, lng, radius) to find venues related to the search query in a geographic location.

Note: Use the 'New foot traffic forecast' API endpoint when searching for a single venue (this is much faster).

Multiple API endpoints are involved from entering a search input until returning foot-traffic data for the found venues. The Venue Search model will lookup venues in the background and will forecast them subsequently. Remember that this will therefore also result in forecast API credit usage. The endpoint will reply with a background task URL, job_id, and a collection_id (see Collections). You can poll the Venue Search Progress endpoint to poll to progress. The venue search functionality can also be used without API using the website Venue Search Tool or on the Radar tool.

Once finished and if available for the venue, the Venue Search Progress endpoint will return the foot traffic data for the found venues. This data is similar to the day_info and day_raw response values of the New Foot Traffic Forecast endpoint. However, it does not include all additional analyses. Use the Query Week endpoint to get the whole forecast analysis using the venue_id. Normally API credits are charged for this endpoint, but is free within one day after created a new forecast (through the Venue Search- or directly through the New Foot Traffic Forecast endpoint).

Highly recommended to read first: - BestTime tools beginners tutorial - BestTime Software API beginners tutorial

Venue filters

The Venue Search Progress endpoint will return a link to view the results in the 'Radar tool' and the 'venue filter' API endpoint once the background job has been completed (job_finished: true). The venue search endpoint accepts filters similar to the 'venue filter' endpoint and Radar tool. By providing these parameters the links to the Radar tool and Venue Filter endpoint will automatically include the filter parameters. Only after analyzing each venue (foot-traffic forecast) most filters will be applied in the Radar tool/ Venue Filter endpoint. The venue search result therefore also includes venues that do not meet the filter criteria, but match the other search query text. The filters that are directly applied in the search are: opened, lat, lng, and radius for both search methods ('normal' and 'fast' method). The 'fast' method filters directly as well on price_min and price_max. The 'normal' search method will filter directly on rating_min.

Natural language in the search query as filters

Besides separate parameters as filter inputs, the q search query understands also a variety of natural language that will be translated into the related filter parameters. You can use it to filter on busyness, day of week, day part, or time range. For example:

Busyness natural language examples:

Strings that will trigger the busyness filters are:

busy -> busy_min=50,

quiet-> busy_max=50,

Define a range with multiple percentages including the word busy:

E.g. 40% to 90% busy bars in New York City. Define a custom minimum or maximum using the strings:

E.g. at least 60% busy bars in Melbourne Australia will set the filter to busy_min=60

Day of week natural language examples:

Strings (case insensitive) that will trigger the day of week are : - Monday -> day_int=0,
- Tuesday -> day_int=1,
- Wednesday -> day_int=2,
- Thursday -> day_int=3,
- Friday -> day_int=4,
- Saturday -> day_int=5,
- Sunday -> day_int=6

Time of day natural language examples:

Strings (case insensitive) that will trigger the time of day filters:

morning -> hour_min=6, hour_max=11,
afternoon -> hour_min=12, hour_max=17,
evening -> hour_min=18, hour_max=0,
night -> hour_min=21, hour_max=5,

This query endpoint requires the private API key.

 

The above request returns a JSON response with links to the background job:

{
    "_links": {
        "venue_search_progress": "https://besttime.app/api/v1/venues/progress?job_id=e0880f28-3a19-4871-a355-4ca21f10c2c8&collection_id=col_ac734e76ad2d4696a5a66541c67587e8&format=raw"
    },
    "collection_id": "col_ac734e76ad2d4696a5a66541c67587e8",
    "job_id": "e0880f28-3a19-4871-a355-4ca21f10c2c8",
    "status": "OK"
}

The JSON response will contain a URL to the Venue Search Progress endpoint to track the progress of the current venue search that runs in the background. This URL is the same as the Venue Search Progress API endpoint.

Venue Search Progress

Venue Search Progress endpoint

import requests

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

params = {
    'job_id': '0a693bb3-7bd6-4d43-9495-a2773f1c9e29',
    'collection_id': 'col_ffbebb4003974979b75a14844d60e9c5',
    'format': 'raw'
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/venues/progress?
job_id=0a693bb3-7bd6-4d43-9495-a2773f1c9e29&collection_id=col_ffbebb4003974979b75a14844d60e9c5&
format=raw'

const params = new URLSearchParams({ 
    'job_id': '0a693bb3-7bd6-4d43-9495-a2773f1c9e29',
    'collection_id': 'col_ffbebb4003974979b75a14844d60e9c5',
    'format': 'raw'
});

fetch(`https://besttime.app/api/v1/venues/progress?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Venue Search Progress

The above request returns a JSON response with the progress of the venue search. Once it is complete it will show the second displayed JSON response.

{
    "collection_id": "col_5c546908473645c1b9bad36b7fef7765",
    "count_completed": 140,
    "count_failure": 0,
    "count_forecast": 129,
    "count_live": 74,
    "count_total": 200,
    "job_finished": false,
    "job_id": "eb6aa504-e147-4b2d-a191-03d721764279",
    "status": "OK"
}

When the venue search is complete it will return a JSON response with the following structure :

{
    "_links": {
        "background_progress_api": "http://besttime.app/api/v1/venues/progress?job_id=eb6aa504-e147-4b2d-a191-03d721764279&ven=False",
        "background_progress_tool": "http://besttime.app/api/v1/misc/addarea_progress?q=quiet+supermarkets+in+sydney+australia+sunday+morning&job_id=eb6aa504-e147-4b2d-a191-03d721764279&map_lat=-33.8627418&map_lng=151.2165809&lat_min=-33.8877752&lat_max=-33.8377084&lng_min=151.1962989&lng_max=151.2368629&map_zoom=14&radius=6712&collection_id=col_5c546908473645c1b9bad36b7fef7765&api_key_private=pri_50990bf1f8828f6abbf6152013113c6b&busy_min=0&busy_max=50&day_int=6&hour_min=6&hour_max=11&now=True&live_refresh=False&auto_continue=1",
        "radar_tool": "http://besttime.app/api/v1/radar/filter?q=quiet+supermarkets+in+sydney+australia+sunday+morning&map_lat=-33.8627418&map_lng=151.2165809&lat_min=-33.8877752&lat_max=-33.8377084&lng_min=151.1962989&lng_max=151.2368629&map_z=14&collection_id=col_5c546908473645c1b9bad36b7fef7765&api_key_private=pri_50990bf1f8828f6abbf6152013113c6b&busy_min=0&busy_max=50&day_int=6&hour_min=6&hour_max=11&now=True&live_refresh=False",
        "venue_filter_api": "http://besttime.app/api/v1/venues/filter?lat_min=-33.8877752&lat_max=-33.8377084&lng_min=151.1962989&lng_max=151.2368629&collection_id=col_5c546908473645c1b9bad36b7fef7765&api_key_private=pri_50990bf1f8828f6abbf6152013113c6b&busy_min=0&busy_max=50&day_int=6&hour_min=6&hour_max=11&now=True&live_refresh=False"
    },
    "bounding_box": {
        "lat": -33.8627418,
        "lat_max": -33.8377084,
        "lat_min": -33.8877752,
        "lng": 151.2165809,
        "lng_max": 151.2368629,
        "lng_min": 151.1962989,
        "map_zoom": 14,
        "radius": 6712
    },
    "collection_id": "col_5c546908473645c1b9bad36b7fef7765",
    "count_completed": 200,
    "count_failure": 0,
    "count_forecast": 181,
    "count_live": 90,
    "count_total": 200,
    "job_finished": true,
    "job_id": "eb6aa504-e147-4b2d-a191-03d721764279",
    "status": "OK",
    "venues": [
        {
            "forecast": false,
            "processed": true,
            "venue_address": "21 Shelley St, Sydney NSW 2000, Australia",
            "venue_lat": -33.8670477,
            "venue_lon": 151.2023238,
            "venue_name": "Kings Wharf Supermarket",
            "venue_id": "ven_6372542d36476a8759686d52676b646155646e713661514a496843"
        },
        {
            "forecast": true,
            "processed": true,
            "venue_address": "4/490 Crown St, Surry Hills NSW 2010, Australia",
            "venue_lat": -33.8866095,
            "venue_lon": 151.2138922,
            "venue_name": "Maloneys Grocer",
            "venue_id": "ven_9372542d36476a8759686d52676b646155646e713661514a496847",
            "venue_foot_traffic_forecast": [
                {
                    "day_info": {
                        "day_int": 0,
                        "day_max": 25,
                        "day_mean": 12,
                        "day_rank_max": 6,
                        "day_rank_mean": 7,
                        "day_text": "Monday",
                        "venue_closed": 21,
                        "venue_open": 6
                    },
                    "day_int": 0,
                    "day_raw": [
                        5,
                        5,
                        5,
                        10,
                        15,
                        20,
                        20,
                        25,
                        25,
                        20,
                        15,
                        10,
                        5,
                        5,
                        0,
                        0,
                        0,
                        0,
                        0,
                        0,
                        0,
                        0,
                        0,
                        0
                    ]
                },
                {
                    "day_info": {
                        "day_int": 1,
                        "day_max": 24,
                        "day_mean": 12,
                        "day_rank_max": 7,
                        "day_rank_mean": 7,
                        "day_text": "Tuesday",
                        "venue_closed": 21,
                        "venue_open": 6
                    },
                    "day_int": 1,
                    "day_raw": [
                        0,
                        5,
                        5,
                        10,
                        15,
                        ...
        },
        ... Only the first two results are displayed here
    ],
    "venues_n": 200
}

Response attributes Venue Search Progress

The JSON response will contain the progress of the Venue Search query and once completed it will return the remaining attributes as shown in the second part of the attributes below.

The attributes below will be displayed when the Venue Search job is finished (job_finished: true).

Venue collections

Collections can be used to group venues together. Each collection has an unique 36 collection_id and an optional name. Venues inside a collection are managed using the venue_id of each venue. Your existing collections can be also viewed on the Collection page. On the page, click on a collection_id to see which venues are inside or to open the collection in the Radar tool.

Through the collections API endpoints, you can create or delete collections, and add or remove venues to/from an existing collection.

There are multiple ways to use a collection in combination with the other BestTime tools/ API endpoints - Manually add venues to a collection to group them and later call the collection to simply know which venue_id’s belong together. - Pass a collection_id to a New forecast to automatically add one or multiple successful venues to an existing collection. - The Radar tool and Venue Filter accepts a collection_id as input show and filter only on the venues inside that collection - The Venue Search tool and API endpoint automatically creates a new collection with a new search query, with the search query as collection name. The Venue Search API endpoint also accepts an existing collection id. This will merge the new search results with the given collection.

Create a collection

import requests

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

params = {
    'api_key_private': 'pri_s43661721b084d36b8f469a2c012e754',
    'collection_id': 'col_51387131543761435650505241346a39',
    'name': 'Supermarkets in Los Angeles, CA'
}

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

# cURL
curl --location --request POST 'https://besttime.app/api/v1/collection?api_key_private=pri_s43661721b084d36b8f469a2c012e754&
collection_id=col_51387131543761435650505241346a39&
name=Supermarkets%20in%20Los%20Angeles%20CA'

const params = new URLSearchParams({ 
    'api_key_private': 'pri_s43661721b084d36b8f469a2c012e754',
    'collection_id': 'col_51387131543761435650505241346a39',
    'name': 'Supermarkets in Los Angeles, CA'
});

fetch(`https://besttime.app/api/v1/collection?${params}`, {
  method: 'POST'
}).then(function(data) { 
  console.log(data); 
});

Input attributes

The above request returns JSON structured like this:

{
    "collection": {
        "api_key_private": "pri_s43661721b084d36b8f469a2c012e754",
        "collection_id": "col_51387131543761435650505241346a39",
        "name": "Supermarkets in Los Angeles, CA"
    },
    "status": "OK"
}

Add venues to a collection

import requests

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

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

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

# cURL
curl --location --request POST 'https://besttime.app/api/v1/collection/col_51387131543761435650505241346a39/ven_51387131543761435650505241346a394a6432395362654a496843?api_key_private=pri_s43661721b084d36b8f469a2c012e754

const params = new URLSearchParams({ 
    'api_key_private': 'pri_s43661721b084d36b8f469a2c012e754',
});

fetch(`https://besttime.app/api/v1/collection/col_51387131543761435650505241346a39/ven_51387131543761435650505241346a394a6432395362654a496843?${params}`, {
  method: 'POST'
}).then(function(data) { 
  console.log(data); 
});

Input attributes

The above request returns JSON structured like this:

{
    "collection_id": "col_51387131543761435650505241346a39",
    "message": "Venue added to collection",
    "status": "OK",
    "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843"
}

Collection Venues

Returns a list with all venue_id's of venues in the collection

import requests

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

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

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/collection/col_51387131543761435650505241346a39?api_key_private=pri_s43661721b084d36b8f469a2c012e754

const params = new URLSearchParams({ 
    'api_key_private': 'pri_s43661721b084d36b8f469a2c012e754',
});

fetch(`https://besttime.app/api/v1/collection/col_51387131543761435650505241346a39?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes

The above request returns JSON structured like this:

{
    "collection_id": "col_51387131543761435650505241346a39",
    "status": "OK",
    "venue_ids": [
        "ven_51387131543761435650505241346a394a6432395362654a496843"
    ]
}

Collection Remove venue

Removes a venue from the collection using the venue_id.

import requests

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

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

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

# cURL
curl --location --request DELETE 'https://besttime.app/api/v1/collection/col_51387131543761435650505241346a39/ven_51387131543761435650505241346a394a6432395362654a496843?api_key_private=pri_s43661721b084d36b8f469a2c012e754

const params = new URLSearchParams({ 
    'api_key_private': 'pri_s43661721b084d36b8f469a2c012e754',
});

fetch(`https://besttime.app/api/v1/collection/col_51387131543761435650505241346a39/ven_51387131543761435650505241346a394a6432395362654a496843?${params}`, {
  method: 'DELETE'
}).then(function(data) { 
  console.log(data); 
});

Input attributes

The above request returns JSON structured like this:

{
    "collection_id": "col_51387131543761435650505241346a39",
    "message": "Venue deleted from collection",
    "status": "OK",
    "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843"
}

Collection delete

Delete a collection using the collection_id. Deleting a collection does not affect the venues listed in the collection itself.

import requests

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

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

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

# cURL
curl --location --request DELETE 'https://besttime.app/api/v1/collection?api_key_private=pri_s43661721b084d36b8f469a2c012e754&
collection_id=col_51387131543761435650505241346a39'

const params = new URLSearchParams({ 
    'api_key_private': 'pri_s43661721b084d36b8f469a2c012e754',
    'collection_id': 'col_51387131543761435650505241346a39'
});

fetch(`https://besttime.app/api/v1/collection?${params}`, {
  method: 'DELETE'
}).then(function(data) { 
  console.log(data); 
});

Input attributes

The above request returns JSON structured like this:

{
    "message": "collection_id col_51387131543761435650505241346a39 deleted",
    "status": "OK"
}

Query endpoints

All query endpoints are used to retrieve all data or specific analysis from an existing forecast. Query endpoints often also include dynamic information (e.g. remaining time until it will be busy according to the forecast). The venue_id is the primary parameter to query an existing forecast.

It is also possible to update a venue forecast in combination with the query in one API call. This way you can retrieve query-specific data: - with a fresh forecast - don't having to worry about the retention days (maximum days a forecast is stored on the server) - use the venue name and address as API input instead of the venue_id

Check the query endpoint itself for more information. This will be counted as new forecast credit.

Query endpoints:

Venues Lists all previously forecasted venues, and venue_id's.

Venues filtered (Radar tool) Query earlier forecasted venues that match the filter on busyness, location, time, day and venue type.

Venue Query a forecasted venue, with detailed venue information.

Week Query the forecast for the whole week, including all analysis. This gives the same response as the original 'new forecast' endpoint.

Week raw Query the forecast for the whole week, in raw percentages.

Week overview Qeury a week overview for the venue. Including day maximum, day mean, day maximum ranking, day mean ranking, and open/closing times.

Day Query a specific day of the week including all analysis.

Day raw Query the forecast for a specific day of the week, in raw percentages.

Hour Query a specific hour of the day.

Hour raw Query the forecast for a specific day and hour of the week, in raw percentages.

Now Query the current hour of the business with the local business timezone taken into account.

Now raw Query the current hour of the business with the local business timezone taken into account, in raw percentages.

Peak Hours Query the peak hours of today. Peaks will also include peak start, end times, and how intense the peak will be.

Busy Hours Query the busy hours of today.

Quiet Hours Query the quiet hours of today.

Surge Hours Query the surge hours of today. Surge analysis shows when most people come to a venue, or leave the venue.

Highly recommended to read first: - BestTime tools beginners tutorial - BestTime Software API beginners tutorial

Query filtered venues (Radar)

Filter forecasted venues on busyness, location, type, day, and time. 

import requests

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

params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
    'busy_min': 50,
    'busy_max': 100,
    'hour_min': 18,
    'hour_max': 23,
    'busy_conf':'any',
    'types': ['BAR','CAFE','RESTAURANT'],
    'lat': 51.5121172,
    'lng': -0.126173,
    'radius': 2000,
    'order_by': ['day_rank_max','reviews'],
    'order': ['desc','desc'],
    'foot_traffic': 'both',
    'limit': 20,
    'page': 0
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/venues/filter?api_key_private=pri_50990bf1f8828f6abbf6152013113c6b&busy_min=50&busy_max=100&hour_min=18&hour_max=23&hour_conf=any&types=BAR,CAFE,RESTAURANT&lat=51.5121172&lng=-0.126173&radius=2000&order_by=day_rank_max%2Creviews&order=asc%2Cdesc&foot_traffic=both&limit=20&page=0'

const params = new URLSearchParams({ 
 'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
    'busy_min': 50,
    'busy_max': 100,
    'busy_conf':'any',
    'hour_min': 18,
    'hour_max': 23,
    'types': ['BAR','CAFE','RESTAURANT'],
    'lat': 51.5121172,
    'lng': -0.126173,
    'radius': 2000,
    'order_by': ['day_rank_max','reviews'],
    'order': ['desc','desc'],
    'foot_traffic': 'both',
    'limit': 20,
    'page': 0
});

fetch(`https://besttime.app/api/v1/venues/filter?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Venue Filter

The 'venue filter' endpoint will return all venues and foot traffic data that meet the filter requirements. Venues can be filtered on how busy they are, on location, type of venue, day & time range, etc, or a combination. This could be useful to for e.g. find all busy bars, cafes and nightclubs, between 6pm and 11pm in a specific neighborhood. The filter will only return venues that are forecasted before with the given private API key.

The BestTime Radar tool is using the same API endpoint to show all venues that meet the filter criteria on a (heat)map.

The endpoint will only return venues that have been forecasted before with the provided api_key_private. The user can manually add each desired venue individually through the BestTime API, or can use an external API service with public business (like Google Maps Places Nearby search, Here.com, Fouresquare Venues, or Factual Places). Using the external service places in a certain area can be discovered and the results (venue name and address) can be fed into the BestTime API.

The 'Venue Search' tool can be used to add multiple venues to your account with one API call. See more info on Venue Search.

Highly recommended to read first: - BestTime tools beginners tutorial - BestTime Software API beginners tutorial

Radar tool (which is using this 'venue filter' endpoint) Radar tool (Venue filter)

The above request returns a JSON response like this (this example only contains a list with one venue):

{
  "status": "OK",
  "venues": [
    {
      "day_info": {
          "day_int": 4,
          "day_max": 74,
          "day_mean": 55,
          "day_rank_max": 7,
          "day_rank_mean": 4,
          "day_text": "Friday",
          "venue_closed": 22,
          "venue_open": 7
      },
      "day_int": 4,
      "day_raw": [
          65,
          65,
          60,
          50,
          0,
          0
      ],
      "day_raw_whole": [
          0,
          10,
          35,
          50,
          45,
          55,
          70,
          75,
          70,
          60,
          60,
          60,
          65,
          65,
          60,
          50,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
      ],
      "price_level": 0,
      "rating": 4.6,
      "reviews": 496,
      "venue_address": "45 Jermyn St St. James's, London SW1Y 6DN United Kingdom",
      "venue_dwell_time_max": 120,
      "venue_dwell_time_min": 60,
      "venue_id": "ven_6f39545031476b54345f5852676b6445596457484a79674a496843",
      "venue_lat": 51.5080107,
      "venue_lng": -0.1382948,
      "venue_name": "45 Jermyn St.",
      "venue_type": "RESTAURANT"
    },
    {
      "day_info": {
          "day_int": 4,
          "day_max": 87,
          "day_mean": 41,
          "day_rank_max": 2,
          "day_rank_mean": 3,
          "day_text": "Friday",
          "venue_closed": 0,
          "venue_open": 12
      },
      "day_int": 4,
      "day_raw": [
          55,
          80,
          85,
          80,
          55,
          30
      ],
      "day_raw_whole": [
          0,
          0,
          0,
          0,
          0,
          0,
          15,
          20,
          15,
          10,
          15,
          30,
          55,
          80,
          85,
          80,
          55,
          30,
          15,
          0,
          0,
          0,
          0,
          0
      ],
      "price_level": 2,
      "rating": 4.5,
      "reviews": 1782,
      "venue_address": "7 Northumberland Ave London WC2N 5BY United Kingdom",
      "venue_dwell_time_max": 120,
      "venue_dwell_time_min": 60,
      "venue_id": "ven_6f5a30484241302d48623552676b6446556e49492d36374a496843",
      "venue_lat": 51.5071129,
      "venue_lng": -0.1265196,
      "venue_name": "50 Kalò di Ciro Salvo Pizzeria London",
      "venue_type": "RESTAURANT"
    }
  ],
  "venues_n": 2,
  "window": {
      "day_window": "Friday 6PM until Friday 11PM",
      "day_window_end_int": 4,
      "day_window_end_txt": "Friday",
      "day_window_start_int": 4,
      "day_window_start_txt": "Friday",
      "time_local": 8,
      "time_local_12": "8AM",
      "time_local_index": 2,
      "time_window_end": 23,
      "time_window_end_12h": "11PM",
      "time_window_end_ix": 17,
      "time_window_start": 18,
      "time_window_start_12h": "6PM",
      "time_window_start_ix": 12
  }
}

Response attributes Query Venues

The JSON response will contain a list with venue objects.

Query venue

Query a single venue:

import requests

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

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754'
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/venues/ven_51387131543761435650505241346a394a6432395362654a496843&
api_key_public=pub_e11661721b084d36b8f469a2c012e754'

fetch(`https://besttime.app/api/v1/venues/ven_51387131543761435650505241346a394a6432395362654a496843?api_key_public=pub_e11661721b084d36b8f469a2c012e754`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Query Venue

The 'query venue' endpoint is used to retrieve information about the venue. It does not contain forecasted data, except the day rankings for a week. This query endpoint requires the private API key. Although the private API keys is used, this endpoint will be charged with query credits.

The above request returns a JSON response like this:

{
    "epoch_analysis": 1585875838,
    "forecast_updated_on": "Fri, 03 Apr 2020 01:03:58 GMT",
    "status": "OK",
    "venue_forecasted": true,
    "venue_info": {
        "venue_address": "1201 Ocean Ave San Francisco, CA 94112",
        "venue_current_gmttime": "Friday 2021-04-23 07:26AM",
        "venue_current_localtime_iso": "Friday 2021-04-23 03:26PM",
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_lat": 37.7235448,
        "venue_lng": -122.455458,
        "venue_name": "McDonald's",
        "venue_timezone": "America/Los_Angeles",
        "venue_dwell_time_min": 20,
        "venue_dwell_time_max": 20,
        "venue_type": "FAST_FOOD",
        "venue_types": [
            "fast_food_restaurant",
            "breakfast_restaurant",
            "coffee_shop",
            "hamburger_restaurant",
            "restaurant",
            "sandwich_shop"
        ],
    }
}

Response attributes Query Venue

The JSON response will contain detailed venue information.

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query all venues

Query list of all forecasted venues:

import requests

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

params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b'
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/venues?
api_key_private=pri_50990bf1f8828f6abbf6152013113c6b'

fetch(`https://besttime.app/api/v1/venues?api_key_private=pri_50990bf1f8828f6abbf6152013113c6b`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Query All Venues

The 'query venues' endpoint is used to retrieve a list with all previously forecasted venues. This query endpoint requires the private API key. Although the private API keys is used, this endpoint will be charged with query credits.

The above request returns a JSON response like this (this example only contains a list with one venue):

[
    {
        "venue_address": "1201 Ocean Ave San Francisco, CA 94112 United States",
        "venue_forecasted": true,
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_name": "McDonald's"
    }
]

Response attributes Query Venues

The JSON response will contain a list with venue objects.

Venues Update

Show a list of venues that are older than a specified amount of weeks. Optionally update each listed venue with a 'new foot traffic forecast':

import requests

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

params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b'
    'weeks': 2,
    'update': False,
    'foottraffic': 'with'
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/venues/update?
api_key_private=pri_50990bf1f8828f6abbf6152013113c6b&
weeks=2&
update=false&
footttraffic=with'

const params = new URLSearchParams({ 
  'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
  'weeks': 2,
  'update': false,
  'foottraffic': 'with'
});

fetch(`https://besttime.app/api/v1/venues/update${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Venues Update

The 'Venues Update' endpoint returns a list of venues that are older than a specified amount of weeks for the given 'api_key_private'. Optionally update each listed venue with a 'new foot traffic forecast'. This endpoint can also be filtered by collection_id or a geographical bounding box. This is useful since venue foot traffic is only updated through a new 'New foot traffic forecast' per venue or venues from the 'Venue Search' results. The Venue Filter (except for live data) endpoint and other query endpoints will not update the foot traffic data.

Return only venues without a geographic bounding box: - lat_min float OPTIONAL
Minimum latitude of the bounding box (South-West). lat_min must be combined with lat_max, lng_min and lng_max. The bounding box cannot be combined with the circle parameters. Either a combination of a lat, lng, with a radius or lat_min, lng_min, lat_max, and lng_max is required.
  - lng_min float OPTIONAL
Minimum longitude of the bounding box (South-West). lng_min must be combined with lng_max, lat_min and lat_max.
  - lat_max float OPTIONAL
Maximum latitude of the bounding box (North-East). lat_max must be combined with lat_min, lng_min and lng_max.
  - lng_max float OPTIONAL
Maximum longitude of the bounding box (North-East). lng_max must be combined with lng_min, lat_min and lat_max.  

The above request returns a JSON response like this (this example only contains a list with one venue):

 {
   "message": "Venues with foot traffic data older than 2 week(s). Listed venues will not be updated. Set 'update=true' to create a new foot traffic forecast for each individual venue (normal 'new foot traffic forecast' API credits apply for each venue)",
    "status": "OK",
    "venues": [
        [
           "1201 Ocean Ave San Francisco, CA 94112 United States",
            "ven_51387131543761435650505241346a394a6432395362654a496843",
            "2021-03-05 04:37AM"
        ],....
    ],
    "venues_n": 298
 }

Response attributes Query Venues

The JSON response will contain a list with venue objects.

Query week

Query the week (whole forecast):

import requests

url = "https://besttime.app/api/v1/forecasts/week"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/week?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843'

const params = new URLSearchParams({ 
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
});

fetch(`https://besttime.app/api/v1/forecasts/week?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

The above request returns a JSON structured similar as the new forecast endpoint

Click here for the full JSON response

Input attributes

The 'query week' endpoint is used to retrieve all data from an existing forecast (every day of the week). The response structure is exactly the same as the new forecast response. Normally API credits are charged for this endpoint, but is free within one day after created a new forecast (through the Venue Search- or directly through the New Foot Traffic Forecast endpoint).

Response attributes

The response attributes are exactly the same as the attributes in the 'new forecast' endpoint.
  See new forecast reponse attributes

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query week raw

Query the raw week data:

import requests

url = "https://besttime.app/api/v1/forecasts/week/raw"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/week/raw?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843'

const params = new URLSearchParams({ 
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
});

fetch(`https://besttime.app/api/v1/forecasts/week/raw?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes

The 'query week raw' endpoint is used to retrieve the raw data from an existing forecast (every day of the week).

The above request returns JSON structured like this:

{
    "analysis": {
        "week_raw": [
            0.0,
            10.0,
            30.0,
            60.0,
            80.0,
            90.0,
            100.0,
            Other hours hidden 
            50.0,
            40.0,
            40.0,
            30.0,
            10.0,
            0.0,
            0.0
        ]
    },
    "epoch_analysis": 1585875838,
    "forecast_updated_on": "2020-04-03T01:03:58.692417+00:00",
    "venue_name": "McDonald's"
}

Alternative split per day data

Using the endpoint https://besttime.app/api/v1/forecasts/week/raw2 will result in the same response but split per day using the day window from 6am till 5am next day.

{
    "analysis": {
        "week_raw": [
            {
                "day_int": 0,
                "day_raw": [
                    20,
                    30,
                    40,
                    50,
                    60,
                    ...
                    60,
                    50,
                    40,
                    30,
                    20,
                    0,
                    20,
                    20
                ]
            },
            ....
        ]
    },
    "status": "OK",
    "window": {
        "day_window_end_int": 6,
        "day_window_end_txt": "Monday",
        "day_window_start_int": 0,
        "day_window_start_txt": "Monday",
        "time_window_end": 5,
        "time_window_end_12h": "5AM",
        "time_window_start": 6,
        "time_window_start_12h": "6AM",
        "week_window": "Monday 6AM until Monday 5AM next week"
    }
}

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query weekoverview

Query the week overview:

import requests

url = "https://besttime.app/api/v1/forecasts/weekoverview"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/weekoverview?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843'

const params = new URLSearchParams({ 
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
});

fetch(`https://besttime.app/api/v1/forecasts/weekoverview?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes

The 'query week' endpoint is used to retrieve all data from an existing forecast (every day of the week). The response structure is exactly the same as the new forecast response.

The above request returns a JSON response like this:

{
    "analysis": {
        "week_overview": [
            {
                "day_int": 0,
                "day_max": 100,
                "day_mean": 57,
                "day_rank_max": 1,
                "day_rank_mean": 6,
                "day_text": "Monday",
                "venue_closed": 4,
                "venue_open": 4
            },
            {
                "day_int": 1,
                "day_max": 96,
                "day_mean": 58,
                "day_rank_max": 3,
                "day_rank_mean": 5,
                "day_text": "Tuesday",
                "venue_closed": 4,
                "venue_open": 4
            },
            {
                "day_int": 2,
                "day_max": 99,
                "day_mean": 62,
                "day_rank_max": 2,
                "day_rank_mean": 1,
                "day_text": "Wednesday",
                "venue_closed": 4,
                "venue_open": 4
            },
            {
                "day_int": 3,
                "day_max": 87,
                "day_mean": 59,
                "day_rank_max": 6,
                "day_rank_mean": 4,
                "day_text": "Thursday",
                "venue_closed": 4,
                "venue_open": 4
            },
            {
                "day_int": 4,
                "day_max": 88,
                "day_mean": 61,
                "day_rank_max": 5,
                "day_rank_mean": 2,
                "day_text": "Friday",
                "venue_closed": 4,
                "venue_open": 4
            },
            {
                "day_int": 5,
                "day_max": 85,
                "day_mean": 60,
                "day_rank_max": 7,
                "day_rank_mean": 3,
                "day_text": "Saturday",
                "venue_closed": 4,
                "venue_open": 4
            },
            {
                "day_int": 6,
                "day_max": 93,
                "day_mean": 54,
                "day_rank_max": 4,
                "day_rank_mean": 7,
                "day_text": "Sunday",
                "venue_closed": 4,
                "venue_open": 4
            }
        ]
    },
    "forecast_updated_on": "2020-04-03T01:03:58.692417+00:00",
    "status": "OK"
}

Response attributes Weekoverview

### Combine a new forecast with this query in a single API call This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query day

Query one day of the week:

import requests

url = "https://besttime.app/api/v1/forecasts/day"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_int': 3
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/day?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843&
day_int=3'

const params = new URLSearchParams({ 
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_int': 3
});

fetch(`https://besttime.app/api/v1/forecasts/day?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Query Day

The 'query day' endpoint is used to retrieve all analysis from an existing forecast for a specific day of the week.

The above request returns a JSON response like this:

  {
  "analysis": {
    "busy_hours": [
      9,
      10,
      11
    ],
    "day_info": {
      "day_int": 0,
      "day_rank_max": 6,
      "day_rank_mean": 4,
      "day_text": "Monday",
      "venue_closed": 4,
      "venue_open": 4
    },
    "hour_analysis": [{
        "hour": 6,
        "intensity_nr": -1,
        "intensity_txt": "Below average"
      },
      {
        "hour": 7,
        "intensity_nr": -1,
        "intensity_txt": "Below average"
      },
      {
        "hour": 8,
        "intensity_nr": 0,
        "intensity_txt": "Average"
      },
      ....Other hours hidden. See below for the full JSON response example...
      {
        "hour": 5,
        "intensity_nr": -1,
        "intensity_txt": "Below average"
      }
    ],
    "peak_hours": [{
      "peak_delta_mean_week": 29,
      "peak_end": 23,
      "peak_intensity": 4,
      "peak_max": 11,
      "peak_start": 8
    }],
    "quiet_hours": [
      2,
      3,
      4,
      5
    ],
    "surge_hours": {
      "most_people_come": 8,
      "most_people_leave": 0
    }
  },
  "day_int": 0,
  "epoch_analysis": 1583400856,
  "forecast_updated_on": "2020-03-05T09:34:16.836061+00:00",
  "status": "OK",
  "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
  "venue_name": "McDonald's"
}

Click here for the full JSON response

Response attributes Query Day

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query day raw

Query the raw day data:

import requests

url = "https://besttime.app/api/v1/forecasts/day/raw"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_int': 3
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/day/raw?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843&
day_int=3'

const params = new URLSearchParams({ 
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_int': 3
});

fetch(`https://besttime.app/api/v1/forecasts/day/raw?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes

The 'query day raw' endpoint is used to retrieve the raw data from an existing forecast for one day of the week.

The above request returns JSON structured like this:

{
    "analysis": {
        "day_raw": [
            0.0,
            40.0,
            60.0,
            70.0,
            80.0,
            90.0,
            90.0,
            90.0,
            90.0,
            80.0,
            70.0,
            70.0,
            70.0,
            70.0,
            70.0,
            70.0,
            60.0,
            50.0,
            40.0,
            30.0,
            20.0,
            10.0,
            0.0,
            0.0
        ]
    },
    "epoch_analysis": 1585875838,
    "forecast_updated_on": "2020-04-03T01:03:58.685394+00:00",
    "status": "OK"
}

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query hour

Query a specific hour of the week:

import requests

url = "https://besttime.app/api/v1/forecasts/hour"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_int': 3,
    'hour':23
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/hour?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843&
day_int=3&
hour=23'

const params = new URLSearchParams({ 
  'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
  'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
  'day_int': 3,
  'hour': 23
});

fetch(`https://besttime.app/api/v1/forecasts/hour?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Query Hour

The 'query hour' endpoint is used to retrieve the 'hour analysis' forecast for the given hour and day of the week.

The above request returns a JSON reponse like this:

{
    "analysis": {
        "hour_analysis": {
            "hour": 23,
            "intensity_nr": 0,
            "intensity_txt": "Average"
        }
    },
    "day_int": 3,
    "epoch_analysis": 1583400856,
    "forecast_updated_on": "2020-03-05T09:34:16.842662+00:00",
    "status": "OK",
    "venue_info": {
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_name": "McDonald's"
    }
}

Click here for the raw JSON response.

Response attributes Query Hour

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query hour raw

Query the raw hour data:

import requests

url = "https://besttime.app/api/v1/forecasts/hour/raw"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_int': 3,
    'hour': 16
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/hour/raw?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843&day_int=3&hour=16'

const params = new URLSearchParams({ 
  'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
  'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
  'day_int':3,
  'hour':16
});

fetch(`https://besttime.app/api/v1/forecasts/hour/raw?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes

The 'query hour raw' endpoint is used to retrieve the raw data from an existing forecast for one hour of the day.

The above request returns JSON structured like this:

{
  "analysis": {
    "hour_analysis": {
      "hour": 16,
      "intensity_nr": 0,
      "intensity_txt": "Average"
    },
    "hour_raw": 70
  },
  "epoch_analysis": 1585890444,
  "forecast_updated_on": "2020-04-03T05:07:26.012357+00:00",
  "status": "OK",
  "venue_info": {
    "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
    "venue_name": "McDonald's"
  }
}

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query now

Query the now:

import requests

url = "https://besttime.app/api/v1/forecasts/now"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/now?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843'

const params = new URLSearchParams({ 
   'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
});

fetch(`https://besttime.app/api/v1/forecasts/now?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Query Now

The 'query now' endpoint is used to retrieve the 'hour analysis' forecast for the current hour. The hour is the venues current hour with the local timezone taken into account.

The above request returns a JSON response like this:

{
    "analysis": {
        "hour_analysis": {
            "hour": 23,
            "intensity_nr": 0,
            "intensity_txt": "Average"
        }
    },
    "day_int": 3,
    "epoch_analysis": 1583400856,
    "forecast_updated_on": "2020-03-05T09:34:16.842662+00:00",
    "status": "OK",
    "venue_info": {
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_name": "McDonald's",
        "venue_current_gmttime": "Saturday 2020-04-24 04:03AM",
        "venue_current_localtime_iso": "Saturday 2020-04-24 12:02PM"
    }
}

Click here for the raw JSON response.

Response attributes Query Current Hour

The response attributes are the same as the attributes in the 'query hour' endpoint. See query hour response attributes.

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query now raw

Query the raw hour data for current hour:

import requests

url = "https://besttime.app/api/v1/forecasts/now/raw"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/now/raw?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843'

const params = new URLSearchParams({ 
  'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
  'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
});

fetch(`https://besttime.app/api/v1/forecasts/now/raw?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes

The 'query now raw' endpoint is used to retrieve the raw data from an existing forecast for one hour of the day. It automatically determines the current day and hour in the local timezone of the venue.

The above request returns JSON structured like this:

{
  "analysis": {
    "hour_analysis": {
      "hour": 16,
      "intensity_nr": 0,
      "intensity_txt": "Average"
    },
    "hour_raw": 70
  },
  "epoch_analysis": 1585890444,
  "forecast_updated_on": "2020-04-03T05:07:26.012357+00:00",
  "status": "OK",
  "venue_info": {
    "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
    "venue_name": "McDonald's",
    "venue_current_gmttime": "Saturday 2020-04-24 04:03AM",
    "venue_current_localtime_iso": "Saturday 2020-04-24 12:02PM"
  }
}

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query peak hours

Query peaks:

import requests

url = "https://besttime.app/api/v1/forecasts/peaks"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_step': 0,
    'hour_step': 0
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/peaks?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843&
day_step=0&
hour_step=0'

const params = new URLSearchParams({ 
  'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
  'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
  'day_step': 0,
  'hour_step': 0
});

fetch(`https://besttime.app/api/v1/forecasts/peaks?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Query Peaks

The 'query peaks' endpoint is used to retrieve all peaks from an existing forecast for a specific day of the week. By default, the response includes the peak objects for the current day (at the local timezone of the venue) peak_hours. Additionally, it contains a list with peak objects peaks_coming which only contains the peaks from peak_hours which have not passed yet.

The above request returns a JSON response like this:

{
    "analysis": {
        "day_info": {
            "day_int": 1,
            "day_rank_max": 2,
            "day_rank_mean": 4,
            "day_text": "Tuesday",
            "venue_closed": 4,
            "venue_open": 4
        },
        "peak_hours": [
            {
                "peak_delta_mean_week": 37,
                "peak_end": 18,
                "peak_end_12h": "6PM",
                "peak_end_in": "2 hour and 40 minutes",
                "peak_end_in_sec": 9660,
                "peak_end_passed": 0,
                "peak_intensity": 5,
                "peak_max": 13,
                "peak_max_12h": "1PM",
                "peak_max_in": "Peak maximum already passed",
                "peak_max_in_sec": 0,
                "peak_max_passed": 1,
                "peak_start": 7,
                "peak_start_12h": "7AM",
                "peak_start_in": "Peak already started",
                "peak_start_passed": 1
            },
            {
                "peak_delta_mean_week": 12,
                "peak_end": 23,
                "peak_end_12h": "11PM",
                "peak_end_in": "7 hour and 41 minutes",
                "peak_end_in_sec": 27660,
                "peak_end_passed": 0,
                "peak_intensity": 3,
                "peak_max": 21,
                "peak_max_12h": "9PM",
                "peak_max_in": "5 hour and 41 minutes",
                "peak_max_in_sec": 20460,
                "peak_max_passed": 0,
                "peak_start": 18,
                "peak_start_12h": "6PM",
                "peak_start_in": "2 hour and 40 minutes",
                "peak_start_in_sec": 9660,
                "peak_start_passed": 0
            }
        ]
    },
    "epoch_analysis": 1583400856,
    "forecast_updated_on": "2020-03-05T09:34:16.842016+00:00",
    "status": "OK",
    "venue_info": {
        "venue_current_gmttime": "Tue, 10 Mar 2020 22:19:56 GMT",
        "venue_current_localtime_iso": "2020-03-10T15:19:56.979659-07:00",
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_name": "McDonald's",
        "venue_timezone": "America/Los_Angeles"
    }
}

Response attributes Query Peaks

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query busy hours

Query busy hours:

import requests

url = "https://besttime.app/api/v1/forecasts/busy"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_step': 0
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/busy?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843&
day_step=0'

const params = new URLSearchParams({ 
  'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
  'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
  'day_step': 0
});

fetch(`https://besttime.app/api/v1/forecasts/busy?${params}`, {
  method: 'get'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Query Busy hours

The 'query busy hours' endpoint is used to retrieve all busy hour information from an existing forecast for a specific day of the week. By default, the response includes the busy hour information for the current day (at the local timezone of the venue).

The above request returns a JSON response like this:

{
    "analysis": {
        "busy_hours": [
            {
                "busy_end": 14,
                "busy_end_12": "2PM",
                "busy_end_in": "2 hour and 16 minutes",
                "busy_end_in_sec": 8220,
                "busy_end_passed": 0,
                "busy_period_duration": 4,
                "busy_start": 10,
                "busy_start_12": "10AM",
                "busy_start_in": "Start of busy period already passed",
                "busy_start_in_sec": 0,
                "busy_start_passed": 1
            },
            {
                "busy_end": 20,
                "busy_end_12": "8PM",
                "busy_end_in": "8 hour and 16 minutes",
                "busy_end_in_sec": 29820,
                "busy_end_passed": 0,
                "busy_period_duration": 4,
                "busy_start": 16,
                "busy_start_12": "4PM",
                "busy_start_in": "4 hour and 16 minutes",
                "busy_start_in_sec": 15420,
                "busy_start_passed": 0
            }
        ],
        "busy_hours_list": [
            10,
            11,
            12,
            13,
            16,
            17,
            18,
            19
        ],
        "busy_hours_list_12h": [
            "10AM",
            "11AM",
            "12PM",
            "1PM",
            "4PM",
            "5PM",
            "6PM",
            "7PM"
        ],
        "busy_hours_list_coming": [
            12,
            13,
            16,
            17,
            18,
            19
        ],
        "busy_hours_list_coming_12h": [
            "12PM",
            "1PM",
            "4PM",
            "5PM",
            "6PM",
            "7PM"
        ],
        "day_info": {
            "day_int": 4,
            "day_rank_max": 7,
            "day_rank_mean": 3,
            "day_text": "Friday",
            "venue_closed": 4,
            "venue_open": 4
        }
    },
    "epoch_analysis": 1583911633,
    "forecast_updated_on": "2020-03-11T07:27:13.849228+00:00",
    "status": "OK",
    "venue_id": "wqXCm8K8wr7DmcKTw4BsU8KWemrCo8KWdMOFw4TDhMKHwrDClFjChmHConHCsw==",
    "venue_info": {
        "venue_current_gmttime": "Fri, 13 Mar 2020 18:43:30 GMT",
        "venue_current_localtime_iso": "2020-03-13T11:43:30.101057-07:00",
        "venue_id": "wqXCm8K8wr7DmcKTw4BsU8KWemrCo8KWdMOFw4TDhMKHwrDClFjChmHConHCsw==",
        "venue_name": "McDonald's",
        "venue_timezone": "America/Los_Angeles"
    },
    "venue_name": "McDonald's"
}

Response attributes Query Busy hours

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query quiet hours

Query quiet hours:

import requests

url = "https://besttime.app/api/v1/forecasts/quiet"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_step': 0,
    'hour_step':0
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/quiet?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843&
day_step=0&
hour_step=0'

const params = new URLSearchParams({ 
  'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
  'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
  'day_step': 0,
  'hour_step': 0
});

fetch(`https://besttime.app/api/v1/forecasts/quiet?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Query Quiet hours

The 'query quiet hours' endpoint is used to retrieve all quiet hour information from an existing forecast for a specific day of the week. By default, the response includes the quiet hour information for the current day (at the local timezone of the venue).

The above request returns a JSON response like this:

{
    "analysis": {
        "day_info": {
            "day_int": 4,
            "day_rank_max": 7,
            "day_rank_mean": 3,
            "day_text": "Friday",
            "venue_closed": 4,
            "venue_open": 4
        },
        "quiet_hours": [
            {
                "quiet_end": 8,
                "quiet_end_12": "8AM",
                "quiet_end_in": "End of quiet period already passed",
                "quiet_end_in_sec": 0,
                "quiet_end_passed": 1,
                "quiet_period_duration": 2,
                "quiet_start": 6,
                "quiet_start_12": "6AM",
                "quiet_start_in": "Start of quiet period already passed",
                "quiet_start_in_sec": 0,
                "quiet_start_passed": 1
            },
            {
                "quiet_end": 6,
                "quiet_end_12": "6AM",
                "quiet_end_in": "18 hour and 7 minutes",
                "quiet_end_in_sec": 65280,
                "quiet_end_passed": 0,
                "quiet_period_duration": 3,
                "quiet_start": 3,
                "quiet_start_12": "3AM",
                "quiet_start_in": "15 hour and 7 minutes",
                "quiet_start_in_sec": 54480,
                "quiet_start_passed": 0
            }
        ],
        "quiet_hours_list": [
            6,
            7,
            3,
            4,
            5
        ],
        "quiet_hours_list_12h": [
            "6AM",
            "7AM",
            "3AM",
            "4AM",
            "5AM"
        ],
        "quiet_hours_list_coming": [
            3,
            4,
            5
        ],
        "quiet_hours_list_coming_12h": [
            "3AM",
            "4AM",
            "5AM"
        ]
    },
    "epoch_analysis": 1583911633,
    "forecast_updated_on": "2020-03-11T07:27:13.849228+00:00",
    "status": "OK",
    "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
    "venue_info": {
        "venue_current_gmttime": "Fri, 13 Mar 2020 18:52:28 GMT",
        "venue_current_localtime_iso": "2020-03-13T11:52:28.890102-07:00",
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_name": "McDonald's",
        "venue_timezone": "America/Los_Angeles"
    },
    "venue_name": "McDonald's"
}

Response attributes Query Quiet hours

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Query surge hours

Query surge hours:

import requests

url = "https://besttime.app/api/v1/forecasts/surge"

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_step': 0,
    'hour_step':0
}

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

# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/surge?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843&
day_step=0&
hour_step=0'

const params = new URLSearchParams({ 
  'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
  'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
  'day_step': 0,
  'hour_step': 0
});

fetch(`https://besttime.app/api/v1/forecasts/surge?${params}`, {
  method: 'GET'
}).then(function(data) { 
  console.log(data); 
});

Input attributes Query surge hours

The 'query surge hours' endpoint is used to retrieve all surge hour information from an existing forecast for a specific day of the week. By default, the response includes the surge hour information for the current day (at the local timezone of the venue).

The above request returns a JSON response like this:

{
    "analysis": {
        "day_info": {
            "day_int": 0,
            "day_rank_max": 5,
            "day_rank_mean": 5,
            "day_text": "Monday",
            "venue_closed": 4,
            "venue_open": 4
        },
        "surge_hours": {
            "most_people_come": 8,
            "most_people_come_12h": "8AM",
            "most_people_come_passed": 0,
            "most_people_come_start_in": "Most people are coming in now",
            "most_people_come_start_in_sec": 0,
            "most_people_leave": 1,
            "most_people_leave_12h": "1AM",
            "most_people_leave_passed": 0,
            "most_people_leave_start_in": "16 hour and 26 minutes",
            "most_people_leave_start_in_sec": 59160
        }
    },
    "epoch_analysis": 1583911633,
    "forecast_updated_on": "2020-03-11T07:27:13.841800+00:00",
    "status": "OK",
    "venue_info": {
        "venue_current_gmttime": "Mon, 16 Mar 2020 15:34:59 GMT",
        "venue_current_localtime_iso": "2020-03-16T08:34:59.778538-07:00",
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_name": "McDonald's",
        "venue_timezone": "America/Los_Angeles"
    },
    "venue_name": "McDonald's"
}

Response attributes Query Surge hours

Combine a new forecast with this query in a single API call

This query endpoint takes data from an earlier forecasted venue. You can also combine a fresh forecast and get the results from this query endpoint using:

See the New Forecast endpoint for more information on the venue_name and venue_address input. This will be counted as new forecast credits instead of a query credit.

Examples

Foot traffic forecast + Live chart (HTML / Javascript)

See example on Github

Foot traffic Week heatmap (HTML / Javascript)

See example on Github

python javascript shell