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 creating
labels - 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)

curl --location 'https://api.predicthq.com/v1/saved-locations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "name": "Test with place_id",
    "labels": [],
    "place_ids": [ 2750405 ]
}'

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: for sorting on summary insights `date_range_type.summary_insight_key` with full example for next_90d type - e.g. `next_90d.phq_attendance_sum` created updated name address location_code 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: `Point` `Polygon` - this is reserved for future use 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 - use next_90d
category - list of event categories - see category in the Events API documentation
offset - 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
            ]
        }
    }
}'

Delete a saved location

To delete a location use DELETE /saved-locations/location_id. Where location_id is the ID of the location to delete.

curl --location --request DELETE 'https://api.predicthq.com/v1/saved-locations/K9XvW4KE32ZjcdqQ3WiPvg' \
--header 'Authorization: Bearer TOKEN'