# Get Demand Surges

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](https://docs.predicthq.com/api/events/search-events) to find the names, descriptions, locations, and other details of the events that constitute the surges.
* Our [Features API](https://docs.predicthq.com/api/features/get-features) to get Machine Learning features for events in your searched date range.

## GET /v1/demand-surge/

> Get Demand Surges

```json
{"openapi":"3.1.0","info":{"title":"PredictHQ Demand Surge API","version":"1.0.0"},"tags":[{"name":"Demand Surge API"}],"servers":[{"url":"https://api.predicthq.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"$API_KEY","description":"Enter your PredictHQ API key. The Bearer prefix is added automatically.\n\nWhen calling the API directly, send: `Authorization: Bearer <YOUR_API_KEY>` as documented at [https://docs.predicthq.com/api/overview/authenticating](https://docs.predicthq.com/api/overview/authenticating)\n"}},"schemas":{"SizeEnum":{"type":"string","enum":["s","m","l","xl"],"title":"SizeEnum"},"DemandSurgeResponse":{"type":"object","properties":{"count":{"description":"The number of identified demand surges given the search criteria.","type":"integer","title":"Count"},"surge_dates":{"description":"An array of identified demand surges.","type":"array","items":{"$ref":"#/components/schemas/SurgeDate"},"title":"Surge Dates"}},"required":["count"],"title":"DemandSurgeResponse"},"SurgeDate":{"type":"object","properties":{"date":{"description":"The date of the identified demand surge.","type":"string","format":"date","title":"Date"},"phq_attendance_sum":{"description":"The sum of all attendance based features in the identified demand surge.","type":"integer","title":"Phq Attendance Sum"}},"required":["date","phq_attendance_sum"],"title":"SurgeDate"},"HTTPValidationError":{"type":"object","properties":{"detail":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail"}},"title":"HTTPValidationError"},"ValidationError":{"type":"object","properties":{"loc":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/demand-surge/":{"get":{"operationId":"get_demand_surge_demand_surge_get","summary":"Get Demand Surges","parameters":[{"name":"min_surge_intensity","in":"query","description":"Filters out demand surges smaller than the minimum surge intensity provided.\n\n\nE.g. `?min_surge_intensity=m`","required":true,"schema":{"$ref":"#/components/schemas/SizeEnum"}},{"name":"date_from","in":"query","description":"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.\n\n\nThe accepted format for this parameter is `YYYY-MM-DD`\n\n\nE.g. `?date_from=2021-05-12`","required":true,"schema":{"type":"string","format":"date","title":"Date From"}},{"name":"location.place_id","in":"query","description":"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.\n\n\nE.g. `?location.place_id=2643743,2643744`","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Location.Place Id"},"explode":false,"style":"form"},{"name":"location.origin","in":"query","description":"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`.\n\n\nE.g. `?location.origin=40.7128,74.0060`","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Location.Origin"},"explode":false,"style":"form"},{"name":"location.radius","in":"query","description":"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:\n- `m` - meters\n- `km` - kilometers\n- `ft` - feet\n- `mi` - miles\n\n\nE.g. `?location.radius=100mi`","required":false,"schema":{"type":"string","title":"Location.Radius"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemandSurgeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["Demand Surge API"]}}}}
```

## OpenAPI Spec

The OpenAPI spec for Demand Surge API can be [found here](https://api.predicthq.com/docs/?urls.primaryName=Demand+Surge+API).

## Examples

{% tabs %}
{% tab title="curl" %}

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

{% endtab %}

{% tab title="python" %}

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

{% endtab %}
{% endtabs %}