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
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
get
GET /v1/demand-surge/?min_surge_intensity=s&date_from=2025-10-08 HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "count": 1,
  "surge_dates": [
    {
      "date": "2025-10-08",
      "phq_attendance_sum": 1
    }
  ]
}

OpenAPI Spec

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

Examples

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"

Last updated

Was this helpful?