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.

Request

HTTP Request

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

Query Parameters

ParameterDescription

date_from date

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

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

The location to use in the demand surge search window. Supports place_idOR origin and radius suffixes.

  • place_id: 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

  • origin: A 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: 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

Response

Response Fields

FieldDescription

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&min_surge_intensity=m&location.place_id=2643743 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

Last updated

© 2024 PredictHQ Ltd