Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Working with location-based subscriptions

Note: If you have location-based access and make requests to the Events API or Features API, filter your API calls by a Saved Location ID.

You can purchase access to PredictHQ's events in different ways. You can purchase access to geographic areas like cities, states, or countries. Or you can purchase access to a number of locations to get access to specific business locations. Business locations include stores, hotels, restaurants, parking garages, offices, or any other type of location you can think of.

Under the hood, location-based access uses latitude, longitude, and radius to control what you can access. In the UI you can enter a street address for a business location and the product finds the latitude and longitude for that location and sets a Predicted Impact Area and save the location with those details.

You can purchase location-based access if you have a number of business locations across a region, country, or multiple countries that you want access to but you don't need access to larger geographic areas like cities, states, or countries. For example, you may have a hotel chain with 300 hotels across the US in 20 different states spread between smaller towns and bigger cities. You can purchase location-based access for 300 hotels rather than buying access to full cities or entire states. The same could apply to a chain of restaurants, parking locations, retail stores, or any other business locations.

This guide provides details on how to use PredictHQ APIs when you have purchased location-based access instead of access to larger geographic areas.

The summary of how to use our APIs with location-based access is as follows:

  • To create a Saved Location for each of your business locations, use the Saved Locations feature in our WebApp or our Saved Locations API

  • To access events you then use our Events API and call it using the saved_location.location_id filter to access events for your locations. Alternatively, you can also access events using the /events call in the Saved Locations API (see Get a list of events for a location).

  • If you add or delete locations ensure you update the location_id values used to query the API.

This guide is focused on using the APIs. You can also use our WebApp to manage and access locations. See the documentation on the WebApp for more details.

How to see the number of locations I have access to?

Within the WebApp on the plans page or in the Location Insights view you can see how many locations you have purchased and how many you have used.

If you add more locations than you have purchased, you keep access to the extra locations for a limited time. To keep them, upgrade your subscription to purchase more, or remove the locations you added. The PredictHQ team reaches out to discuss your options.

The Location Insights view showing the number of locations purchased and the number used

How to use the APIs with location-based access

Setting up your locations

You will have a list of locations for your business. Such as a list of addresses for your stores. The first stage is to find the latitude and longitude (lat/long) of each store. Once you have done that you can create Saved Locations for each using the API.

For example, you could create a file that has a list of lat/longs and names for each store and run a script over the file to create Saved Locations for each.

See the Saved Locations API documentation. To upload a list of locations do the following:

  1. Find the lat/long of each location

  2. Call the Create Saved Locations endpoint (POST /saved-locations) using origin_geojson with the lat/lon for each location. The API calculates Predicted Impact Area automatically and stores it as the location boundary, so no separate API call is needed

  3. Store the location_id returned for each location

This process only needs to be performed when you initially load in your locations or if locations change (such as a store closes or a new store opens).

Fetching events for your locations

Once you have uploaded your locations you will have a list of location_id's for each location. To get the latest events for each location you can call the Events API with the saved_location.location_id filter to get back events for the location.

Example fetching events using a Saved Location ID:

You can use other filters in the Events API to further filter down the response. Use paging to handle multiple pages of results.

Alternatively, you can also access events using the /events call in the Saved Locations API (see 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.

See the following example:

You can then use the events or store them in your data store. Ensure you keep events refresh as events are dynamic and can change such as be canceled, postponed, move locations, change dates, and so on. See Keeping Data Updated.

For example, you may write code to loop over your list of locations and retrieve updated events for each and update your data store.

Note if you have location-based access you need to supply a value for this filter. If you do not supply a value, the API returns an error.

Last updated

Was this helpful?