PredictHQ

Delete an existing Analysis. The Analysis will no longer appear in default search results, but can still be retrieved by filtering with `status=deleted`. Any Analysis Groups containing this Analysis will be automatically refreshed.

beam_api_delete_analysis

Delete an existing Analysis Group. The individual Analyses within the group are not deleted.

beam_api_delete_analysis_group

Permanently deletes a forecast model and all associated demand data and forecasts. The model must not be in `preparing`, `training`, or `forecasting` status. This action is irreversible.

forecasts_api_delete_model

Permanently delete a saved location by ID. This action is irreversible — the location and all associated insights data will be removed.

saved_locations_api_delete_saved_location

Deletes a closure by ID for the specified location.

saved_locations_api_delete_closure

Deletes an opening hours record by ID for the specified location.

saved_locations_api_delete_opening_hours

Returns the full details of a single Analysis, including its location, demand type, rank, readiness status, and processing state.

beam_api_get_analysis

Retrieve results of the correlation of our event data with your transactional demand data.

beam_api_get_analysis_correlation

This endpoint provides the relevant ML features (based on feature importance testing) that are shown to impact the demand for the Beam Analysis. These are the features you should take into your forecasting model to improve your model accuracy. These values represent each group of features' statistical significance when it comes to impacting observable incremental/decremental changes in demand. The easiest way to get these ML features from our Features API to be used in your models is by using the Beam `analysis_id` in your Features API request.

beam_api_get_analysis_feature_importance

Returns the full details of a single Analysis Group, including its member analyses, demand type, readiness status, and processing state.

beam_api_get_analysis_group

This endpoint provides Feature Importance results aggregated across the Analyses in an existing Analysis Group, and returns a list of feature groups with associated Features API features and group p-values.

beam_api_get_analysis_group_feature_importance

Get a specific page from PredictHQ's technical documentation. Use this tool to retrieve the full content of a specific documentation page when you already know the exact URL. Always obtain URLs from docs_search results — do NOT guess or construct URLs from patterns, as documentation page paths do not follow a predictable naming convention and guessed URLs will return "Page not found" errors. Correct workflow: 1. Call docs_search to find relevant pages and get their exact URLs. 2. Call docs_get_page with a URL returned by docs_search.

docs_get_page

Get a single event by ID with full details including geometry. Use this when you need the complete event record for a specific event — including full Polygon/MultiPolygon geometry that is omitted from list_events results. Prefer list_events for discovery and get_event for detail retrieval.

events_api_get_event

Returns aggregated ML-ready features for the specified location and date range. Returns pre-built ML-ready features for the specified location and date range, aggregated per day or per week. Features are opt-in: only features included in the request body are returned. **Beam (recommended):** Provide a `beam` object with an `analysis_id` to automatically derive location, interval, and feature selection from a Beam analysis. This is the recommended approach. When `beam.analysis_id` is provided, you must not specify `location`, `interval`, or individual features separately — these are determined by the analysis and the request will be rejected if they are included. **Manual configuration:** If not using Beam, location must be specified via `location.geo` (lat/lon + radius), `location.place_id`, or `location.saved_location_id`, and features must be explicitly requested. **Feature families:** `phq_attendance_*`, `phq_impact_*`, `phq_spend_*`, and `phq_viewership_*` features return statistical summaries (`count`, `sum`, `min`, `max`, `avg`, `median`, `std_dev`) — pass `true` for defaults (`count` and `sum`), or a criteria object to customise stats and filter by `phq_rank` or `local_rank`. `phq_rank_*` features return a `rank_levels` object (counts bucketed into 5 severity levels) and are requested by setting the field to `true`. **Date range** (`active`) is required in all cases and uses local time. Multi-day occurrences are included for each day they are active within the range. Results are paginated with `offset` and `limit`, and can be returned as JSON or CSV via the `Accept` header.

features_api_get_features

Returns the generated forecast results for a trained model. Each result includes a date and predicted demand value. Supports filtering by date range.

forecasts_api_get_forecast

Retrieves a single forecast model by ID, including its current readiness status, configuration, accuracy metrics, and location details.

forecasts_api_get_model

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.

impact_area_api_get_impact_area

Get full details for a Google Place using a Google Place ID previously retrieved from autocomplete_places. Returns the Google Place formatted address, coordinates, and additional details. Only call this when you have a google_place_id from a prior autocomplete_places call. Do not guess or construct Google Place IDs. Use when you need full place details beyond what autocomplete returned, or when you need to confirm the exact coordinates before creating a Saved Location.

geocode_api_get_place

Retrieve full details for a single Saved Location by ID. Response includes the `geojson` field (which stores the Predicted Impact Area boundary), `origin_geojson` (exact business point), `industry`, `labels`, `formatted_address`, and `summary_insights` — which contain attended/non-attended event counts, PHQ attendance sum, and Predicted Event Spend metrics for the next 90-day window. The `status` field reflects enrichment state: `pending` means the Predicted Impact Area and `summary_insights` are still being calculated (typically resolves within seconds); `active` means the location is fully enriched and ready to use.

saved_locations_api_get_saved_location

Returns a single closure by ID for the specified location.

saved_locations_api_get_closure

Returns a single opening hours record by ID for the specified location.

saved_locations_api_get_opening_hours

Get the authenticated user's subscription details, including visibility window and covered places.

auth_get_subscription

Returns a paginated list of your Beam Analyses. Supports filtering by `status`, `readiness_status`, `industry`, `interval`, `label`, and date range. Note: Polygon and MultiPolygon geometry is omitted from results to reduce token usage. To retrieve full geometry for a specific analysis, call the `get_analysis` tool.

beam_api_list_analyses

Returns a paginated list of your Analysis Groups. Supports filtering by `status`, `readiness_status`, `industry`, `interval`, and date range.

beam_api_list_analysis_groups

Returns a paginated list of broadcast records matching the given filters. Broadcasts represent scheduled or predicted Live TV events at the county level in the US. Use date range filters (`start.*`, `updated.*`, `first_seen.*`) to narrow results by time, `location.place_id` or `location.origin` to filter by geography, and `event.*` filters to find broadcasts linked to specific physical events. Results are sorted by `start` ascending by default. Use the `sort` parameter to change ordering. Pagination is offset-based.

broadcasts_api_list_broadcasts

Search for events happening in a location and date range. Use our extensive filters to narrow down your results. Note: Polygon and MultiPolygon geometry is omitted from results to reduce token usage. To retrieve full geometry for a specific event, call the `get_event` tool.

events_api_list_events

Returns the list of available forecasting algorithms. Currently one algorithm is offered (`phq-xgboost`) based on XGBoost.

forecasts_api_list_algorithms

Returns the demand data that has been uploaded to the model. Supports filtering by date range. By setting the `Accept` header, you can specify the format of the response. The default is JSON. Supported formats: `application/json`, `text/csv`, `application/x-ndjson`.

forecasts_api_list_demand_data

Returns a paginated list of forecast models belonging to the authenticated organization. Supports full-text search across `name`, `label`, and `external_id` via the `q` parameter, and filtering by Saved Location ID and readiness status.

forecasts_api_list_models

Return the administrative hierarchy chain for one or more places. Exactly one of `location.place_id` or `location.origin` must be provided — supplying both or neither returns `400`. **By place ID** (`location.place_id`): Returns stored hierarchies for the given place IDs. Results are paginated over the matched places. The `country` filter is not applied in this mode. **By coordinates** (`location.origin`): Finds the nearest locality to the given `lat,lon` and returns its hierarchy chain. - When `level` is `region` or above (`planet`, `continent`, `country`, `region`), only nearby localities are considered. - When `level` is more granular than `region` (`county`, `localadmin`, `locality`, `neighbourhood`) or not specified, the search is extended to include major and metro areas within the same region as the nearest locality. - If no locality is found at the exact coordinates, a **500 km fallback radius** is applied before giving up. - Use `country` (comma-separated ISO 3166-1 alpha-2 codes) to restrict the coordinate lookup to specific countries. Use `level` to scope which hierarchy levels are returned. Results are paginated with `offset` and `limit`.

places_api_list_place_hierarchies

Search for places by text query, country, geographic coordinates, or place IDs. At least one of `q`, `country`, `location`, or `id` must be provided — otherwise a `400` is returned. **Filtering:** - `q` — free-text search on place name. - `country` — comma-separated ISO 3166-1 alpha-2 country codes. - `location` — coordinates in `lat,lon` or `@lat,lon` format. Lat must be between −90 and 90, lon between −180 and 180. - `id` — comma-separated place IDs. When `id` is the only filter and no pagination parameters are set, an optimised multi-get is used instead of a search query. - `type` — comma-separated place types. Accepts admin level values as well as aliases (e.g. `local` expands to `neighbourhood`, `locality`, and `localadmin`). Results are paginated with `offset` and `limit`.

places_api_list_places

Returns a paginated list of closures for a location. Optionally filter by date range using `active_from` and `active_to`.

saved_locations_api_list_closures

Returns events that impact the specified Saved Location. Please refer to the [Events API](https://docs.predicthq.com/api/events/search-events) docs for the available query parameters in addition to those listed below.

saved_locations_api_list_saved_location_insight_events

Returns a paginated list of opening hours records for a location. Optionally filter by date range using `active_from` and `active_to`.

saved_locations_api_list_opening_hours

Search and list Saved Locations. Supports full-text search across `name`, `description`, `location_code`, `formatted_address`, and `labels` via the `q` parameter. Saved Locations are standalone geographic entities that exist independently of any other PredictHQ product. Creating a Saved Location does not create a Beam Analysis — those must be created separately. The returned `location_id` values can be passed directly to the Events API, Features API, and Beam API without needing to supply coordinates each time. Note: Polygon and MultiPolygon geometry is omitted from results to reduce token usage. To retrieve full geometry for a specific saved location, call the `get_saved_location` tool.

saved_locations_api_list_saved_locations

Update one or more fields on an existing Analysis without replacing the entire record. Only the fields you provide will be updated; all other fields remain unchanged.

beam_api_patch_analysis

Partially update an existing Analysis Group. This endpoint accepts the same request body fields as the Create an Analysis Group endpoint. Remember this is a PATCH endpoint which means only the fields you provide will be updated. If you wish to replace all fields please use the PUT endpoint.

beam_api_patch_analysis_group

Partially updates an existing forecast model. Only the fields provided in the request body will be changed. Changes to `location`, `demand_type`, `forecast_window`, `algo`, or `generate_baseline` are blocked while the model is in `preparing`, `training`, or `forecasting` status. Changing any of those fields sets the model to `stale` status, requiring re-training to take effect.

forecasts_api_patch_model

Rerun the Beam correlation and analysis process for an existing Analysis. The `readiness_status` will be set to `pending` until processing completes. Returns 400 if the Analysis is already being processed.

beam_api_refresh_analysis

Rerun the Beam Analysis Group aggregation process. The `readiness_status` will be set to `pending` until processing completes. Returns 400 if the Group is already being processed.

beam_api_refresh_analysis_group