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.

Get Demand Surges

get

Authorizations

BearerAuth

Query parameters

min_surge_intensitystring · enumRequired

Filters out demand surges smaller than the minimum surge intensity provided.

E.g. ?min_surge_intensity=m

Possible values:

date_fromstring · dateRequired

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

location.place_idstring[]Optional

A comma-separated list of place ids

location.originstring[]Optional

A comma-separated coordinate representing the centroid of a location

location.radiusstringOptional

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

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/v1/demand-surge/

HTTPcURLJavaScriptPython

GET /v1/demand-surge/?min_surge_intensity=s&date_from=2025-10-26 HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 1,
  "surge_dates": [
    {
      "date": "2025-10-26",
      "phq_attendance_sum": 1
    }
  ]
}

OpenAPI Spec

The OpenAPI spec for Demand Surge API can be found here.

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())