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

NameDescriptionTypeExample
motionworks_scenario_idUnique identifier for the scenario across Motionworks systems (echoed from request).STRINGC42AA2BB-173F-423E-9AFF-518BB9D7486C
periodsReporting time period(s): period_name, start_time, end_time (ISO-8601).RECORD (repeated)See example above
scenario_publishedTimestamp when Placecast Select finished the scenario (ISO-8601).STRING2024-01-18T14:32:07+00:00
measured_placesNumber of places measured (valid, focused Motionworks places).INTEGER1
timezoneTimezone used for day-of-week and hour-of-day reporting.STRINGAmerica/New_York
cohortBase cohort analyzed.RECORDSee 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.STRING21d529097c81af04
cohort.
motionworks_base_segment_name
Name of the base segment.STRINGAll Persons
visitsVisit 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.INTEGER41200
visits_ci95% confidence interval (Binomial Wilson), [lower, upper].ARRAY<INT64>[39100, 43300]
visits_totalVisit events regardless of home geography or cohort.INTEGER52800
visits_uniqueUnique persons visiting, matching the cohort.INTEGER33700
visits_unique_totalUnique persons visiting, regardless of cohort.INTEGER43100
dropoffsDropoff events (dwell greater than 0 but below the dwell threshold), matching the cohort.INTEGER8600
dropoffs_ci95% confidence interval, [lower, upper].ARRAY<INT64>[7900, 9300]
dropoffs_totalDropoff events regardless of cohort.INTEGER11000
passbysPass-by events (zero dwell time; not an activity), matching the cohort.INTEGER15400
passbys_ci95% confidence interval, [lower, upper].ARRAY<INT64>[14300, 16500]
passbys_totalPass-by events regardless of cohort.INTEGER19700
activitiesActivities = visits + dropoffs (differentiated by the dwell threshold), matching the cohort.INTEGER49800
activities_ci95% confidence interval, [lower, upper].ARRAY<INT64>[47300, 52300]
activities_totalActivities regardless of cohort.INTEGER63800
activities_uniqueUnique persons with an activity, matching the cohort.INTEGER39900
activities_unique_totalUnique persons with an activity, regardless of cohort.INTEGER51100
exposuresExposures = visits + dropoffs + pass-bys, matching the cohort.INTEGER65200
exposures_ci95% confidence interval, [lower, upper].ARRAY<INT64>[61900, 68500]
exposures_totalExposures regardless of cohort.INTEGER83500
exposures_uniqueUnique persons with an exposure, matching the cohort.INTEGER52100
exposures_unique_totalUnique persons with an exposure, regardless of cohort.INTEGER66700
exposures_visitorsExposures by visitors (non-workers, non-residents) matching the cohort.INTEGER58400
event_minutes_visitorsSum of event minutes for visitor exposures matching the cohort. (Event minutes = the activity's overlap with the scenario period, vs dwell = full activity duration.)INTEGER2870000
total_event_minutesTotal event minutes across the scenario.INTEGER3120000
populationPopulation context: persons, persons at work, and persons at home (residents).JSON{"persons":41200,"persons_at_work":5100,"persons_at_home":3300}
percentPercent breakdowns by dimension (see below). Within a mutually-exclusive dimension the values sum to ~100 (rounding aside).JSONSee 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.objectSee 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 objectsSee 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 objectsSee example above
percent.
home
Home-location breakdowns of guests.objectSee 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_internalInternal diagnostics: runtime version, timestamps, device/place multiplier counts, and quality scores/tier/message.RECORDSee Data Interpretation
qualifiedWhether the scenario passed the quality gate and produced usable metrics.BOOLEANtrue
qa_flagQuality tier for the scenario.STRINGGOOD
messagesmessage (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_plusdwell_10min_plusdwell_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.


Did this page help you?