Get Predicted Impact Area

Determine the area around a location where events are likely to influence demand.

Most teams start with a fixed radius when scoping events around a location. The problem is that the distance over which events influence demand varies - by industry, by location type, and by how people actually move in that area. A radius that works in one market will miss impact or introduce noise in another.

Predicted Impact Area returns a location and industry-specific boundary that reflects where event-driven demand impact actually occurs. Boundaries are calibrated against real demand and event data across industries and geographies.

Use it as the spatial input for Events API queries, Features API calls, and Beam. Getting scope right at this step improves the quality of everything downstream.

Predicted Impact Area is the successor to the Suggested Radius API. It provides a more accurate representation of event impact than a radius-based approach.

Using Predicted Impact Area

The recommended approach is to use Saved Locations. When you create a location using origin_geojson without specifying a geojson area, Predicted Impact Area is calculated automatically and stored against that location. You can then use the location_id across all PredictHQ APIs - Events, Features, and Beam - without needing to manage the boundary yourself.

Polygon-based filtering across PredictHQ APIs requires a saved location. To use a Predicted Impact Area boundary in API queries, create a saved location first and reference it by location_id.

Get Predicted Impact Area

get

Returns the Predicted Impact Area for a given location and industry as a GeoJSON feature.

Two response shapes are supported via area_type:

• polygon (default, recommended) — a GeoJSON Polygon or MultiPolygon that precisely follows the true boundaries of the impact area. This is the best practice as real impact areas are rarely circular.
• radius — a GeoJSON Point with a radius property defining a circular approximation. Supported but not recommended, as it sacrifices accuracy for simplicity.

The returned GeoJSON cannot be passed directly to the Events, Features, or Beam APIs. To query events or features within this area, create a Saved Location using origin_geojson — the Predicted Impact Area will be calculated and stored automatically, and the location_id can then be used across those APIs.

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

industrystring · enumOptional

The industry category of the business location.

Different industries have different event impact profiles, which affect the size and shape of the returned predicted impact area.

• accommodation — Accommodation providers, travel tech, and OTAs
• cpg — Consumer packaged goods companies
• tourism — Leisure, travel, and tourism businesses (e.g. Expedia, DMOs, travel platforms)
• marketing — Advertising and marketing services
• parking — Parking facility operators
• restaurants — Food and beverage businesses including restaurant groups
• retail — Non-food retail and retail tech
• transportation — On-demand transport and delivery
• other — All other industries

Default: otherPossible values:

location.originstringRequired

A comma-separated string consisting of the latitude and longitude of the location to find the optimal area for. For example your store or hotel location.

The format is <latitude>,<longitude>

E.g. ?location.origin=37.747767,-122.455320

Example: 37.7749,-122.4194Pattern: ^-?\d{1,3}(?:\.\d+)?,\-?\d{1,3}(?:\.\d+)?$

area_typestring · enumOptional

The shape used to represent the returned impact area.

Default: polygonPossible values:

radius_unitstring · enumOptional

The unit of the radius returned.

This will be the unit specified in the radius_unit parameter in the call made.

• m — Meters
• km — Kilometers
• ft — Feet
• mi — Miles

Default: mPossible values:

Responses

200

Successful Response

application/json

warningsstring[]Optional

Warnings about the response

400

Validation Error

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

429

Rate limit exceeded. See Rate Limiting for details on limits and retry guidance.

application/json

get/v1/impact-area/

HTTPcURLJavaScriptPython

GET /v1/impact-area/?location.origin=37.7749%2C-122.4194 HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "geojson": {
    "type": "Feature",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -122.4194,
            37.7649
          ],
          [
            -122.4095,
            37.7649
          ],
          [
            -122.4035,
            37.771
          ],
          [
            -122.4095,
            37.781
          ],
          [
            -122.4194,
            37.781
          ],
          [
            -122.4254,
            37.771
          ],
          [
            -122.4194,
            37.7649
          ]
        ]
      ]
    }
  },
  "location": {
    "lat": "37.7749",
    "lon": "-122.4194"
  },
  "warnings": []
}

Examples

curl

curl -X GET "https://api.predicthq.com/v1/impact-area/?location.origin=37.747767,-122.455320&industry=parking" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $API_TOKEN"

python

OpenAPI Spec

The OpenAPI spec for Impact Area API can be found here.