Get Demand Surges

Identify dates with surges in demand caused by multiple events happening at the same time and location.

The Demand Surge API can be used to quickly scan a period of 90 days for abnormal increases in attendance for a given area. The API calculates the mean attendance for your requested location over the next 90 days after the date_from date and returns all the dates where attendance is a certain number of standard deviations over the mean. This is represented by the min_surge_intensity parameter, that corresponds to the number of standard deviations the API will look for.

Once you have identified the dates with the surge in demand, you can use:

• Our Events API to find the names, descriptions, locations, and other details of the events that constitute the surges.

• Our Features API to get Machine Learning features for events in your searched date range.

Request

HTTP Request

GET https://api.predicthq.com/v1/demand-surge/

Query Parameters

Parameter	Description
date_from date	The beginning of the demand surge search window. The demand surge will be looked up over the next 90 days after the date you provide for the date_from parameter. The accepted format for this parameter is YYYY-MM-DD E.g. ?date_from=2021-05-12
min_surge_intensity string	Filters out demand surges smaller than the minimum surge intensity provided. Possible values: s - Small m - Medium l - Large xl - Extra Large E.g. ?min_surge_intensity=m
location.* string	The location to use in the demand surge search window. Supports place_idOR origin and radius suffixes. place_id: A comma-separated list in the format representing the place ids of a location in the format <place_id1>,<place_id2> . It cannot be used with origin or radius suffixes. E.g. ?location.place_id=2643743,2643744 origin: A comma-separated coordinate (<lat>,<lon>) representing the centroid of a location. It must be used with radius suffix and cannot be used with place_id suffix. E.g. ?location.origin=40.7128,74.0060 radius: A string representing the radius for the demand surge, in the format <radius_value><radius_unit>, where <radius_value> is an integer or a float number up to 2 decimal places and <radius_unit> is one of: m - meters km - kilometers ft - feet mi - miles E.g. ?location.radius=100mi

Response

Response Fields

Field	Description
count number	The number of identified demand surges given the search criteria.
surge_dates array	An array of identified demand surges.
date date	The date of the identified demand surge.
phq_attendance_sum number	The sum of all attendance based features in the identified demand surge.

Example response

Below is an example response:

{
    "count": 2,
    "surge_dates": [
        {
            "date": "2021-08-07",
            "phq_attendance_sum": 233930
        },
        {
            "date": "2021-08-08",
            "phq_attendance_sum": 213382
        }
    ]
}

Examples

curl

curl -X GET "https://api.predicthq.com/v1/demand-surge/?date_from=2021-05-12&min_surge_intensity=m&location.place_id=2643743" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

python

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/demand-surge/",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    },
    params={
        "date_from": "2021-05-12",
        "min_surge_intensity": "m",
        "location.place_id": "2643743"
    }
)

print(response.json())