Placecast Select Responses
Response schema for a Placecast Select scenario, including the metric families, percent breakdowns, and an example JSON payload.
Each Placecast Select scenario returns a single response object carrying the scenario metadata, the cohort analyzed, the visit / dropoff / passby / activity / exposure metric families, population context, and percent breakdowns across demographic, consumer, temporal, dwell-time, and home-location dimensions. All metrics reported as percentages are rounded to the nearest tenth of a percent (25.1 is 25.1%).
Response Structure
{
"motionworks_scenario_id": "C42AA2BB-173F-423E-9AFF-518BB9D7486C",
"periods": [
{
"period_name": "2024-01-02 12:00 AM - 2024-01-02 11:45 PM",
"start_time": "2024-01-02T05:00:00+00:00",
"end_time": "2024-01-03T04:45:00+00:00"
}
],
"scenario_published": "2024-01-18T14:32:07+00:00",
"measured_places": 1,
"timezone": "America/New_York",
"cohort": {
"home_geography_ids": ["XX2020NATNUS"],
"home_geography_names": ["United States"],
"motionworks_base_segment_id": "21d529097c81af04",
"motionworks_base_segment_name": "All Persons"
},
"visits": 41200,
"visits_ci": [39100, 43300],
"visits_total": 52800,
"visits_unique": 33700,
"visits_unique_total": 43100,
"dropoffs": 8600,
"dropoffs_ci": [7900, 9300],
"dropoffs_total": 11000,
"passbys": 15400,
"passbys_ci": [14300, 16500],
"passbys_total": 19700,
"activities": 49800,
"activities_ci": [47300, 52300],
"activities_total": 63800,
"activities_unique": 39900,
"activities_unique_total": 51100,
"exposures": 65200,
"exposures_ci": [61900, 68500],
"exposures_total": 83500,
"exposures_unique": 52100,
"exposures_unique_total": 66700,
"exposures_visitors": 58400,
"event_minutes_visitors": 2870000,
"total_event_minutes": 3120000,
"population": {
"persons": 41200,
"persons_at_work": 5100,
"persons_at_home": 3300
},
"percent": {
"dwell_bins": [
{"id": "exposures_dwell_000_030min", "description": "Less than 30 minutes", "value": 0.5456},
{"id": "exposures_dwell_030_060min", "description": "30 minutes to 59 minutes", "value": 0.2342},
{"id": "exposures_dwell_060_120min", "description": "1 hour to 1 hour 59 minutes", "value": 0.1689},
{"id": "exposures_dwell_120_240min", "description": "2 hours to 3 hours 59 minutes", "value": 0.0272},
{"id": "exposures_dwell_240min_plus", "description": "4 hours or more", "value": 0.0241}
],
"dwell_plus": [
{"id": "exposures_dwell_05min_plus", "description": "5 minutes or more", "value": 0.8734},
{"id": "exposures_dwell_10min_plus", "description": "10 minutes or more", "value": 0.7912},
{"id": "exposures_dwell_20min_plus", "description": "20 minutes or more", "value": 0.6103}
],
"event_time_plus": [
{"id": "visits_dwell_00min_plus_event_minutes", "description": "Any event time", "value": 1.0000},
{"id": "visits_dwell_05min_plus_event_minutes", "description": "5 minutes or more of event time", "value": 0.8641},
{"id": "visits_dwell_10min_plus_event_minutes", "description": "10 minutes or more of event time", "value": 0.7788},
{"id": "visits_dwell_20min_plus_event_minutes", "description": "20 minutes or more of event time", "value": 0.5934}
],
"day": [
{"id": "1", "description": "Sunday", "value": 0.182},
{"id": "7", "description": "Saturday", "value": 0.201}
],
"date": [
{"id": "2024-01-02", "description": "2024-01-02", "value": 1.000}
],
"segment": {
"basic_demographics": [
{
"category": "age",
"segments": [
{
"description": "Population, Age 0 - 17",
"exposure_index": 1.24,
"activity_index": 1.25,
"visits_index": 1.28,
"exposure_penetration": 0.2748,
"activity_penetration": 0.2750,
"visits_penetration": 0.2821,
"market_persons": 380000000,
"motionworks_segment_id": "c3649875967afb92"
}
]
}
],
"consumer": [
{
"category": "restaurants",
"segments": [
{
"description": "Visited a fast food restaurant in last 30 days",
"exposure_index": 1.12,
"activity_index": 1.11,
"visits_index": 1.14,
"exposure_penetration": 0.4821,
"activity_penetration": 0.4810,
"visits_penetration": 0.4933,
"market_persons": 210000000,
"motionworks_segment_id": "9f1c7d0a4b2e6a35"
}
]
}
]
},
"home": {
"state_province": [
{"id": "50", "alias": "VT", "description": "Vermont", "value": 0.252},
{"id": "33", "alias": "NH", "description": "New Hampshire", "value": 0.137}
],
"dma": [
{"id": "504", "description": "Philadelphia", "value": 0.311}
],
"metro_area": [
{"id": "37980", "description": "Philadelphia-Camden-Wilmington, PA-NJ-DE-MD", "value": 0.288}
],
"county": [
{"id": "34001", "description": "Atlantic County, NJ", "value": 0.164}
],
"postal_code": [
{"id": "08401", "description": "08401", "value": 0.092}
],
"census_neighborhood": [
{"id": "340010001001", "description": "340010001001", "value": 0.031}
]
}
},
"qualified": true,
"qa_flag": "GOOD",
"messages": {
"message": "Passed - Good Confidence",
"dropped_places": []
}
}Schema
| Name | Description | Type | Example |
|---|---|---|---|
| motionworks_scenario_id | Unique identifier for the scenario across Motionworks systems (echoed from request). | STRING | C42AA2BB-173F-423E-9AFF-518BB9D7486C |
| periods | Reporting time period(s): period_name, start_time, end_time (ISO-8601). | RECORD (repeated) | See example above |
| scenario_published | Timestamp when Placecast Select finished the scenario (ISO-8601). | STRING | 2024-01-18T14:32:07+00:00 |
| measured_places | Number of places measured (valid, focused Motionworks places). | INTEGER | 1 |
| timezone | Timezone used for day-of-week and hour-of-day reporting. | STRING | America/New_York |
| cohort | Base cohort analyzed. | RECORD | See below |
| cohort. home_geography_ids | Home geography identifiers scoping the cohort (echoed from request). | array of strings | ["XX2020NATNUS"] |
| cohort. home_geography_names | Human-readable names for the home geographies. | array of strings | ["United States"] |
| cohort. motionworks_base_segment_id | Identifier of the base segment against which indices are computed. | STRING | 21d529097c81af04 |
| cohort. motionworks_base_segment_name | Name of the base segment. | STRING | All Persons |
| visits | Visit events by persons matching the cohort and home geography. A visit is an activity with dwell time at or above the place's dwell threshold. | INTEGER | 41200 |
| visits_ci | 95% confidence interval (Binomial Wilson), [lower, upper]. | ARRAY<INT64> | [39100, 43300] |
| visits_total | Visit events regardless of home geography or cohort. | INTEGER | 52800 |
| visits_unique | Unique persons visiting, matching the cohort. | INTEGER | 33700 |
| visits_unique_total | Unique persons visiting, regardless of cohort. | INTEGER | 43100 |
| dropoffs | Dropoff events (dwell greater than 0 but below the dwell threshold), matching the cohort. | INTEGER | 8600 |
| dropoffs_ci | 95% confidence interval, [lower, upper]. | ARRAY<INT64> | [7900, 9300] |
| dropoffs_total | Dropoff events regardless of cohort. | INTEGER | 11000 |
| passbys | Pass-by events (zero dwell time; not an activity), matching the cohort. | INTEGER | 15400 |
| passbys_ci | 95% confidence interval, [lower, upper]. | ARRAY<INT64> | [14300, 16500] |
| passbys_total | Pass-by events regardless of cohort. | INTEGER | 19700 |
| activities | Activities = visits + dropoffs (differentiated by the dwell threshold), matching the cohort. | INTEGER | 49800 |
| activities_ci | 95% confidence interval, [lower, upper]. | ARRAY<INT64> | [47300, 52300] |
| activities_total | Activities regardless of cohort. | INTEGER | 63800 |
| activities_unique | Unique persons with an activity, matching the cohort. | INTEGER | 39900 |
| activities_unique_total | Unique persons with an activity, regardless of cohort. | INTEGER | 51100 |
| exposures | Exposures = visits + dropoffs + pass-bys, matching the cohort. | INTEGER | 65200 |
| exposures_ci | 95% confidence interval, [lower, upper]. | ARRAY<INT64> | [61900, 68500] |
| exposures_total | Exposures regardless of cohort. | INTEGER | 83500 |
| exposures_unique | Unique persons with an exposure, matching the cohort. | INTEGER | 52100 |
| exposures_unique_total | Unique persons with an exposure, regardless of cohort. | INTEGER | 66700 |
| exposures_visitors | Exposures by visitors (non-workers, non-residents) matching the cohort. | INTEGER | 58400 |
| event_minutes_visitors | Sum of event minutes for visitor exposures matching the cohort. (Event minutes = the activity's overlap with the scenario period, vs dwell = full activity duration.) | INTEGER | 2870000 |
| total_event_minutes | Total event minutes across the scenario. | INTEGER | 3120000 |
| population | Population context: persons, persons at work, and persons at home (residents). | JSON | {"persons":41200,"persons_at_work":5100,"persons_at_home":3300} |
| percent | Percent breakdowns by dimension (see below). Within a mutually-exclusive dimension the values sum to ~100 (rounding aside). | JSON | See below |
| percent. dwell_bins | Per-exposure dwell-time buckets (exposures_dwell_*), as a share of all exposures. | array of objects | {"id":"exposures_dwell_000_030min", ...} |
| percent. dwell_plus | Cumulative dwell-time thresholds (exposures_dwell_NNmin_plus): share of exposures at or above each dwell length. | array of objects | {"id":"exposures_dwell_05min_plus", ...} |
| percent. event_time_plus | Cumulative event-time thresholds (visits_dwell_NNmin_plus_event_minutes): share of visit event-minutes at or above each threshold. | array of objects | {"id":"visits_dwell_05min_plus_event_minutes", ...} |
| percent. day | Share of activity by day of week. | array of objects | {"id":"7","description":"Saturday","value":0.201} |
| percent. date | Share of activity by calendar date. | array of objects | {"id":"2024-01-02","value":1.000} |
| percent. segment | Demographic and consumer segment breakdowns, grouped into basic_demographics and consumer. | object | See below |
| percent.segment. basic_demographics | Array of categories (age, age_plus, hh_income, race, gender, ethnicity, prizm). Each category holds segments[] with description, exposure_index, activity_index, visits_index, exposure_penetration, activity_penetration, visits_penetration, market_persons, and motionworks_segment_id. | array of objects | See example above |
| percent.segment. consumer | Array of consumer categories (alcohol, automotive, restaurants, travel, …). Same per-segment shape as basic_demographics; only the most relevant segments are returned. | array of objects | See example above |
| percent. home | Home-location breakdowns of guests. | object | See below |
| percent.home. state_province | Share by state/province. Labeled by 2-digit FIPS code (with leading zeros); includes alias. | array of objects | {"id":"50","alias":"VT","description":"Vermont","value":0.252} |
| percent.home. dma | Share by DMA. Labeled by DMA identifier. | array of objects | {"id":"504","description":"Philadelphia","value":0.311} |
| percent.home. metro_area | Share by metro area. Labeled by core-based statistical area (CBSA) identifier. | array of objects | {"id":"37980", ...} |
| percent.home. county | Share by county. Labeled by 5-digit county FIPS code (with leading zeros). | array of objects | {"id":"34001", ...} |
| percent.home. postal_code | Share by postal code. Labeled by 5-digit postal code. | array of objects | {"id":"08401","value":0.092} |
| percent.home. census_neighborhood | Share by neighborhood. Labeled by block group's 12-digit FIPS (US) or dissemination area's 8-digit id (Canada). | array of objects | {"id":"340010001001","value":0.031} |
| debug_internal | Internal diagnostics: runtime version, timestamps, device/place multiplier counts, and quality scores/tier/message. | RECORD | See Data Interpretation |
| qualified | Whether the scenario passed the quality gate and produced usable metrics. | BOOLEAN | true |
| qa_flag | Quality tier for the scenario. | STRING | GOOD |
| messages | message (values below) and dropped_places (place IDs dropped for being invalid or unfocused). | RECORD | {"message":"Passed - Good Confidence","dropped_places":[]} |
Data Interpretation
Visits are not occupancy. visits, activities, and exposures count events by measured persons scaled to population; they are not headcounts of everyone present. A person who arrives and leaves several times over a period contributes several events. Use visits_unique / activities_unique / exposures_unique for distinct-person counts.
Metric families and thresholds. Exposures = visits + dropoffs + pass-bys. Activities = visits + dropoffs (a dropoff has dwell greater than 0 but below the place's dwell threshold; a visit meets or exceeds it). Pass-bys are zero-dwell and are not activities. dwell_plus and event_time_plus are cumulative, so each higher threshold is a subset of the lower one (e.g. dwell_20min_plus ≤ dwell_10min_plus ≤ dwell_05min_plus).
Confidence intervals (*_ci). Each *_ci field is a 95% confidence interval computed with the Binomial Wilson method and returned as [lower, upper]. *_ci fields are only populated when include_confidence_interval was set on the request. Wider intervals indicate a smaller observed device sample behind the estimate.
Cohort vs total. Non-_total metrics are filtered to the requested cohort and home geography and are only populated when include_cohort_metrics was set on the request. _total metrics count events regardless of cohort or home geography.
Quality gate — qualified and qa_flag. qa_flag carries the quality tier; when the tier is BAD (or a period violates the runtime version's date floor), qualified is false and all metric fields are returned as null. debug_internal exposes the component quality scores (device sample, place coverage, temporal completeness, multiplier stability) and the composite behind the tier.
messages.message values. On success: Passed - High Confidence, Passed - Good Confidence, Passed - Fair Confidence, or Passed - No quality tier assigned. A . Note: <Visit|Passby|Dropoff> estimates carry higher uncertainty suffix may be appended when the corresponding additive factor is negative. When the scenario runs but does not clear the quality bar (qualified = false): Failed - Insufficient data: expand the place set or extend the measurement window, Failed - Below quality threshold, or Failed - Assessment incomplete. On input error: Error: No places provided - add at least one place to the scenario, Error: No focused places in set - at least one place must be marked as focused, Error: No valid places in set - verify place IDs and geocoding, Error: Scenario period starts before <date> - runtime version <version> only supports periods starting on or after <date>, Error: Insufficient data to complete measurement - add places or extend the time period, or Error: Invalid geographic identifier - verify blockgroup format.
Updated about 14 hours ago