Suggested Radius API

The Suggested Radius API returns a radius that can be used to find attended 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.

Search Suggested Radius

Use the parameters described below to find the suggested radius for your case.

Query Parameters

Field Description
location.origin
geopoint		 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.
E.g. ?location.origin=37.747767,-122.455320
radius_unit
string		 Unit in which the suggested radius will be returned.
The default unit is m
Possible values:
  • m - meters (default)
  • km - kilometers
  • ft - feet
  • mi - miles
E.g. ?radius_unit=km
industry
string		 The industry of interest that the radius will be calculated for. For different industries, the radii will be different based on the different 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.
The default industry is other
Possible values:
  • parking
  • restaurants
  • retail
  • accommodation
  • other(default)
E.g. ?industry=accommodation

Action

raw
GET /v1/suggested-radius/

Example

curlpythonraw
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"
json
{
    "radius": 1.46,
    "radius_unit": "km",
    "location": {
        "lat": "37.747767",
        "lon": "-122.45532"
    }
}

Suggested Radius Fields

Below are the fields returned by the Suggested Radius endpoint. Please note that these are not the fields used for searching - please refer to the Search Suggested Radius section to discover which parameters can be used calling the Suggested Radius API.

Field Description
radius
float
read-only		 The suggested radius for a given location rounded to 2 decimal places.
radius_unit
string
read-only		 The unit of the radius returned. This will be the unit specified in the industry parameter in the call made.
location
object
read-only		 A json object representing the geo location of the event.
E.g. {"lat": 37.747767,"lon": -122.455320}