Chain/Venue Multi-Metrics - V1.1.2
Once enabled, Placer will upload to your bucket CSVs in the schema detailed below on a daily/weekly basis.
Each row in the CSV will be provided in the Schema format detailed below.
Filenames, path and retention policy:
-
Files will be provided on Amazon Web Services (AWS) S3 or Google Cloud Storage (GCS) (see Data Access)
-
Files will be exported until midnight UTC every day.
-
File path will be as follows:
'CUSTOMER_BUCKET/SUB_FOLDER/placer-analytics/SCHEMA/EXPORT_TYPE/DATE_STRING/ENTITY_TYPE/
| Terms | Values | Description |
|---|---|---|
| CUSTOMER_BUCKET/ SUB_FOLDER | Any valid string that represents a path | The bucket and the relative in the bucket as provided in the export settings (Output/Deliver To). SUB_FOLDER could be empty. E.g. if “Deliver To” is configured to be “my-customer-bucket/incoming-files/placer”, CUSTOMER_BUCKET = “my-customer-bucket” and SUB_FOLDER = “incoming-files/placer”. |
| SCHEMA | multi-metric, single-metric | The path will also include the export SCHEMA, currently supported only “multi-metric” (default for new exports) “single-metric” (deprecated, still used for existing exports). |
| EXPORT_TYPE | daily, weekly, monthly, weekly-daily, monthly-daily, monthly-weekly | Each export has an EXPORT_TYPE that is a combination of the frequency and the aggregation. If they are the same, the type is simply the frequency. For example, a weekly export (generated once a week) with a daily level aggregation (each line represents a single day), will be defined as “weekly-daily”. If that export would have had a weekly level aggregation (each line represent a single week’s aggregated metrics), the definition would be “weekly”. |
| DATE_STRING | Date in the format YYYY-MM-DD | Feed's generation date |
| ENTITY_TYPE | chain, venue, complex or billboard | Each exported file represents an entity. And that entity has an ENTITY_TYPE. |
- Files are GZip compressed
- Files delivery is based on the feed's configuration:
a. Files are aggregated per entity (Chain/Complex/Venue/Billboard) and placed in the appropriate folder,
separating the metrics from the metadata, as shown in the following image:
If requested to include sub entities in the
report, then the chain's feed will be generated in one file and placed under the chain folder, and all the
included entities will be generated in one file and placed under the chain_entities folder, as presented in the above image.
If the feed is configured to merge the requested entities into one feed(zipped or unzipped), then the folder structure of the feed will include the custom/metrics folder for the feed file and the custom/metadata folder for the metadata file as shown on the image below:
CSV Schema Overview
| Column | Description | Type | Example |
|---|---|---|---|
| publication_date | Data publication date | ISO-8601 | 2020-08-01 |
| version_code | Calibration version code | string | 1.0.0 |
| id | Placer's entity ID | string | '5965fca0173f564b883c222e' |
| name | Entity name | string | 'Mcdonald's' |
| type | Entity type. See Location Info for a full list of supported types. | string | 'venue' |
| time_frame | Data aggregation resolution. Supported values: 'daily', 'weekly', 'monthly' and 'yearly'. | string | 'daily' |
| start_date | Data start date. | ISO-8601 | 2018-04-15 |
| end_date | Data end date (inclusive) | ISO-8601 | 2018-04-15 |
| region_type | 'nationwide', 'state', 'dma' & 'cbsa' are supported. Only available for entities of type 'chain.' Note: CBSA is the union of MSAs & micro-MSAs | string | 'nationwide' |
| region_name | Region's name | string | 'California' |
| region_code | Region's code | string | 'CA' |
| lat | The entity's latitude. Only available for entities of type 'venue' or 'complex | double | 37.786099 |
| lng | The entity's longitude. Only available for entities of type 'venue' or 'complex | double | -121.46352 |
| ticker_symbol | The stock exchange ticker symbol | string | 'MCD' |
| company_name | If available, the parent company chain name. | string | 'Mcdonald's' |
| foottraffic | Estimated foot-traffic in the location during the relevant time frame. Foot-traffic is extrapolated from the panel_visits. | integer | 5000000 |
| panel_visits | The actual number of visits generated by Placer's panel (observed visit). | integer | 50000 |
| home_distance _estimated_foottraffic_X (multiple columns) | The accumulative foottraffic generated by customer who live within 'X' miles of the property. Includes a column per distance(mi) as follows: 0.3, 0.5, 0.7, 1, 2, 3, 5, 7, 10, 30, 50, 100, 250, 250+ Example: 'home_distance _estimated_foottraffic_50' means the sum of foottraffic generated by customers who live within 50 miles of the property | integer | 40000 |
| home_distance _percentage_X (multiple columns) | The percentage of foottraffic generated by customer who live within 'X' miles of the property. Includes a column per distance(mi) as follows: 0.3, 0.5, 0.7, 1, 2, 3, 5, 7, 10, 30, 50, 100, 250, 250+ | double | 25.485 |
| work_distance _estimated_foottraffic_X (multiple columns) | The accumulative foottraffic generated by customer who work within 'X' miles of the property. Includes a column per distance(mi) as follows: 0.3, 0.5, 0.7, 1, 2, 3, 5, 7, 10, 30, 50, 100, 250, 250+ | integer | 4000 |
| work_distance _percentage_X (multiple columns) | The percentage of foottraffic generated by customer who work within 'X' miles of the property. Includes a column per distance(mi) as follows: 0.3, 0.5, 0.7, 1, 2, 3, 5, 7, 10, 30, 50, 100, 250, 250+ | double | 13.35 |
Additional Metrics
From time to time Placer may add additional metrics to the schema. They will be appended as additional columns and you will be given a 30 days note in advance with a sample file.
Sample file
Note
- Use the following files to review the delivery format structure and compression method.
- The actual delivery will include more data (more history/chains/venues).
- Files contain fake-data and therefore cannot be used for data-evaluation
Sample #1 - Daily Chain-level data for Walmart Supercenter, Only January 2017
Sample #2 - Weekly Venue-level data for a selected Applebee's store in Q1/Q2 2017
CSV serialization
We conform by the IETF informational suggestion RFC-4180
Please note the following:
- A field value may or may not be enclosed in quotes. Those are not part of the data.
- A field value may contain double-quotes and commas. When this happens, the field value is enclosed within double-quotes, and the double-quotes that are part of the value are escaped by a double-quote.
Example:
// this line represents 3 fields, where the second field has a comma, and the third has 1 double-quote in the middle:
aaa,"bb,b","cc""c"
Updated about 1 year ago