# Get Suggested Radius

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.

{% hint style="success" %}
[Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-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.
{% endhint %}

## Get Suggested Radius

> Returns a suggested radius for the given location and industry.

````json
{"openapi":"3.1.0","info":{"title":"PredictHQ Suggested Radius API","version":"1.0.0"},"tags":[{"name":"Suggested Radius 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":{"RadiusUnit":{"description":"The unit of the radius returned.\n\nThis will be the unit specified in the radius_unit parameter in the call made.","type":"string","enum":["m","km","ft","mi"],"title":"RadiusUnit"},"Industry":{"type":"string","enum":["parking","restaurants","retail","accommodation","cpg","tourism","marketing","transportation","other"],"title":"Industry"},"SuggestedRadiusResponse":{"description":"Response model for the backwards-compatible Suggested Radius API.","type":"object","properties":{"radius":{"description":"The suggested radius for a given location rounded to 2 decimal places.","type":"number","title":"Radius"},"radius_unit":{"description":"The unit of measurement for the radius","$ref":"#/components/schemas/RadiusUnit"},"location":{"description":"Origin location","$ref":"#/components/schemas/LocationResponse"}},"required":["radius","radius_unit","location"],"title":"SuggestedRadiusResponse"},"LocationResponse":{"description":"A json object representing the geo location of the event.\n\n\nE.g.:\n```json\n{\n  \"lat\": \"37.747767\",\n  \"lon\": \"-122.455320\"\n}\n```","type":"object","properties":{"lat":{"description":"Latitude of the location","type":"string","title":"Lat"},"lon":{"description":"Longitude of the location","type":"string","title":"Lon"}},"required":["lat","lon"],"title":"Location"},"HTTPValidationError":{"type":"object","properties":{"error":{"description":"Error summary message","type":"string","title":"Error"},"details":{"description":"List of validation error details","type":"array","items":{"$ref":"#/components/schemas/ValidationErrorDetail"},"title":"Details"}},"required":["error","details"],"title":"HTTPValidationError"},"ValidationErrorDetail":{"type":"object","properties":{"field":{"description":"The field that failed validation","type":"string","title":"Field"},"msg":{"description":"The validation error message","type":"string","title":"Message"},"type":{"description":"The type of validation error","type":"string","title":"Error Type"}},"required":["field","msg","type"],"title":"ValidationErrorDetail"},"ErrorResponse":{"type":"object","properties":{"error":{"description":"Error message","type":"string","title":"Error"}},"required":["error"],"title":"ErrorResponse"}}},"paths":{"/v1/suggested-radius/":{"get":{"operationId":"get_suggested_radius","summary":"Get Suggested Radius","description":"Returns a suggested radius for the given location and industry.","parameters":[{"name":"radius_unit","in":"query","description":"Unit in which the suggested radius will be returned.\nThe default unit is m\n\nPossible values:\n- `m` - meters (default)\n- `km` - kilometers\n- `ft` - feet\n- `mi` - miles\n\n\nE.g. `?radius_unit=km`","required":false,"schema":{"default":"m","$ref":"#/components/schemas/RadiusUnit"}},{"name":"industry","in":"query","description":"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.\n\n\nE.g. `?industry=accommodation`","required":false,"schema":{"default":"other","$ref":"#/components/schemas/Industry"}},{"name":"location.origin","in":"query","description":"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.\n\n\nThe format is `<latitude>,<longitude>`\n\n\nE.g. `?location.origin=37.747767,-122.455320`","required":true,"schema":{"type":"string","pattern":"^-?\\d{1,3}(?:\\.\\d+)?,\\-?\\d{1,3}(?:\\.\\d+)?$"},"explode":false,"style":"form"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestedRadiusResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Suggested Radius API"]}}}}
````

## Examples

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

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

{% endtab %}

{% tab title="python" %}

```python
import requests

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

print(response.json())
```

{% endtab %}
{% endtabs %}

## OpenAPI Spec

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

## Guides

Below are some guides relevant to this API:

* [Find Events by Latitude/Longitude and Radius](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-latitude-longitude-and-radius)