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.

    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'