Get a Saved Location

Get an existing Saved Location.

Request
HTTP Request
GET https://api.predicthq.com/v1/saved-locations/$location_id​
Path Parameters
Parameter
Description
location_id
An existing Saved Location ID.
Response
Response Fields
Field
Description
location_id
string
The autogenerated identifier for the saved location.

E.g. 8gZ2rn8BRcTjM_3SWdjP
location_code
string
The user-supplied identifier for the location.

E.g. 4t855453234t5623
name
string
The user defined name of the Saved Location set in the create location call.

E.g. My Parking Building
labels
array
A list of user defined labels for the location.

E.g.: ["test", "retail"]
create_dt
string
The creation date time for the location in ISO 8601 format format.

E.g. 2022-04-26T11:46:24+00:00
update_dt
string
The last update date time for the location in ISO 8601 format format.

E.g. 2022-04-26T11:46:24+00:00
enrich_dt
string
The date time the location was last enriched in ISO 8601 format format.

E.g. 2022-04-26T11:46:25+00:00
insights_dt
string
The date/time insights were last calculated for the location in ISO 8601 format format.

E.g. 2022-04-26T11:46:25+00:00
user_id
string
The ID of the user who created the saved location. This is present for location created in Control Center. For locations created via the API this field will not be populated.

E.g. hjqkKozgS8mm
geojson
object
An object containing the geographic information about a location. Represents the geometry associated with the event in the GeoJSON format.

This will be present for locations that use a centerpoint and radius. For locations that cover an area (for example city, state or country) they will not have the geojson value defined instead they use place_ids.

Point type locations are defined by latitude and longitude.
The radius field defines which events are included in the location.
Events that are within the radius or that overlap the radius are included

Geometry - Possible types:
Point
Polygon - this is reserved for future use
{
  "geojson": {
    "type": "Feature",
    "properties": {
      "radius": 0.9,
      "radius_unit": "mi"
    },
    "geometry": {
      "type": "Point",
      "coordinates": [
        -122.40152,
        37.7869
      ]
    }
  }
}
place_ids
array
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]
formatted_address
string
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",
}
places
string
This is a list of (geonames) Places. It is based on the lowest level place_id in the place_hierarchies. It will usually only contain 1 item in the list but will always be a list.
​
{
  "places": [
    {
      "place_id": 5391959,
      "type": "locality",
      "name": "San Francisco",
      "county": "City and County of San Francisco",
      "region": "California",
      "country": "US",
      "geojson": {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -122.41942,
            37.77493
          ]
        }
      }
    }
  ]
}
summary_insights
array
This object contains the saved locations stats. This includes values for each of the 4 stats as well as the date_range field. The stats reflect the number of events and attend happening for the location.

The date range field includes the start and end datetime for the period that the stats have been calculated for.
{
  "summary_insights": [
    {
      "date_range": {
        "type": "next_90d",
        "start_dt": "2023-07-03T04:39:16+00:00",
        "end_dt": "2023-10-01T04:39:16+00:00"
      },
      "phq_attendance_sum": 2646606,
      "attended_event_count": 519,
      "non_attended_event_count": 85,
      "unscheduled_event_count": 0
    }
  ]
}
subscription_valid_types
array
The value is a list of different (subscription) types that this location is valid for. The possible values are events, broadcasts, notifications, features_api. 
​
It is possible to create locations outside of what your subscription has access to. In this case this field will be empty and you will not be able to view events for the location

E.g. ["events"]
status
string
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 response
Below is an example response:
{
  "location_id": "h8LbiiiTOXsxSAI0p3wEIg",
  "create_dt": "2023-03-27T22:07:00+00:00",
  "update_dt": "2023-07-03T04:31:38+00:00",
  "enrich_dt": "2023-07-03T04:31:39+00:00",
  "insights_dt": "2023-07-03T04:31:40+00:00",
  "name": "My Parking Building",
  "labels": [
    "parking"
  ],
  "geojson": {
    "type": "Feature",
    "properties": {
      "radius": 0.9,
      "radius_unit": "mi"
    },
    "geometry": {
      "type": "Point",
      "coordinates": [
        -122.40152,
        37.7869
      ]
    }
  },
  "formatted_address": "666 Mission St, San Francisco, CA 94105, USA",
  "places": [
    {
      "place_id": 5391959,
      "type": "locality",
      "name": "San Francisco",
      "county": "City and County of San Francisco",
      "region": "California",
      "country": "US",
      "geojson": {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -122.41942,
            37.77493
          ]
        }
      }
    }
  ],
  "summary_insights": [
    {
      "date_range": {
        "type": "next_90d",
        "start_dt": "2023-07-03T04:31:40+00:00",
        "end_dt": "2023-10-01T04:31:40+00:00"
      },
      "phq_attendance_sum": 2646606,
      "attended_event_count": 519,
      "non_attended_event_count": 85,
      "unscheduled_event_count": 0
    }
  ],
  "subscription_valid_types": [
    "events"
  ],
  "status": "active"
}
Examples
curl
python
curl --location 'https://api.predicthq.com/v1/saved-locations/_4Dl3p4Q2zl4ifMjG4Z3ew' \
--header 'Authorization: Bearer TOKEN'
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)
Guides
Below are some guides relevant to this API:
​Working with Location-Based Subscriptions​

Parameter	Description
`location_id`	An existing Saved Location ID.

Field	Description
`location_id` string	The autogenerated identifier for the saved location. E.g. `8gZ2rn8BRcTjM_3SWdjP`
`location_code` string	The user-supplied identifier for the location. E.g. `4t855453234t5623`
`name` string	The user defined name of the Saved Location set in the create location call. E.g. `My Parking Building`
`labels` array	A list of user defined labels for the location. E.g.: `["test", "retail"]`
`create_dt` string	The creation date time for the location in ISO 8601 format format. E.g. `2022-04-26T11:46:24+00:00`
`update_dt` string	The last update date time for the location in ISO 8601 format format. E.g. `2022-04-26T11:46:24+00:00`
`enrich_dt` string	The date time the location was last enriched in ISO 8601 format format. E.g. `2022-04-26T11:46:25+00:00`
`insights_dt` string	The date/time insights were last calculated for the location in ISO 8601 format format. E.g. `2022-04-26T11:46:25+00:00`
`user_id` string	The ID of the user who created the saved location. This is present for location created in Control Center. For locations created via the API this field will not be populated. E.g. `hjqkKozgS8mm`
`geojson` object	An object containing the geographic information about a location. Represents the geometry associated with the event in the GeoJSON format. This will be present for locations that use a centerpoint and radius. For locations that cover an area (for example city, state or country) they will not have the geojson value defined instead they use place_ids. Point type locations are defined by latitude and longitude. The radius field defines which events are included in the location. Events that are within the radius or that overlap the radius are included Geometry - Possible types: `Point` `Polygon` - this is reserved for future use { "geojson": { "type": "Feature", "properties": { "radius": 0.9, "radius_unit": "mi" }, "geometry": { "type": "Point", "coordinates": [ -122.40152, 37.7869 ] } } }
`place_ids` array	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]`
`formatted_address` string	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", }
`places` string	This is a list of (geonames) Places. It is based on the lowest level place_id in the place_hierarchies. It will usually only contain 1 item in the list but will always be a list. { "places": [ { "place_id": 5391959, "type": "locality", "name": "San Francisco", "county": "City and County of San Francisco", "region": "California", "country": "US", "geojson": { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -122.41942, 37.77493 ] } } } ] }
`summary_insights` array	This object contains the saved locations stats. This includes values for each of the 4 stats as well as the `date_range` field. The stats reflect the number of events and attend happening for the location. The date range field includes the start and end datetime for the period that the stats have been calculated for. { "summary_insights": [ { "date_range": { "type": "next_90d", "start_dt": "2023-07-03T04:39:16+00:00", "end_dt": "2023-10-01T04:39:16+00:00" }, "phq_attendance_sum": 2646606, "attended_event_count": 519, "non_attended_event_count": 85, "unscheduled_event_count": 0 } ] }
`subscription_valid_types` array	The value is a list of different (subscription) types that this location is valid for. The possible values are `events`, `broadcasts`, `notifications`, `features_api`. It is possible to create locations outside of what your subscription has access to. In this case this field will be empty and you will not be able to view events for the location E.g. `["events"]`
`status` string	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`

Search Saved Locations

Search Events for a Saved Location

Last modified 2mo ago