# Get a Saved Location

## Get a Saved Location

> 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.

````json
{"openapi":"3.1.0","info":{"title":"PredictHQ Saved Locations API","version":"1.0.0"},"tags":[{"name":"Saved Locations 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":{"SavedLocationResponse":{"description":"A Saved Location record including geographic data, summary insights, and enrichment status.","type":"object","properties":{"location_code":{"description":"The user-supplied identifier for the location.\n\n\nE.g. `4t855453234t5623`","type":"string","title":"Location Code"},"name":{"description":"The user defined name of the Saved Location set in the create location call.\n\n\nE.g. `My Parking Building`","type":"string","title":"Name"},"description":{"description":"A user-supplied description of the location.","type":"string","title":"Description"},"labels":{"description":"A list of user defined labels for the location.\n\n\nE.g.: `[\"test\", \"retail\"]`","type":"array","items":{"type":"string"},"title":"Labels"},"geojson":{"description":"An object containing the geographic information about a location. Represents the geometry associated with the event in the [GeoJSON format](https://geojson.org/).","$ref":"#/components/schemas/GeoJson-Output"},"place_ids":{"description":"An array of place ids (see the [Places API](https://docs.predicthq.com/api/places/search-places)) for locations that are defined as covering an area (see City, State, Country locations) rather than a point and radius.\n\n\nE.g. `[2750405]`","type":"array","items":{"type":"integer"},"title":"Place Ids"},"formatted_address":{"description":"The address of the location. This can be supplied when creating a location.\n\n\nE.g.\n  ```json\n    {\n      \"formatted_address\": \"666 Mission St, San Francisco, CA 94105, USA\",\n    }\n  ```","type":"string","title":"Formatted Address"},"industry":{"description":"The industry of your business.","$ref":"#/components/schemas/Industry"},"origin_geojson":{"description":"An object containing the geographic information about a location. Represents the location of your business\nin the [GeoJSON format](https://geojson.org/).","$ref":"#/components/schemas/OriginGeoJson"},"create_dt":{"description":"The creation date time for the location in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).\n\n\nE.g. `2022-04-26T11:46:24+00:00`","type":"string","format":"date-time","title":"Create Dt"},"update_dt":{"description":"The last update date time for the location in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).\n\n\nE.g. `2022-04-26T11:46:24+00:00`","type":"string","format":"date-time","title":"Update Dt"},"enrich_dt":{"description":"The date time the location was last enriched in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).\n\n\nE.g. `2022-04-26T11:46:25+00:00`","type":"string","format":"date-time","title":"Enrich Dt"},"insights_dt":{"description":"The date/time insights were last calculated for the location in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).\n\n\nE.g. `2022-04-26T11:46:25+00:00`","type":"string","format":"date-time","title":"Insights Dt"},"user_id":{"description":"The ID of the user who created the saved location.\nThis is present for locations created in the WebApp.\nFor locations created via the API this field will not be populated.\n\n\nE.g. `hjqkKozgS8mm`","type":"string","title":"User Id"},"subscription_valid_types":{"description":"The value is a list of different (subscription) types that this location is valid for.\nThe possible values are `events`, `broadcasts`, `notifications`, `features_api`.\n\n\nIt is possible to create locations outside of what your subscription has access to.\nIn this case this field will be empty and you will not be able to view events for the location.\n\n\nE.g. `[\"events\"]`","type":"array","items":{"$ref":"#/components/schemas/SubscriptionValidType"},"title":"Subscription Valid Types"},"location_type":{"description":"The type of geographic definition used for this location. Possible values are `place_id`, `point`, `polygon`, or `impact_area`.","$ref":"#/components/schemas/LocationType"},"status":{"description":"Reflects if a location has been updated by the enrichment process. When a location is initially created its status will be `pending`.\n\n\nAfter the enrichment process has updated the location populating `summary_insights` and other fields the status will be `active`.\n\n\nTypically locations only have the `pending` status for a short time.\n\n\nE.g. `active`","$ref":"#/components/schemas/SavedLocationStatus"},"summary_insights":{"description":"This object contains the saved locations stats.\nThis includes values for each of the 4 stats as well as the date_range field.\nThe stats reflect the number of events and attend happening for the location.\n\nThe date range field includes the start and end datetime for the period that the stats have been calculated for.","type":"array","items":{"$ref":"#/components/schemas/SummaryInsights"},"title":"Summary Insights"},"places":{"description":"This is a list of (geonames) Places. It is based on the lowest level place_id in the [place_hierarchies](https://docs.predicthq.com/getting-started/guides/geolocation-guides/understanding-place-hierarchies). It will usually only contain 1 item in the list but will always be a list.","type":"array","items":{"$ref":"#/components/schemas/Place"},"title":"Places"},"location_id":{"description":"The autogenerated identifier for the saved location.\n\n\nE.g. `8gZ2rn8BRcTjM_3SWdjP`","type":"string","title":"Location Id"},"additional_details":{"description":"Contains supplementary operational data for the location, including opening hours and closures that fall within a rolling window.","$ref":"#/components/schemas/AdditionalDetails"}},"required":["create_dt","update_dt","status","location_id"],"title":"SavedLocationResponse"},"GeoJson-Output":{"description":"A GeoJSON Feature representing the geographic area of a location as returned in responses.","type":"object","properties":{"type":{"description":"The GeoJSON object type. Always `Feature`.","type":"string","const":"Feature","title":"Type"},"properties":{"description":"Optional properties for the feature, such as radius and radius unit for Point geometries.","$ref":"#/components/schemas/Properties"},"geometry":{"description":"The geometry of the feature.","discriminator":{"propertyName":"type","mapping":{"LineString":"#/components/schemas/LineString","MultiLineString":"#/components/schemas/MultiLineString","MultiPolygon":"#/components/schemas/MultiPolygon","Point":"#/components/schemas/Point","Polygon":"#/components/schemas/Polygon"}},"oneOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"}],"title":"Geometry"}},"required":["type","geometry"],"title":"GeoJSON (Output)"},"Properties":{"description":"Custom properties for embedding the radius information","type":"object","properties":{"radius":{"description":"The radius around the Point geometry, defining the area of impact.","type":"number","title":"Radius"},"radius_unit":{"description":"The unit of measurement for the radius value.","$ref":"#/components/schemas/RadiusUnit"}},"title":"Properties"},"RadiusUnit":{"description":"The unit of the radius returned. This will be the unit specified in the radius_unit parameter in the call made.","type":"string","enum":["m","km","ft","mi"],"title":"RadiusUnit"},"Point":{"description":"A GeoJSON Point geometry. Coordinates are `[longitude, latitude]`.","type":"object","properties":{"type":{"description":"The geometry type. Always `Point`.","type":"string","default":"Point","const":"Point","title":"Type"},"coordinates":{"description":"The position as `[longitude, latitude]` or `[longitude, latitude, altitude]`.","anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":3,"minItems":3}],"title":"Coordinates"}},"required":["coordinates"],"title":"Point"},"Polygon":{"description":"A GeoJSON Polygon geometry. The first ring is the outer boundary; subsequent rings are holes.","type":"object","properties":{"type":{"description":"The geometry type. Always `Polygon`.","type":"string","default":"Polygon","const":"Polygon","title":"Type"},"coordinates":{"description":"An array of linear rings. Each ring is an array of `[longitude, latitude]` positions where the first and last positions are identical.","type":"array","items":{"items":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":3,"minItems":3}]},"type":"array"},"title":"Coordinates"}},"required":["coordinates"],"title":"Polygon"},"MultiPolygon":{"description":"A GeoJSON MultiPolygon geometry containing multiple Polygon geometries.","type":"object","properties":{"type":{"description":"The geometry type. Always `MultiPolygon`.","type":"string","default":"MultiPolygon","const":"MultiPolygon","title":"Type"},"coordinates":{"description":"An array of Polygon coordinate arrays.","type":"array","items":{"items":{"items":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":3,"minItems":3}]},"type":"array"},"type":"array"},"title":"Coordinates"}},"required":["coordinates"],"title":"MultiPolygon"},"LineString":{"description":"A GeoJSON LineString geometry.","type":"object","properties":{"type":{"description":"The geometry type. Always `LineString`.","type":"string","default":"LineString","const":"LineString","title":"Type"},"coordinates":{"description":"An array of two or more positions.","type":"array","items":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":3,"minItems":3}]},"title":"Coordinates"}},"required":["coordinates"],"title":"LineString"},"MultiLineString":{"description":"A GeoJSON MultiLineString geometry containing multiple LineString geometries.","type":"object","properties":{"type":{"description":"The geometry type. Always `MultiLineString`.","type":"string","default":"MultiLineString","const":"MultiLineString","title":"Type"},"coordinates":{"description":"An array of LineString coordinate arrays.","type":"array","items":{"items":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":3,"minItems":3}]},"type":"array"},"title":"Coordinates"}},"required":["coordinates"],"title":"MultiLineString"},"Industry":{"description":"The industry classification of a business location.","type":"string","enum":["parking","restaurants","retail","accommodation","cpg","tourism","marketing","transportation","other"],"title":"Industry"},"OriginGeoJson":{"description":"A GeoJSON Feature with a Point geometry representing the exact origin location of a business.","type":"object","properties":{"type":{"description":"The GeoJSON object type. Always `Feature`.","type":"string","default":"Feature","const":"Feature","title":"Type"},"geometry":{"description":"A Point geometry defining the origin coordinates.","$ref":"#/components/schemas/Point"}},"additionalProperties":false,"required":["geometry"],"title":"OriginGeoJson"},"SubscriptionValidType":{"description":"A subscription feature type that a location is valid for.","type":"string","enum":["broadcasts","events","features_api","notifications"],"title":"SubscriptionValidType"},"LocationType":{"description":"The type of geographic definition used for a Saved Location.","type":"string","enum":["place_id","point","polygon","impact_area"],"title":"LocationType"},"SavedLocationStatus":{"description":"The status of a Saved Location. Locations start as `pending` and become `active` after enrichment.","type":"string","enum":["active","deleted","pending"],"title":"SavedLocationStatus"},"SummaryInsights":{"description":"Aggregated event and spend metrics for a location over a rolling date range.","type":"object","properties":{"date_range":{"description":"The date range over which the insight metrics were calculated.","$ref":"#/components/schemas/DateRange"},"phq_attendance_sum":{"description":"The total predicted attendance across all attended events.","type":"integer","title":"Phq Attendance Sum"},"attended_event_count":{"description":"The number of attended events impacting this location.","type":"integer","title":"Attended Event Count"},"non_attended_event_count":{"description":"The number of non-attended events impacting this location.","type":"integer","title":"Non Attended Event Count"},"unscheduled_event_count":{"description":"The number of unscheduled events impacting this location.","type":"integer","title":"Unscheduled Event Count"},"demand_surge_count":{"description":"The number of demand surges impacting this location.","type":"integer","title":"Demand Surge Count"},"venue_count":{"description":"The number of venues within the location area.","type":"integer","title":"Venue Count"},"pes_total_sum":{"description":"Total predicted event spend across all categories in USD.","type":"integer","title":"Pes Total Sum"},"pes_accommodation_sum":{"description":"Predicted event spend for the accommodation category.","type":"integer","title":"Pes Accommodation Sum"},"pes_hospitality_sum":{"description":"Predicted event spend for the hospitality category.","type":"integer","title":"Pes Hospitality Sum"},"pes_transportation_sum":{"description":"Predicted event spend for the transportation category.","type":"integer","title":"Pes Transportation Sum"}},"required":["date_range","phq_attendance_sum","attended_event_count","non_attended_event_count","unscheduled_event_count"],"title":"SummaryInsights"},"DateRange":{"description":"A date range over which insight metrics are calculated.","type":"object","properties":{"type":{"description":"The type of date range. Currently only `next_90d` is supported.","$ref":"#/components/schemas/DateRangeType"},"start_dt":{"description":"The start of the date range in ISO 8601 format.","type":"string","format":"date-time","title":"Start Dt"},"end_dt":{"description":"The end of the date range in ISO 8601 format.","type":"string","format":"date-time","title":"End Dt"}},"required":["type","start_dt","end_dt"],"title":"DateRange"},"DateRangeType":{"description":"The type of date range for insight calculations. Currently only `next_90d` is supported.","type":"string","const":"next_90d","title":"DateRangeType"},"Place":{"description":"A geographic place resolved from a Geonames place ID.","type":"object","properties":{"place_id":{"description":"The Geonames place identifier.","type":"integer","title":"Place Id"},"type":{"description":"The type of place, such as `locality`, `county`, `region`, or `country`.","type":"string","title":"Type"},"name":{"description":"The name of the place.","type":"string","title":"Name"},"county":{"description":"The county the place belongs to, if applicable.","type":"string","title":"County"},"region":{"description":"The region or state the place belongs to, if applicable.","type":"string","title":"Region"},"country":{"description":"The ISO 3166-1 alpha-2 country code.","type":"string","title":"Country"},"geojson":{"description":"The geographic representation of the place in GeoJSON format.","$ref":"#/components/schemas/PlaceGeoJson"}},"required":["place_id","type","name","geojson"],"title":"Place"},"PlaceGeoJson":{"description":"A GeoJSON Feature representing the geographic geometry of a place.","type":"object","properties":{"type":{"description":"The GeoJSON object type. Always `Feature`.","type":"string","default":"Feature","const":"Feature","title":"Type"},"geometry":{"description":"The geometry of the place.","anyOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"}],"title":"Geometry"}},"required":["geometry"],"title":"PlaceGeoJson"},"AdditionalDetails":{"description":"Supplementary operational data for a location, including upcoming opening hours and closures.","type":"object","properties":{"opening_hours":{"description":"Opening hour slots that fall within the rolling window for this location.","type":"array","items":{"$ref":"#/components/schemas/OpeningHourSlot-Output"},"title":"Opening Hours"},"closures":{"description":"Closures that fall within the rolling window for this location.","type":"array","items":{"$ref":"#/components/schemas/AdditionalDetailsClosure"},"title":"Closures"}},"title":"AdditionalDetails"},"OpeningHourSlot-Output":{"description":"A day-and-time-slot pair defining when a location is open, as returned in responses.","type":"object","properties":{"day":{"description":"The day of the week this slot applies to.","$ref":"#/components/schemas/DayOfWeek"},"slot":{"description":"The time range for this opening slot.","$ref":"#/components/schemas/TimeSlot-Output"}},"required":["day","slot"],"title":"OpeningHourSlot"},"DayOfWeek":{"description":"A day of the week.","type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"title":"DayOfWeek"},"TimeSlot-Output":{"description":"A time slot representing when a location is open on a given day, as returned in responses.","type":"object","properties":{"open":{"description":"Opening time in HH:MM format (00:00-23:59)","type":"string","pattern":"^([01]?[0-9]|2[0-3]):[0-5][0-9]$","title":"Open"},"close":{"description":"Closing time in HH:MM format (00:00-24:00)","type":"string","pattern":"^(([01]?[0-9]|2[0-3]):[0-5][0-9]|24:00)$","title":"Close"}},"required":["open","close"],"title":"TimeSlot"},"AdditionalDetailsClosure":{"description":"A closure record within the additional details rolling window.","type":"object","properties":{"effective_from":{"description":"The start date of the closure period.","type":"string","title":"Effective From"},"effective_to":{"description":"The end date of the closure period.","type":"string","title":"Effective To"},"title":{"description":"A short descriptive title for the closure.","type":"string","title":"Title"}},"required":["effective_from","effective_to","title"],"title":"AdditionalDetailsClosure"},"HTTPValidationError":{"description":"A validation error response containing field-level error details.","type":"object","properties":{"error":{"description":"A summary error message.","type":"string"},"details":{"description":"A list of field-level validation errors.","type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}},"title":"HTTPValidationError"},"ValidationError":{"description":"A single field-level validation error.","type":"object","properties":{"field":{"description":"The field path that caused the error.","type":"string"},"msg":{"description":"A human-readable error message.","type":"string","title":"Message"},"type":{"description":"The type of validation error.","type":"string","title":"Error Type"}},"title":"ValidationError"},"ErrorResponse":{"description":"An error response containing a human-readable error message.","type":"object","properties":{"error":{"description":"Error message","type":"string","title":"Error"}},"required":["error"],"title":"ErrorResponse"}}},"paths":{"/v1/saved-locations/{location_id}":{"get":{"operationId":"get_saved_location","summary":"Get a Saved Location","description":"Retrieve full details for a single Saved Location by ID.\n\nResponse 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.\n\nThe `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.","parameters":[{"name":"location_id","in":"path","description":"An existing Saved Location ID.","required":true,"schema":{"type":"string","title":"Location Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedLocationResponse"}}}},"400":{"description":"Bad Request","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"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Saved Locations API"]}}}}
````

## Examples

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

```bash
curl --location 'https://api.predicthq.com/v1/saved-locations/_4Dl3p4Q2zl4ifMjG4Z3ew' \
--header 'Authorization: Bearer TOKEN'
```

{% endtab %}

{% tab title="python" %}

```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)
```

{% endtab %}
{% endtabs %}

## OpenAPI Spec

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

## Guides

Below are some guides relevant to this API:

* [Working with Location-Based Subscriptions](/getting-started/guides/geolocation-guides/searching-by-location/working-with-location-based-subscriptions.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.predicthq.com/api/saved-locations/get-a-saved-location.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.