Saved Locations API (Beta)
The Saved Locations API is used for managing Location Insights Locations. See this overview of Location Insights. The name of the feature is Location Insights and the name of the API is the Saved Locations API.
You can use the Saved Locations API to implement all of the functionality that you'll see in PredictHQ's Control Center. If you have access to the PredictHQ APIs you will have access to use the Saved Locations API with the same permissions that you will have for events API subscription. E.g. if you have purchased access to Seattle and Los Angeles you will be able to use the Saved Locations API to create location insights within these geographic areas.
Note that the Saved Locations backend runs an asynchronous enrichment process. After a location is created it will be enriched with details on the number of events and the number of people attending events within a location. This process runs immediately after event creation and the location statistics are periodically updated in the background on a scheduled basis.
The Saved Location API includes the following functionality:
Creating new locations - use
POST /saved-locations
Getting a list of locations for your organization - use
GET /saved-locations
Get location details for a location - use
GET /saved-locations/<location_id>
Get a list of events for a location - use
GET /saved-locations/<location_id>/insights/events
Updating a location - use
PUT /saved-locations/<location_id>
Deleting a location - use
DELETE /saved-locations/<location_id>
This API reference provides details on each of these calls.
Note that you can also use the saved_location.location_id
filter on the Events API to retrieve events within a list of specified locations ids.
Create Saved Locations call
To create a location use the POST /saved-locations
call with the body of the call being populated with the fields shown to the right.
The field definitions can be found in the Saved Locations API Response Fields section.
In general, the create location call needs the following fields:
name
- the name of the location you are creatinglabels
- an array of any labels you want to set to classify the location
It needs one of the following two options - geojson
or place_ids
:
geojson
- for locations where you set a point and radius this field contains the details below. This follows the geojson format defined here. The key values supplied are radius, radius_unit and coordinates. See the code sample for the exact syntax:"type": "Feature",
"properties":
"radius"
- set the radius numeric value - e.g. 1 for 1 mile or 1 kilometer. Use the Suggested Radius API to find the radius to use for a location."radius_unit"
- set the radius unit to m|km|ft|mi
"geometry":
"type": "Point",
coordinates
longitude, latitude - this is the longitude and latitude of the location. For example the longitude and latitude of a business. These values along with the radius are used to define what events are returned for a location.
place_ids
- for locations that affect an area this field lists the place id of the area. Use the Places API to find the Place ID. Typically this option is used when you want to create a location for an entire city, county, state, or country.
Create Saved Location Response
The POST /saved-locations
call returns the location_id for the created location.
E.g. { "location_id": "K9XvW4KE32ZjcdqQ3WiPvg" }
Example 1 - creating a point and radius location
curl --location 'https://api.predicthq.com/v1/saved-locations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
"name": "Example of creating a saved location",
"labels": [],
"geojson": {
"type": "Feature",
"properties": {
"radius": 1,
"radius_unit": "mi"
},
"geometry": {
"type": "Point",
"coordinates": [
-115.1728484,
36.1147065
]
}
}
}'
Example 2 - creating a location for an area (e.g. City, State, Country)
Get Saved Locations
Retrieve a list of Saved Locations based on the parameters supplied.
Query Parameters
Field | Description |
---|---|
location_id string |
A comma-separated string consisting of a list of 1 or more location_id's. E.g. ?location_id=6TxvEapQeDzq9y_UKVRQCQ |
q string |
A full-text search query.This searches name,description, location_code, formatted_address and labels E.g. q=alabama |
sort string |
A comma-separated list of fields to sort results by. Use the - prefix to sort descending. Possible values:
E.g.: ?sort=-created |
limit string |
The maximum number of results to return. The default limit is 10. E.g. ?limit=50 |
offset string |
Used for paging. The number of results to skip. The default is 0. E.g. ?offset=20 |
Action
curl --location 'https://api.predicthq.com/v1/saved-locations?q=alabama&limit=50' \
--header 'Authorization: Bearer TOKEN'
Example
{
"count": 2320,
...
{
"name": "Dallas - city example",
"labels": [],
"place_ids": [
4684888
],
"formatted_address": "Dallas, Dallas County, Texas, United States [Locality]",
"create_dt": "2022-03-25T03:06:28+00:00",
"update_dt": "2022-04-20T04:46:26+00:00",
"enrich_dt": "2022-04-20T04:46:28+00:00",
"insights_dt": "2023-04-13T23:20:54+00:00",
"user_id": "hjqkKozgS8mm",
"subscription_valid_types": [
"events"
],
"status": "active",
"summary_insights": [
{
"date_range": {
"type": "next_90d",
"start_dt": "2023-04-13T23:20:54+00:00",
"end_dt": "2023-07-12T23:20:54+00:00"
},
"phq_attendance_sum": 1819348,
"attended_event_count": 1048,
"non_attended_event_count": 171,
"unscheduled_event_count": 3
}
],
"places": [],
"log": [],
"location_id": "9wYKv38BRcTjM_3SKdjd"
},
...
}
Saved Locations API Response Fields
List of fields returned in the GET Saved Locations response.
All fields are read-only.
Response fields
Field | Description |
---|---|
name string |
The user defined name of the Saved Location set in the create location call. E.g. "name": "Boston" |
labels array |
A list of user defined labels for the location. E.g.: "labels": [ "test", "retail" ] |
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. "place_ids": [ 2750405 ] |
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:
E.g. "geometry": { "type": "Feature", "properties": { "radius": 1.0, "radius_unit": "mi" }, "type": "Point", "coordinates": [ -87.6507,41.9398 ] } } |
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": "E 41st St, New York, NY 10168, USA", |
create_dt string |
The creation date time for the location in ISO 8601 format format. E.g. "create_dt": "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. "update_dt": "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. "enrich_dt": "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 create in Control Center. For locations created via the API this field will not be populated. E.g. "user_id": "hjqkKozgS8mm", |
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 should still be a list. E.g. "places": [ "place_id": "4930956", ... |
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. "subscription_valid_types": [ "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 once 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. "status": "active" |
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. E.g. "summary_insights": [ { "date_range": { "type": "next_90d", "start_dt":... "end_dt": ... }, "phq_attendance_sum": 8676977, "attended_event_count": 4262, "non_attended_event_count": 24, "unscheduled_event_count": 43 } ] |
location_id string |
The ID for the saved location E.g. "location_id": "8gZ2rn8BRcTjM_3SWdjP" |
Example response
...
{
"name": "Coffee chain - near lake view",
"labels": [
"pete",
"coffee"
],
"geojson": {
"type": "Feature",
"properties": {
"radius": 1.0,
"radius_unit": "mi"
},
"geometry": {
"type": "Point",
"coordinates": [
-87.65076599999999,
41.93985199999999
]
}
},
"formatted_address": "3184 N Clark St, Chicago, IL 60657, USA",
"create_dt": "2022-04-05T05:18:20+00:00",
"update_dt": "2022-04-20T02:20:29+00:00",
"enrich_dt": "2022-04-20T02:20:30+00:00",
"insights_dt": "2023-04-13T22:53:10+00:00",
"user_id": "hjqkKozgS8mm",
"subscription_valid_types": [
"events"
],
"status": "active",
"summary_insights": [
{
"date_range": {
"type": "next_90d",
"start_dt": "2023-04-13T22:53:10+00:00",
"end_dt": "2023-07-12T22:53:10+00:00"
},
"phq_attendance_sum": 2608079,
"attended_event_count": 446,
"non_attended_event_count": 123,
"unscheduled_event_count": 0
}
],
"places": [],
"log": [],
"location_id": "TyaP1J9dnDFM8iLxcnI3Ow"
},
...
Get location details
To get location details for a location make the following call with the location_id GET /saved-locations/<location_id>
. E.g. GET /saved-locations/5BcRstnNPjXl-fiB_0TQJg
.
The fields in the response are the Saved Locations API Response Fields (listed for GET /saved-locations
).
Request
curl --location 'https://api.predicthq.com/v1/saved-locations/_4Dl3p4Q2zl4ifMjG4Z3ew' \
--header 'Authorization: Bearer TOKEN'
Response
{
"name": "Fairmont Austin - example",
"labels": [
"Pete"
],
"geojson": {
"type": "Feature",
"properties": {
"radius": 2.0,
"radius_unit": "km"
},
"geometry": {
"type": "Point",
"coordinates": [
-97.7382007,
30.2621272
]
}
},
"formatted_address": "101 Red River St, Austin, TX 78701, USA",
"create_dt": "2022-04-07T20:50:00+00:00",
"update_dt": "2022-04-20T03:49:25+00:00",
"enrich_dt": "2022-04-20T03:49:27+00:00",
"insights_dt": "2023-04-17T23:46:24+00:00",
"user_id": "hjqkKozgS8mm",
"subscription_valid_types": [
"events"
],
"status": "active",
"summary_insights": [
{
"date_range": {
"type": "next_90d",
"start_dt": "2023-04-17T23:46:24+00:00",
"end_dt": "2023-07-16T23:46:24+00:00"
},
"phq_attendance_sum": 811152,
"attended_event_count": 624,
"non_attended_event_count": 121,
"unscheduled_event_count": 0
}
],
"places": [],
"log": [],
"location_id": "_4Dl3p4Q2zl4ifMjG4Z3ew"
}
Get a list of events for a location
To get a list of events for a location make the following call with the location_id GET /saved-locations/<location_id>/insights/events
. E.g. GET /saved-locations/0b6ZrOnTdB2Y7k4zC_9qBg/insights/events
.
date_range_type
- usenext_90d
category
- list of event categories - seecategory
in the Events API documentationoffset
- standard paging field. See above.limit
- standard paging field. See above.sort
- See the sort field for the Events API
Note that you can also use the saved_location.location_id
field in the Events API to get a list of events for a location or for multiple locations.
Response fields
The fields in the response are the same as the Events API fields
Request
curl --location 'https://api.predicthq.com/v1/saved-locations/0b6ZrOnTdB2Y7k4zC_9qBg/insights/events?date_range_type=next_90d&category=public-holidays%2Csports&sort=start' \
--header 'Authorization: Bearer TOKEN'
Response
{
"count": 11,
"results": [
{
"id": "hBFEUSAiFQAizkpkWA",
"title": "Confederate Memorial Day",
"description": "On Confederate Memorial Day remembers the soldiers who died fighting for the Confederate States of America during the American Civil War (1861-1865). It is a state holiday in some parts of the United States.",
"entities": [
{
"formatted_address": "",
"type": "event-group",
"name": "Confederate Heroes' Day"
}
],
"place_hierarchies": [
[
"6295630",
"6255149",
"6252001",
"4829764"
]
],
"location": [
-86.902298,
32.3182314
],
"start": "2023-04-24T00:00:00Z",
"end": "2023-04-24T23:59:59Z",
"duration": 86399,
"category": "public-holidays",
"labels": [
"holiday",
"holiday-local"
],
"rank": 70,
"aviation_rank": 0,
"geo": {
"geometry": {
"type": "Point",
"coordinates": [
-86.902298,
32.3182314
]
}
},
"state": "active"
},
{
"id": "4vSSuEGwiQ5msWDqNx",
"title": "National Collegiate Beach Volleyball Championship - Friday",
"description": "",
"entities": [
{
"formatted_address": "West Gulf Place\nGulf Shores, AL 36542\nUnited States of America",
"type": "venue",
"name": "Gulf Shores Public Beach"
}
],
"place_hierarchies": [
[
"6295630",
"6255149",
"6252001",
"4829764",
"4831207",
"4065552"
]
],
"timezone": "America/Chicago",
"location": [
-87.6909473,
30.2476689
],
"start": "2023-05-05T14:00:00Z",
"end": "2023-05-05T14:00:00Z",
"duration": 0,
"category": "sports",
"labels": [
"sport",
"volleyball"
],
"phq_attendance": 8,
"rank": 8,
"local_rank": 42,
"geo": {
"geometry": {
"type": "Point",
"coordinates": [
-87.6909473,
30.2476689
]
},
"placekey": "@8f5-68z-ghq"
},
"state": "active"
},
...
Update a Location
To update a location call PUT /saved-locations/<location-id>
with the location_id of the location to update. Use this call to modify a location that you have created. The format of the body of the PUT request is the same as the POST /saved-locations
call used to create a location.
curl --location --request PUT 'https://api.predicthq.com/v1/saved-locations/5BcRstnNPjXl-fiB_0TQJg' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
"name": "S Las Vegas Blvd, Las Vegas (NV), US",
"labels": [],
"geojson": {
"type": "Feature",
"properties": {
"radius": 1,
"radius_unit": "mi"
},
"geometry": {
"type": "Point",
"coordinates": [
-115.1728484,
36.1147065
]
}
}
}'