BestTime.app
BestTime.app · Acciones GPT
Venue Filtering API
API to filter venues based on busyness, type, and location.
POST /api/v1/venues/filter/gptfilterVenuesFind venues based on various criteria such as busyness (popular visitor times), area name, time, type, and location
Esquema original API
{
"openapi": "3.1.0",
"info": {
"title": "Venue Filtering API",
"description": "API to filter venues based on busyness, type, and location.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://besttime.app/"
}
],
"paths": {
"/api/v1/venues/filter/gpt": {
"post": {
"description": "Find venues based on various criteria such as busyness (popular visitor times), area name, time, type, and location",
"operationId": "filterVenues",
"parameters": [
{
"name": "usermsg",
"in": "query",
"description": "Exact user chat input.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "busy_min",
"in": "query",
"description": "Min popular times % during the day.",
"required": true,
"schema": {
"type": "integer",
"default": 1,
"minimum ": 1,
"maximum": 100
}
},
{
"name": "busy_max",
"in": "query",
"description": "Max popular times % during the day.",
"required": false,
"schema": {
"type": "integer",
"minimum ": 20,
"maximum": 100
}
},
{
"name": "hour_min",
"in": "query",
"description": "filter foot traffic after a hour 24f format. Midnight is 0.",
"required": false,
"schema": {
"type": "integer",
"minimum ": 0,
"maximum": 23
}
},
{
"name": "hour_max",
"in": "query",
"description": "filter foot traffic before a hour in 24h format. Midnight is 0.",
"required": false,
"schema": {
"type": "integer",
"minimum ": 0,
"maximum": 23
}
},
{
"name": "day_int",
"in": "query",
"description": "0 (Monday) to 6 (Sunday). Current day if ignored",
"required": false,
"schema": {
"type": "integer",
"minimum ": 0,
"maximum": 6
}
},
{
"name": "types",
"in": "query",
"description": "Types of venues to filter. Options examples are BAR, BEER, BREWERY, WINERY, CLUBS, RESTAURANT, RESTAURANT,BURGER_RESTAURANT, COFFEE,CAFE,BAKERY,TEA,BREAKFAST_RESTAURANT, SHOPPING,DEPARTMENT_STORE,MARKET,SHOPPING_CENTER, APPAREL, FAST_FOOD, SUPERMARKET, GROCERY, PARK, APPAREL, FOOD_AND_DRINK, CAFE, SHOPPING_CENTER, COFFEE, MUSEUM, LIBRARY, TOURIST_DESTINATION, SPA, MARKET,ART_GALLERY,AMUSEMENT_PARK, CHURCH,ZOO,BOTANICAL_GARDEN,MARKET,PERFORMING_ARTS,CONCERT_HALL.",
"required": false,
"schema": {
"type": "string",
"format": "csv"
}
},
{
"name": "area",
"in": "query",
"description": "area such as a neighborhood,city or specific POI",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "limit the number of venues returned. Max 10 in the free version.",
"required": true,
"schema": {
"type": "integer",
"default": 10,
"minimum ": 1,
"maximum": 10
}
},
{
"name": "page",
"in": "query",
"description": "Page number to get more venues if the users asks. Max 3 in the free version.",
"required": false,
"schema": {
"type": "integer",
"default": 0,
"minimum ": 0,
"maximum": 3
}
},
{
"name": "price_min",
"in": "query",
"description": "Min price level. 1 to 5",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5
}
},
{
"name": "price_max",
"in": "query",
"description": "Max price level. 1 to 5.",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5
}
},
{
"name": "rating_min",
"in": "query",
"description": "Minimum rating for a venue. Possible values are 2.0, 2.5, 3.0, 3.5, 4.0, 4.5. Venues without a rating (0) will NOT be returned when applying this filter.",
"required": false,
"schema": {
"type": "number",
"enum": [
2,
2.5,
3,
3.5,
4,
4.5
],
"default": 3.5
}
},
{
"name": "rating_max",
"in": "query",
"description": "Maximum rating for a venue. Possible values are 2.0, 3.0, 3.5, 4.0, 4.5, 5.0. Venues without a rating (0) WILL be returned when applying this filter.",
"required": false,
"schema": {
"type": "number",
"enum": [
2,
3,
3.5,
4,
4.5,
5
]
}
},
{
"name": "reviews_min",
"in": "query",
"description": "Minimum number of reviews for a venue.",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "reviews_max",
"in": "query",
"description": "Maximum number of reviews for a venue.",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "order_by",
"in": "query",
"description": "Sort venues on foot traffic intensity data or order venues by a specific parameter. Can be reviews (popularity), rating, price_level, dwell_time_min, dwell_time_max, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23. Default is reviews (proxy for popularity). The 24 numbers represent the foot traffic data for each of the 24 hours in a day. E.g. 16 will sort the venues based on predicted foot traffic at 16:00 (4PM).",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "order",
"in": "query",
"description": "Order the order_by parameters ascending or descending. Can be asc or desc. Default desc.",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
}
],
"responses": {
"200": {
"description": "a list of filtered venues. The day_raw key contains by default foot traffic percentages for each hour of the week from 6AM until 5AM next day (unless the hour_min and hour_max are used. In that case the array starts with the hour_min and ends with the hour_max value).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "OK"
},
"besttime_url": {
"type": "url to view this data on BestTime.app"
},
"venues": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Venue"
}
},
"venues_n": {
"type": "integer",
"description": "The number of venues returned by the search."
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Venue": {
"type": "object",
"properties": {
"day_info": {
"type": "object",
"properties": {
"day_int": {
"type": "integer"
},
"day_max": {
"type": "integer",
"description": "Indicating the maximum busyness percentage. Values (0 - 100%) are based on the hour with the most visitors of the day, relative to the biggest peak of the week for this venue."
},
"venue_closed": {
"description": "The closing time of the venue in 24-hour int format. 0 is midnight."
},
"venue_open": {
"type": "integer",
"description": "The opening time of the venue in 24-hour int format. 0 is midnight."
}
}
},
"day_raw": {
"type": "array",
"items": {
"type": "integer",
"description": "The popular times percentage for each the hour of the week. 100% indicates the most busy visiting hour of the week for a venue. The array starts with 6AM on Monday and ends with 5AM on Monday. The array is 24 hours long."
}
},
"price_level": {
"type": "integer",
"description": "The price level of the venue. Ranges from 1 to 5. Should be presented with one or multiple $ signs."
},
"rating": {
"type": "number",
"description": "The average rating for the venue. Ranges from 1 to 5. Should be presented as a star rating."
},
"reviews": {
"type": "integer"
},
"venue_address": {
"type": "string"
},
"venue_dwell_time_max": {
"type": "integer",
"description": "The maximum dwell time in minutes for the venue. This is the maximum time that the average visitor spends at the venue."
},
"venue_dwell_time_min": {
"type": "integer",
"description": "The minimum dwell time in minutes for the venue. This is the minimum time that the average visitor spends at the venue."
},
"venue_name": {
"type": "string"
},
"venue_type": {
"type": "string"
},
"peak_hours": {
"type": "array",
"items": {
"type": "object",
"properties": {
"peak_max": {
"type": "integer",
"description": "The peak hour when most visitors are at the venue. 0 is midnight."
},
"peak_start": {
"type": "integer",
"description": "The start hour of the peak in 24H notation. 0 is midnight."
},
"peak_end": {
"type": "integer",
"description": "The end hour of the peak in 24H notation. 0 is midnight."
},
"peak_intensity": {
"type": "integer",
"description": "The intensity of the peak, ranging from 1 to 5 (5 being the most busy)."
}
}
}
}
}
}
}
}
}