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

Request

HTTP Request

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

Query Parameters

Parameter Description

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`

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

Response

Response Fields

Field Description

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.

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

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",
        "date_to": "2021-08-10",
        "min_surge_intensity": "m",
        "location.place_id": "2643743"
    }
)

print(response.json())

PreviousDemand Surge NextSuggested Radius

Last updated 9 months ago