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 that can be used to find events around a given location. When looking for events around a business location (such as a store, a hotel, or another business location) a key question is how far should you look for events. For example, should you look at events in a 0.5-mile radius, a 2-mile radius, or a 10-mile radius from your location? The Suggested Radius API answers this question by returning a radius based on a number of factors that can be used to retrieve events around a location. This radius returned by the API is commonly used as follows:

• When querying the Events API using the within parameter.

• When calling the Features API with a latitude, longitude, and radius to get aggregated features back for a location.

• For retrieving events in a data lake by setting the radius around a store or location to the suggested radius.

• In-demand forecasting when building event-based features for a location, use this radius when calculating features for a location.

• For use with our Beam product when performing a correlation analysis

The Suggested Radius API is powered by a machine learning model that looks at factors like population density, the events around a location, the customer’s industry, and many other factors to determine the ideal radius.

We'd suggest caching the Suggested Radius API response where possible. The response will only change infrequently and it would be sufficient to refresh the cache once per month.

Get Suggested Radius

get

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

radius_unitstring · enumOptional

The unit of the radius returned. This will be the unit specified in the radius_unit parameter in the call made.

Default: mPossible values:

industrystring · enumOptional

The industry of interest for which the radius will be calculated. For different industries, the radii will be different based on the various types of events that would impact the location. For example, if you were getting the suggested radius around a hotel you’d specify accommodation as the industry.

E.g. ?industry=accommodation

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

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

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/v1/suggested-radius/

HTTPcURLJavaScriptPython

GET /v1/suggested-radius/?location.origin=text HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "radius": 1,
  "radius_unit": "m",
  "location": {
    "lat": "text",
    "lon": "text"
  }
}

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

python

OpenAPI Spec

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

Guides

Below are some guides relevant to this API:

• Find Events by Latitude/Longitude and Radius