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

AuthorizationstringRequired

Enter your PredictHQ API key. The Bearer prefix is added automatically.

When calling the API directly, send: Authorization: Bearer <YOUR_API_KEY> as documented at https://docs.predicthq.com/api/overview/authenticating

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

location.originstring[]Optional

A comma-separated coordinate (<lat>,<lon>) representing the centroid of a location. It must be used with location.radius and cannot be used with location.place_id.

E.g. ?location.origin=40.7128,74.0060

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=2026-02-03 HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 1,
  "surge_dates": [
    {
      "date": "2026-02-03",
      "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