Demand Surge

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 across 90 days, then 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, which corresponds to the number of standard deviations the API will look for.

Once identified, demand surges can be further explored in our Events or Features APIs, to find the names, descriptions and details of the events that constitute the surges.

Search Demand Surge

Use the parameters described below to search and filter all demand surges that are available to your account.

A search requires all of the date_from, date_to, min_surge_intensity and location.* query parameters.

Query Parameters

Parameter	Description
date_from date	The start date of the demand surge search window. The accepted format for this parameter is `YYYY-MM-DD` E.g. `?date_from=2021-05-12`
date_to date	The end date of the demand surge search window. The accepted format for this parameter is `YYYY-MM-DD` E.g. `?date_to=2021-08-10`
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	Filters out demand surges not included in the location specified. Supports `place_id`, `origin` and `radius` suffixes. `place_id`: Comma separated list (`<place_id1>,<place_id2>`) representing the place ids of a location. It cannot be used with `origin` or `radius` suffixes. E.g. `?location.place_id=2643743,2643744` `origin`: 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`: String representing the radius (`<number><unit>`) of a location . It must be used with `origin` suffix and cannot be used with `place_id` suffix. Possible units: `f` - Feet `mi` - Miles `m` - Meters `km` - Kilometers E.g. `?location.radius=100mi`

Action

GET /v1/demand-surge/

Example

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

HTTP/1.1 200 OK
Content-Type: application/json

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

Demand Surge Fields

Below are the fields returned by the Demand Surge endpoint. Please note that these are not the fields used for filtering - please refer to the Search Demand Surge section to discover which parameters can be used for filtering demand surges.

JSON Schemas are available for the Demand Surge endpoint and for a single demand surge:

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