Search Saved Locations

Search for existing Saved Locations.

Search Saved Locations

get

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.

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

qstringOptional

A full-text search query that searches across the following fields:

• name
• description
• location_code
• formatted_address
• labels

E.g. q=alabama

offsetintegerOptional

Offset the results.

Default: 0

limitintegerOptional

Limit the number of results.

Default: 10

location_idstring[] · max: 100Optional

A comma-separated string consisting of a list of 1 or more location_id's.

E.g. ?location_id=6TxvEapQeDzq9y_UKVRQCQ

Responses

200

Successful Response

application/json

A paginated list of Saved Location records.

countintegerRequired

Total number of results found.

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

get/v1/saved-locations

HTTPcURLJavaScriptPython

GET /v1/saved-locations HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 1,
  "locations": [
    {
      "location_id": "7sdevIveOuIQmP0EL1lZoQ",
      "create_dt": "2025-11-17T19:11:43+00:00",
      "update_dt": "2025-11-17T19:11:43+00:00",
      "enrich_dt": "2025-11-17T19:11:45+00:00",
      "insights_dt": "2025-11-17T19:11:46+00:00",
      "name": "San Francisco",
      "place_ids": [
        5391959
      ],
      "formatted_address": "San Francisco, San Francisco County, California, United States [Locality]",
      "places": [
        {
          "place_id": 5391959,
          "type": "locality",
          "name": "San Francisco",
          "county": "San Francisco County",
          "region": "California",
          "country": "US",
          "geojson": {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                -122.41942,
                37.77493
              ]
            }
          }
        }
      ],
      "summary_insights": [
        {
          "date_range": {
            "type": "next_90d",
            "start_dt": "2025-11-17T19:11:46+00:00",
            "end_dt": "2026-02-15T19:11:46+00:00"
          },
          "phq_attendance_sum": 2670581,
          "attended_event_count": 2568,
          "non_attended_event_count": 113,
          "unscheduled_event_count": 2,
          "pes_total_sum": 232505682,
          "pes_accommodation_sum": 88335769,
          "pes_hospitality_sum": 108671383,
          "pes_transportation_sum": 35496672
        }
      ],
      "subscription_valid_types": [
        "events",
        "features_api"
      ],
      "status": "active"
    }
  ]
}

Examples

curl

curl --location 'https://api.predicthq.com/v1/saved-locations?q=alabama&limit=50' \
--header 'Authorization: Bearer TOKEN'

python

OpenAPI Spec

The OpenAPI spec for Saved Locations API can be found here.

Guides

Below are some guides relevant to this API:

• Working with Location-Based Subscriptions