Q: How do I get my API key?
A: You need to make sure you have a paying Placer account, and then you can contact your customer success manager to add permissions to your account and provide you with the access api-key.
Q: When is my weekly quota being renewed?
A: The quota renewal is scheduled for Sundays at 12:00 a.m. UTC.
Q: What are the defined API call rate limitations?
A: Please refer to the following throttle rate limits :
- The quota for reports preparation is - 5000/hour(relevant for reports endpoints);
- The quota for POI query/creation/deletion - 360/min or 10000/hour (relevant for all endpoints included in the manage POIs section);
- The quota for ranking reports- 8000/min or 80000/hour (relevant for ranking reports endpoints)
- General limitation - Execute up to 10 API calls/sec and up to 5 concurrent processes(Relevant for all endpoints)
Q: What API calls count towards my quota??
A: All API calls are counted towards your quota, except those that result in the following status codes:
- 202 (Accepted): The request has been accepted for processing but is not yet completed.
- 429 (Too Many Requests): The request was rejected due to rate limiting.
- 500 (Internal Server Error): The request failed due to a server-side error.
These excluded calls do not consume quota as they do not contribute to actual resource usage. All other API requests, including those that result in other client errors, are counted towards your quota
Q: What is the expected data lag?
A: In order to accurately present recent visitation to any location, the data pulled includes a 3-5 day processing lag, and therefore the latest data reflects visitation up to a few days prior to today's date. Generally, we see a 3 day lag Monday - Saturday and a 4 day lag on Sundays due to our weekend cooldowns.
The Visits by CBGs endpoint is refreshed once a week on Wednesdays.
Q: Are Custom POIs added under the Account Portfolio list after creation?
A: No, however, you can view all custom POIs directly in the platform under My zone > Custom POIs. If you’d like to access/ track all custom POIs that are created via the API, we recommend creating a separate tag for your custom POIs and adding them each time a custom POI is created.
Q: How often should I be retrying when receiving an IN_PROGRESS (HTTP Status Code 202 / Error Code 3005) response?
A: See here for processing duration measurements taken based on a variety of test cases for each endpoint. This information can assist you when planning the utilization of Placer API. In general, every report, it is recommended to do exponential backoff, starting with a short delay and increasing in time as the retry counts grow. i.e. 1 sec, 3 sec, 5 sec, 10 sec, 20 sec, 60 sec, etc. In addition, small locations with less visits are likely to return results faster, and large CPOIs / Markets will take more time (even up to 10 min).
Q: What pattern do you recommend for large bulk pulls to avoid timeouts (batch size, concurrency, limits, etc)?
A: Using Bulk endpoints for requesting reports for 100 entities with a date range longer than 1 year is currently unsupported.
Recommendations
- Batch size: use the max bulk size of 100 POIs per call.
- Concurrency: instead of running bulk calls sequentially, use a fixed-size worker pool that continuously pulls from the full set of POIs. As soon as one report is ready, that worker picks up the next pending one, so you're never idle waiting on the slower reports. The limit is 5 concurrent workers.
- Pacing: cap the overall request rate at no more than 10 API calls per second.
Q: Why does the Visit Trends endpoint return data for a given timeframe but not the Visit Metrics/Visit Trends by Single Property endpoint for the same timeframe?
A: The Visit Metrics report and Visit Trends by Single Property report (aligned with the dashboard) have a panel threshold, which is why it can return no results when the Visit Trends endpoint is returning results. For situations where you encounter no results due to a low panel, we recommend pulling a larger timeframe and larger granularity.
Q: When should I use the Visit Trends vs. Visit Trends by Single Property reports?
A: The Visit Trends report was built out specifically for Custom POIs. It is recommended to use the Visit Trends by Single Property Report for Custom POIs and the Visit Trends Report for verified POIs.
Q:Why does data from the API sometimes differ slightly from the dashboard?
A: In order to return data more efficiently the Visit Trends and Visits by CBG endpoints serve data from our last daily batch rather than the data source that powers the dashboard that is computed on demand. As a result, values from these endpoints may differ very slightly. All other endpoints pull from the same live source as the dashboard and should match exactly.
The Visits by CBGs endpoint is refreshed once a week on Wednesdays.
Q: What endpoints support bulk requests?
Visit Metrics Summary Report
Visit Trends Report
Visits by CBG
Ranking Metrics for Multiple Properties
Q: What endpoints do and do not support CPOIs?
Supported:
Visit Metrics Summary Report
Visits by Hours Report
Visits by Days Report
Visits by Dwell Time Report
Visits by CBGs Report
Visit Trends by Single Property
Visits by Frequency Report
Trade Area Report
Trade Area by Drive Time Report
Trade Area Demographics Report
Visitor Journey - Favorite Places
VIsitor Journey - Favorite Chains
Not Supported:
Visit Trends
Ranking Reports
Retail Sales Reports
Q: What are flagged venues? Are those venues participating in the visits counting or ranking process?
A: There are several reasons why a POI is being flagged (for example, lack of foot traffic information, dense area, etc.). This causes unreliable visits data, which Placer prefers not to consider. Flagged venues will be returned when searching POIs or entities of a POI, but reports cannot be generated for the foot traffic of those entities. For flagged venues, you can use Nearby Activity Reports. See question on Nearby Activity Reports below for more details.
Q: What endpoints support Nearby Activity Reports?
A: There are 6 endpoints that support Nearby Activity Reports. Standard Property reports are not supported for some properties due to environmental factors beyond Placer’s control, such as dense areas and multistory buildings. For these properties, Nearby Activity reports are available. Visitation insights for Nearby Activity reports are generated using a radius ring to capture nearby visits within a set distance from the property. There is a nearbyRadius parameter that accepts 100ft, 250ft, 750ft, and 1000ft as allowed values.
Available endpoints:
Visit Metrics Summary Report
Visits by Hours Report
Visits by Days Report
Visits by Dwell Time Report
Visits by Frequency Report
Trade Area Report
Q: What endpoints support Billboards (Traffic Pins)?
Supported:
Visit Metrics Summary Report
Visits by Hours Report
Visits by Days Report
Visits by Dwell Time Report
Visits by CBGs Report
Visit Trends
Visit Trends by Single Property
Visits by Frequency Report
Trade Area Report
Trade Area by Drive Time Report
Trade Area Demographics Report
Visitor Journey - Favorite Places
Visitor Journey - Favorite Chains
Not Supported:
Ranking Reports
Retail Sales Reports
Q: What endpoints support chains?
A: Visit Trends Report