Get a Saved Location

Get an existing Saved Location.

Get a Saved Location

get

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.

Authorizations

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

Path parameters

location_idstringRequired

An existing Saved Location ID.

Responses

200

Successful Response

application/json

A Saved Location record including geographic data, summary insights, and enrichment status.

place_idsinteger[]Optional

An array of place ids (see the Places API) for locations that are defined as covering an area (see City, State, Country locations) rather than a point and radius.

E.g. [2750405]

Example: [2750405]

industrystring · enumOptional

The industry of your business.

Possible values:

location_codestringOptional

The user-supplied identifier for the location.

E.g. 4t855453234t5623

Example: 4t855453234t5623

namestringOptional

The user defined name of the Saved Location set in the create location call.

E.g. My Parking Building

Example: My Parking Building

descriptionstringOptional

A user-supplied description of the location.

labelsstring[]Optional

A list of user defined labels for the location.

E.g.: ["test", "retail"]

Example: test

formatted_addressstringOptional

The address of the location. This can be supplied when creating a location.

E.g.

  {
    "formatted_address": "666 Mission St, San Francisco, CA 94105, USA",
  }

Example: 666 Mission St, San Francisco, CA 94105, USA

create_dtstring · date-timeRequired

The creation date time for the location in ISO 8601 format.

E.g. 2022-04-26T11:46:24+00:00

Example: 2022-04-26T11:46:24+00:00

update_dtstring · date-timeRequired

The last update date time for the location in ISO 8601 format.

E.g. 2022-04-26T11:46:24+00:00

Example: 2022-04-26T11:46:24+00:00

enrich_dtstring · date-timeOptional

The date time the location was last enriched in ISO 8601 format.

E.g. 2022-04-26T11:46:25+00:00

Example: 2022-04-26T11:46:25+00:00

insights_dtstring · date-timeOptional

The date/time insights were last calculated for the location in ISO 8601 format.

E.g. 2022-04-26T11:46:25+00:00

Example: 2022-04-26T11:46:25+00:00

user_idstringOptional

The ID of the user who created the saved location. This is present for locations created in the WebApp. For locations created via the API this field will not be populated.

E.g. hjqkKozgS8mm

Example: hjqkKozgS8mm

location_typestring · enumOptional

The type of geographic definition used for this location. Possible values are place_id, point, polygon, or impact_area.

Possible values:

statusstring · enumRequired

Reflects if a location has been updated by the enrichment process. When a location is initially created its status will be pending.

After the enrichment process has updated the location populating summary_insights and other fields the status will be active.

Typically locations only have the pending status for a short time.

E.g. active

Example: activePossible values:

location_idstringRequired

The autogenerated identifier for the saved location.

E.g. 8gZ2rn8BRcTjM_3SWdjP

Example: 8gZ2rn8BRcTjM_3SWdjP

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

get/v1/saved-locations/{location_id}

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

{
  "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/_4Dl3p4Q2zl4ifMjG4Z3ew' \
--header 'Authorization: Bearer TOKEN'

python

import requests

url = "https://api.predicthq.com/v1/saved-locations/_4Dl3p4Q2zl4ifMjG4Z3ew"
headers = {
  'Authorization': 'Bearer TOKEN'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

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