NAV Navbar
shell python javascript

Introduction

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

What is BestTime.app?

BestTime.app is a web (API) service that forecasts how busy a public business (e.g. restaurant, gym, etc) will be at any given hour of the week. 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.

Besides hour forecasts, additional analysis are included. For example, the peak hours of the day, if it is now more busy than normal compared to the average, and a ranking of the busiest days of the week.

Once a business has been forecasted additional queries can be made on the forecast. For example: When is today's next peak? When will it be quiet on Saturday? How busy will it be next hour?

Using the Radar tool or the Query filtered venues api endpoint venues can be filtered on how busy they are, location, time & day, and business type.

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 worldwide coverage, but 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. Only when a business can be forecasted credits will be subtracted from your account.

Data retention

Forecast will only be stored on the server for a specific amount 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.

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 24-hour notation, displayed from 0 to 23. Where 0 indicates midnight and 23 indicates 11 pm. To make forecasts more useful in real-life the window for one day has been set from 6 am until 5 am next day. This is for example useful for public venues with late opening times like bars and nightclubs. If you query for example the data for a Monday. The result includes the hours for Monday 6 am until Tuesday 5 am.

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. Our API accepts only JSON-encoded POST requests and returns JSON-encoded responses. This makes it easier to request venue names and addresses without the need to encode the parameters (like you would usually need to do with GET query parameters).

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.

Authentication

To authorize, use this code:

import requests

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

payload = {}
headers= {}

response = requests.request("GET", url, headers=headers, data = payload)

print(response.text.encode('utf8'))
# cURL
curl --location --request GET 'https://besttime.app/api/v1/keys/pri_a00de9e302662c0217a9cf08ab304122'
var settings = {
  "url": "https://besttime.app/api/v1/keys/pri_a00de9e302662c0217a9cf08ab304122",
  "method": "GET"
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

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",
    "credits_forecast": 300,
    "credits_query": 10000000,
    "status": "OK",
    "valid": true
  }

Private and public API keys

Credits

The API usage is counted with credits and the amount 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 the used credits.

When querying an existing forecast a query credit is counted for every request. The public API key can only perform read-only actions, but you could choose to hide the public key on public websites (e.g. in your website back-end) to lower your query credit usage (or to prevent abuse).
 

API Endpoint Credits API Key required
New forecasts (success) 2 Private
New forecasts (unsuccessful) 1 Private
Live data 1 Private
Venue (filter) (basic plan) 1 / venue Private
Venue (filter) (premium plan) 1 / 10 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.

Subscription plans

BestTime has two types of plans. Metered and unlimited 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, However the forecast data is only stored for 1 day (retention days). After 1 day you will need to forecast a venue again to query an existing forecast or to use the venue in the venue filter endpoint (or radar tool). Upgrade to the premium plan to increase the retention days and benefit from lower-priced API credits.

BestTime also offers multiple 'Unlimited' plans if you don't like the uncertainty of a metered plan. The unlimited plans have a fixed price per month and unlimited forecast, live, query and venue API calls. However, each unlimited plan is limited to a certain amount of new venues per calender month. Contact us for a custom amount of retention days or for a higher monthly amount of unlimited venues.

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 10 seconds per IP address. You will receive a HTTP 429 'too many requests' above this threshold. Contact us for if you need higher limits.

Forecasts endpoints

New forecast

Create a new forecast:

import requests
import json

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)

data = json.loads(response.text)

print(data)
# 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'
var params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
    'venue_name': 'McDonalds',
    'venue_address': 'Ocean Ave, San Fransisco'
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts?" + new URLSearchParams(params),
"method": "POST"
}).done(function (response) {
    console.log(response);
});

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
            },
            "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"
    }
}}

Click here for the full JSON response

The 'new 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 amount of days (see data retention)

Input attributes New Forecast

Response attributes New Forecast

Live forecast

Create a Live forecast:

import requests
import json

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)

data = json.loads(response.text)

print(data)
# 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'
var params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
    'venue_name': 'McDonalds',
    'venue_address': 'Ocean Ave, San Fransisco'
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/live?" + new URLSearchParams(params),
"method": "POST"
}).done(function (response) {
    console.log(response);
});

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

Input attributes New Forecast

The above request returns JSON structured like this:

{
    "analysis": {
        "venue_forecasted_busyness": 60,
        "venue_live_busyness": 20,
        "venue_live_busyness_available": true,
        "venue_live_forecasted_detla": -40
    },
    "status": "OK",
    "venue_info": {
        "venue_current_gmttime": "Thu, 12 Mar 2020 13:05:53 GMT",
        "venue_current_localtime_iso": "2020-03-12T06:05:53.948572-07:00",
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_name": "McDonald's",
        "venue_timezone": "America/Los_Angeles"
    }
}

Response attributes Live Forecast

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.

Query venue

Query a single venue:

import requests
import json

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

params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754'
}

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

data = json.loads(response.text)

print(data)
# cURL
curl --location --request GET 'https://besttime.app/api/v1/venues/en_51387131543761435650505241346a394a6432395362654a496843&
api_key_public=pub_e11661721b084d36b8f469a2c012e754'
$.ajax({
"url": "https://besttime.app/api/v1/venues/ven_51387131543761435650505241346a394a6432395362654a496843?api_key_public=pub_e11661721b084d36b8f469a2c012e754",
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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": "Fri, 03 Apr 2020 03:03:51 GMT",
        "venue_current_localtime_iso": "2020-04-02T20:03:51.063663-07:00",
        "venue_id": "ven_51387131543761435650505241346a394a6432395362654a496843",
        "venue_lat": 37.7235448,
        "venue_lng": -122.455458,
        "venue_name": "McDonald's",
        "venue_timezone": "America/Los_Angeles"
    }
}

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
import json

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

params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b'
}

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

data = json.loads(response.text)

print(data)
# cURL
curl --location --request GET 'https://besttime.app/api/v1/venues?
api_key_private=pri_50990bf1f8828f6abbf6152013113c6b'
$.ajax({
"url": "https://besttime.app/api/v1/venues?api_key_private=pri_50990bf1f8828f6abbf6152013113c6b",
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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.

Query filtered venues (Radar)

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

import requests
import json

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,
    'now': False,
    'live': False,
    'types': ['BAR','CAFE','NIGHTCLUB'],
    'lat': 51.5121172,
    'lng': -0.126173,
    'radius': 2000
}

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

data = json.loads(response.text)

print(data)
# 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&now=false&live=false&types=BAR,CAFE,NIGHTCLUB&lat=51.5121172&lng=-0.126173&radius=2000
var params = {
    'api_key_private': 'pri_50990bf1f8828f6abbf6152013113c6b',
    'busy_min': 50,
    'busy_max': 100,
    'hour_min': 18,
    'hour_max': 23,
    'now': false,
    'live': false,
    'types': ['BAR','CAFE','NIGHTCLUB'],
    'lat': 51.5121172,
    'lng': -0.126173,
    'radius': 2000
}

$.ajax({
"url": "https://besttime.app/api/v1/venues/filter?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

Input attributes Venue Filter

The 'venue filter' endpoint will return all venues and the raw forecasted busyness data that meet the filter requirements. Venues can be filtered on how busy they are, on location, type of venue, day & time range, 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 with the given private API key.

This query endpoint requires the private API key. Although the private API keys is used, this endpoint will be charged with query credits.

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.

To prevent manually adding all venues in a specific area (e.g. neighborhood or city) the 'Add Area' tool can be used (expected to be released in August 2020). Using this tool the user can define a geographical bounding box, select multiple desired types of venues (e.g. supermarkets, gyms, restaurants, etc). Under the hood it uses the Google Maps Nearby API to discover venues in the defined area (you will need a Google Maps API key). This geocoder has currently the biggest database and gives the best results.

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_int": 0, 
      "day_raw": [
        0, 
        20, 
        80, 
        80, 
        20, 
        0
      ], 
      "venue_address": "61 Piccadilly Mayfair, London W1J 0DY United Kingdom", 
      "venue_id": "ven_386d55494f76464873784752676b6445593949455752594a496843", 
      "venue_lat": 51.5079836, 
      "venue_lng": -0.1404946, 
      "venue_name": "Caffe Concerto Green Park"
    }, 
    {
      "day_int": 0, 
      "day_raw": [
        40, 
        60, 
        60, 
        0, 
        0, 
        0
      ], 
      "venue_address": "14 Riding House St Fitzrovia, London W1W 7HR United Kingdom", 
      "venue_id": "ven_6372542d36476a4a59686d52676b646155646e713661514a496843", 
      "venue_lat": 51.5183082, 
      "venue_lng": -0.1415526, 
      "venue_name": "The Great Thai Restaurant"
    }
  ]
}

Response attributes Query Venues

The JSON response will contain a list with venue objects.

Query week

Query the week (whole forecast):

import requests
import json

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)

data = json.loads(response.text)

print(data)
# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/week?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843'
var params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/week?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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.

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
import json

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)

data = json.loads(response.text)

print(data)
# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/week/raw?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843'
var params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/week/raw?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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
import json

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)

data = json.loads(response.text)

print(data)
# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/weekoverview?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843'
var params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/weekoverview?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(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.

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
import json

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)

data = json.loads(response.text)

print(data)
# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/day?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843&
day_int=3'
var params = {
   'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_int': 3
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/day?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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
import json

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)

data = json.loads(response.text)

print(data)
# 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'
var params = {
   'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_int': 3
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/day/raw?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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
import json

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)

data = json.loads(response.text)

print(data)
# 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'
var params = {
      'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
      'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
      'day_int': 3,
      'hour': 23
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/hour?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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
import json

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)

data = json.loads(response.text)

print(data)
# 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'
var params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_int':3,
    'hour':16
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/hour/raw?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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
import json

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)

data = json.loads(response.text)

print(data)
# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/now?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843'
var params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/now?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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"
    }
}

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
import json

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)

data = json.loads(response.text)

print(data)
# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/now/raw?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843'
var params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843'
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/now/raw?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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"
  }
}

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
import json

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)

data = json.loads(response.text)

print(data)
# 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'
var params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_step': 0,
    'hour_step': 0
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/peaks?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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
import json

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)

data = json.loads(response.text)

print(data)
# cURL
curl --location --request GET 'https://besttime.app/api/v1/forecasts/busy?api_key_public=pub_e11661721b084d36b8f469a2c012e754&venue_id=ven_51387131543761435650505241346a394a6432395362654a496843&
day_step=0'
var params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_step': 0
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/busy?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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
import json

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)

data = json.loads(response.text)

print(data)
# 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'
var params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_step': 0,
    'hour_step': 0
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/quiet?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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
import json

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)

data = json.loads(response.text)

print(data)
# 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'
var params = {
    'api_key_public': 'pub_e11661721b084d36b8f469a2c012e754',
    'venue_id': 'ven_51387131543761435650505241346a394a6432395362654a496843',
    'day_step': 0,
    'hour_step': 0
}

$.ajax({
"url": "https://besttime.app/api/v1/forecasts/surge?" + new URLSearchParams(params),
"method": "GET"
}).done(function (response) {
    console.log(response);
});

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.