# Get a Saved Location ## GET /v1/saved-locations/{location\_id} > Get a Saved Location ````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 ` as documented at [https://docs.predicthq.com/api/overview/authenticating](https://docs.predicthq.com/api/overview/authenticating)\n"}},"schemas":{"SavedLocationResponse":{"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"},"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 created a location. \nIf it's not supplied it will be populated by a reverse geocode.\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 location 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":{"$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":{"$ref":"#/components/schemas/AdditionalDetails"}},"required":["create_dt","update_dt","status","location_id"],"title":"SavedLocationResponse"},"GeoJson-Output":{"type":"object","properties":{"type":{"type":"string","const":"Feature","title":"Type"},"properties":{"$ref":"#/components/schemas/Properties"},"geometry":{"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":{"type":"number","title":"Radius"},"radius_unit":{"$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":{"type":"object","properties":{"type":{"type":"string","default":"Point","const":"Point","title":"Type"},"coordinates":{"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":{"type":"object","properties":{"type":{"type":"string","default":"Polygon","const":"Polygon","title":"Type"},"coordinates":{"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":{"type":"object","properties":{"type":{"type":"string","default":"MultiPolygon","const":"MultiPolygon","title":"Type"},"coordinates":{"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":{"type":"object","properties":{"type":{"type":"string","default":"LineString","const":"LineString","title":"Type"},"coordinates":{"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":{"type":"object","properties":{"type":{"type":"string","default":"MultiLineString","const":"MultiLineString","title":"Type"},"coordinates":{"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":{"type":"string","enum":["parking","restaurants","retail","accommodation","cpg","tourism","marketing","transportation","other"],"title":"Industry"},"OriginGeoJson":{"type":"object","properties":{"type":{"type":"string","default":"Feature","const":"Feature","title":"Type"},"geometry":{"$ref":"#/components/schemas/Point"}},"additionalProperties":false,"required":["geometry"],"title":"OriginGeoJson"},"SubscriptionValidType":{"type":"string","enum":["broadcasts","events","features_api","notifications"],"title":"SubscriptionValidType"},"LocationType":{"type":"string","enum":["place_id","point","polygon","impact_area"],"title":"LocationType"},"SavedLocationStatus":{"type":"string","enum":["active","deleted","pending"],"title":"SavedLocationStatus"},"SummaryInsights":{"type":"object","properties":{"date_range":{"$ref":"#/components/schemas/DateRange"},"phq_attendance_sum":{"type":"integer","title":"Phq Attendance Sum"},"attended_event_count":{"type":"integer","title":"Attended Event Count"},"non_attended_event_count":{"type":"integer","title":"Non Attended Event Count"},"unscheduled_event_count":{"type":"integer","title":"Unscheduled Event Count"},"demand_surge_count":{"type":"integer","title":"Demand Surge Count"},"venue_count":{"type":"integer","title":"Venue Count"},"pes_total_sum":{"type":"integer","title":"Pes Total Sum"},"pes_accommodation_sum":{"type":"integer","title":"Pes Accommodation Sum"},"pes_hospitality_sum":{"type":"integer","title":"Pes Hospitality Sum"},"pes_transportation_sum":{"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":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/DateRangeType"},"start_dt":{"type":"string","format":"date-time","title":"Start Dt"},"end_dt":{"type":"string","format":"date-time","title":"End Dt"}},"required":["type","start_dt","end_dt"],"title":"DateRange"},"DateRangeType":{"type":"string","const":"next_90d","title":"DateRangeType"},"Place":{"type":"object","properties":{"place_id":{"type":"integer","title":"Place Id"},"type":{"type":"string","title":"Type"},"name":{"type":"string","title":"Name"},"county":{"type":"string","title":"County"},"region":{"type":"string","title":"Region"},"country":{"type":"string","title":"Country"},"geojson":{"$ref":"#/components/schemas/PlaceGeoJson"}},"required":["place_id","type","name","geojson"],"title":"Place"},"PlaceGeoJson":{"type":"object","properties":{"type":{"type":"string","default":"Feature","const":"Feature","title":"Type"},"geometry":{"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":{"type":"object","properties":{"opening_hours":{"type":"array","items":{"$ref":"#/components/schemas/OpeningHourSlot-Output"},"title":"Opening Hours"},"closures":{"type":"array","items":{"$ref":"#/components/schemas/AdditionalDetailsClosure"},"title":"Closures"}},"title":"AdditionalDetails"},"OpeningHourSlot-Output":{"type":"object","properties":{"day":{"$ref":"#/components/schemas/DayOfWeek"},"slot":{"$ref":"#/components/schemas/TimeSlot-Output"}},"required":["day","slot"],"title":"OpeningHourSlot"},"DayOfWeek":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"title":"DayOfWeek"},"TimeSlot-Output":{"description":"Time slot with dual field naming: technical precision internally, user-friendly API externally.\n\nField configuration creates different interfaces:\n- Internal usage: Code accesses .gte/.lt attributes (technical, precise field names)\n- Model input: Accepts both \"gte\"/\"open\" and \"lt\"/\"close\" via AliasChoices validation\n- API output: FastAPI serializes as \"open\"/\"close\" using by_alias=True (user-friendly field names)\n\nThis separation allows internal code to use precise technical terminology while\nproviding an intuitive customer-facing API interface.","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":{"type":"object","properties":{"effective_from":{"type":"string","title":"Effective From"},"effective_to":{"type":"string","title":"Effective To"},"title":{"type":"string","title":"Title"}},"required":["effective_from","effective_to","title"],"title":"AdditionalDetailsClosure"},"HTTPValidationError":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}},"title":"HTTPValidationError"},"ValidationError":{"type":"object","properties":{"field":{"type":"string"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"title":"ValidationError"}}},"paths":{"/v1/saved-locations/{location_id}":{"get":{"operationId":"get_location_public_locations__location_id__get","summary":"Get a Saved Location","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"}}}}},"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](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/getting-started/guides/geolocation-guides/searching-by-location/working-with-location-based-subscriptions)