> For the complete documentation index, see [llms.txt](https://docs.predicthq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/working-with-location-based-subscriptions.md).
# Working with location-based subscriptions
{% hint style="info" %}
**Note:** If you have location-based access and make requests to the [Events API](/api/events/search-events.md) or [Features API](/api/features/get-features.md), filter your API calls by a Saved Location ID.
{% endhint %}
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](/api/impact-area/get-impact-area.md) 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](/api/saved-locations/overview.md)
* To access events you then use our [Events API](/api/events/search-events.md) 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](/api/saved-locations/overview.md) (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](https://www.predicthq.com/support) for more details.
### How to see the number of locations I have access to?
Within the WebApp on the [plans page](https://control.predicthq.com/settings/plans/api) 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.
## 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](/api/saved-locations/overview.md). 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:
```python
import requests
response = requests.get(
url="https://api.predicthq.com/v1/events/",
headers={
"Authorization": "Bearer $API_TOKEN",
"Accept": "application/json"
},
params={
"saved_location.location_id": "sFlb8HlsLa1j-S4UDEMEkQ"
}
)
print(response.json())
```
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//insights/events`. E.g. `GET /saved-locations/0b6ZrOnTdB2Y7k4zC_9qBg/insights/events`.
See the following example:
```python
import requests
response = requests.get(
url="https://api.predicthq.com/v1/saved-locations/sFlb8HlsLa1j-S4UDEMEkQ/events",
headers={
"Authorization": "Bearer $API_TOKEN",
"Accept": "application/json"
},
params={
"date_range_type": "next_90d",
"category": "public-holidays,sports",
"sort": "-start"
}
)
print(response.json())
```
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](/integrations/integration-guides/keep-data-updated-via-api.md).
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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/working-with-location-based-subscriptions.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
