Get Suggested Radius

Take the guesswork out of working out a suitable radius around your business when searching for events.

The Suggested Radius API returns a radius for finding events around a business location. Rather than guessing an appropriate distance, the API calculates a radius based on factors including population density, local event patterns, and industry.

Use the returned radius as the spatial input for Events API queries, Features API calls, Beam, and demand forecasting workflows.

We recommend caching the response and refreshing monthly - the radius for a given location changes infrequently.

Predicted Impact Area is the successor to this API, providing a more accurate representation of event impact than a radius. Suggested Radius remains available and existing implementations are unaffected.

Deprecated

Get Suggested Radius

get

Deprecated: Use the Predicted Impact Area API instead, which provides a more accurate polygon representation of event impact rather than a simple radius.

Returns a suggested radius for the given location and industry.

Authorizations

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

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:

industrystring · enumOptional

The industry category of the business location.

Different industries have different event impact profiles, which affect the returned suggested radius.

• 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 radius 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+)?$

Responses

200

Successful Response

application/json

Response model for the backwards-compatible Suggested Radius API.

radiusnumberRequired

The suggested radius for a given location rounded to 2 decimal places.

radius_unitstring · enumRequired

The unit of measurement for the radius

Possible values:

400

Validation Error

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

get/v1/suggested-radius/

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

{
  "radius": 1500,
  "radius_unit": "m",
  "location": {
    "lat": "37.7749",
    "lon": "-122.4194"
  }
}

Examples

curl

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

python

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/suggested-radius/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "location.origin": "37.747767,-122.455320",
        "industry": "parking",
        "radius_unit": "km"
    }
)

print(response.json())

OpenAPI Spec

The OpenAPI spec for Suggested Radius API can be found here.

Guides

Below are some guides relevant to this API:

• Create a Saved Location

• Get Predicted Impact Area