A guide to understanding various terms used in the Placer ecosystem and the Placer API
Core Concepts
| Term | Description |
|---|---|
| Entity | A Placer entity refers to a managed physical place or a group of physical places. Each entity is the subject of a separate call (unless a bulk capability is noted) and the data for each entity is stored individually. Existing entity types Venue: Individual property or location, such as a single store or restaurant. Complex: Areas that encompass multiple venues, i.e. shopping malls or business parks. Visit metrics are defined as activity within entity boundaries. Custom POI and nearby activity reports act as complex entity type Billboard (Traffic Pin): represents a specific location of an out-of-home (OOH) advertising unit, such as a billboard. It is used to analyze impressions. Impressions are defined as number of estimated people that pass the particular point on the road (defined by billboard location) and is different from visits as it counts multiple iterations per day Chain: A Placer-managed grouping of locations that are part of an identified brand, e.g. Starbucks. Chain acts as a separate entity (e.g. call for chain that has 1,000 underlying venues is considered as 1 queried POI and the data is returned in aggregated format. Chains can be nationwide or regional (State, DMA, CBSA levels) Tag: A custom collection of entities, including entities of different types (billboards, venue, chains etc.), defined as a watch list or as a favorites list. Defined by account users and is only available to specific account Different endpoints may not support each entity type; allowed entity types for the specific endpoint are referenced in each endpoint's documentation. |
| POI | Point of interest. |
| CPOI | Custom POI. POI that was created by a user using custom polygon boundaries or pre-defined ring radius size. Underlying data represents the activity within polygon boundaries |
| Tag | A custom collection of entities (billboards, venue, chains etc.), defined as a watch list or as a favorites list. |
| Visits | A visit refers to an instance when a person enters a specific location or property. It is a key metric used to measure foot traffic and analyze visitation patterns. One person can only visit a POI once per day. If the same person visits multiple times over multiple days, each is counted as a separate visit. |
Identifiers
| Term | Description |
|---|---|
| ApiId (for single entity endpoints) ApiIds (for endpoints allowing bulk) | A unique identifier that allows performing data queries. The ID format is <entityType:entityId>. Example: venue:597d121159b03f6cf8e78962. Note: there is no space between the entity type and entity ID when using an ApiId as a parameter. ApiId is string data type, ApiIds is a list (formatted as list of multiple ApiId) |
| EntityId | Unique string of 24 characters that identifies the entity. Surrogate key. Part of ApiID |
| EntityType | Part of ApiID structure, identifying the entity visit capture logic. Can be one of the following: chain, tag, venue, complex, billboard) |
Metrics
| Term | Description |
|---|---|
| Visitors | A unique person that has activity associated with POI. Number of visitors is an extrapolated number from unique mobile devices (panel) present in Placer’s data. This is different from "visits," which count the total number of times a property is visited. For example, if a person visits a grocery store once a week, they are counted as one visitor, but they generate 52 visits over a year. |
| Visits | A visit refers to an instance when a person enters a specific location or property. It is a key metric used to measure foot traffic and analyze visitation patterns. One person can only visit a POI once per day. If the same person visits multiple times over multiple days, each is counted as a separate visit. |
| estimatedFoottraffic | Similar to “Visit” for endpoints providing breakdowns (Visits by Visit by Days, Visits by Hours, Visits by Dwell Time). Can include multiple visits by same device for same day, given they would fall into multiple output bins |
| panelVisitors | Number of unique mobile devices (unique panel) visits to property that are then used for extrapolation. Raw, unextrapolated data from our mobile device panel, used as an input for our models |
| panelVisits | Number of mobile devices (panel) visits to property that are then used for extrapolation. Raw, unextrapolated data from our mobile device panel, used as an input for our models |
| CBGcode | Census Block Group (CBG) code, represented as 12 digit code (State-County-Tract-Block Group) |
Query Parameters
| Term | Description |
|---|---|
| audienceType | If provided - metrics will be calculated based on the specified types of audience. Can be visitor, employee or resident. In unspecified - displays the default audience for category that POI falls into Defaults to visitors for brick & mortar locations and employees for Offices |
| granularity | Represents the aggregation used for the output. Can be “day”, “week”, “month” or “year” |
| startDate endDate | Queried data start date. Format YYYY-MM-DD. All date range queries, regardless of programming language, are inclusive of both the start and end date. |
| trafficVolPct | The threshold for the volume of traffic coming to the property used to aggregate the True Trade Area. For example - setting a 'traffic vol' of 70% will draw a polygon that includes at home location areas for top 70% of visits. Defined as a whole number (e.g. ‘70’ = 70%). In the Placer dashboard, this setting defaults to 70%. |
Quotas
| Term | Description |
|---|---|
| queriedPOIs | The total number of unique Points of Interest (POIs) queried through any POI-related endpoints in the current weekly quota period. This helps track how many distinct POIs have been requested. Each account has a limit of the total number of entities which can be queried during a week. Consult with your Placer contact to confirm this amount or to expand your available quota. |
| usedQuota | The number of API calls the account has actually used during the current weekly quota period. Each account has a limit of the total number of calls which can be made during a week. Consult with your Placer contact to confirm this amount or to expand your available quota. |