Get a Saved Location

Get an existing Saved Location.

Get a Saved Location

get

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

Path parameters

location_idstringRequired

An existing Saved Location ID.

Responses

200

Successful Response

application/json

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

labelsstring[]Optional

A list of user defined labels for the location.

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

Example: test

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]

formatted_addressstringOptional

The address of the location. This can be supplied when created a location. If it's not supplied it will be populated by a reverse geocode.

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

user_idstringOptional

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

E.g. hjqkKozgS8mm

Example: hjqkKozgS8mm

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

422

Validation Error

application/json

get

/v1/saved-locations/{location_id}

HTTPcURLJavaScriptPython

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

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