API Reference

Use Case: Campaign Impact Measurement

Business Challenge

Proving campaign effectiveness and measuring true audience impact requires more than impressions and reach estimates. Marketers need to demonstrate actual audience behavior change, foot traffic lift, and ROI using real population movement data to validate media investments and optimize future campaigns.

Common Scenarios:

  • Out-of-home advertisers measuring foot traffic lift to advertised locations
  • Retail brands tracking store visitation increases during advertising campaigns
  • Restaurants measuring customer acquisition from targeted media campaigns
  • Event promoters analyzing attendance lift from advertising efforts
  • Media agencies proving campaign effectiveness to clients with actual audience behavior data

Required Inputs

  • Campaign Details: Flight dates, media placements, target audience definitions
  • Measurement Locations: Place IDs for stores, venues, or destinations being promoted
  • Baseline Period: Pre-campaign timeframe for comparison analysis
  • Target Demographics: Audience segments most likely to respond to campaign
  • Success Metrics: KPIs such as visitation lift, new customer acquisition, or audience engagement

API Workflow

Step 1: Establish Baseline Performance

Measure pre-campaign audience behavior and visitation patterns to establish performance benchmarks.

API Call: POST /measures/placecast/report
→ API Documentation: Placecast Profiles

{
    "place_id": [1234, 1235, 1236]
}

Baseline Metrics from Response:

  • Visitor Volume: visits, visits_unique_persons, activities
  • Audience Demographics: segments array with percent and index values
  • Geographic Distribution: county, dma, state arrays with weekly_visits
  • Temporal Patterns: days array with hourly patterns and dwell distribution
  • Engagement Metrics: visits_avg_dwell and visits_frequency_per_person

Response Structure (baseline metrics):

{
    "places": [
        {
            "name": "Campaign Measurement Locations",
            "place_id": [1234, 1235, 1236],
            "activities": 2127778,
            "visits": 1693268,
            "visits_unique_persons": 1169734,
            "visits_avg_dwell": 184,
            "visits_frequency_per_person": 1.45,
            ...
        }
    ],
    "place_count": 3,
    "segments": [
        {
            "type": "consumer",
            "category": "shopping_behavior",
            "description": "Frequent retail shopper",
            "id": "shop_001",
            "percent": 0.234,
            "index": 156,
            "motionworks_segment_id": "abc123-segment-id"
        }
        ...
    ],
    "county": [...],
    "dma": [...],
    "state": [...],
    "days": [...],
    "dwell": [...],
    ...
}

Step 2: Define Target Audience Cohorts

Identify specific audience segments that align with campaign targeting for precise measurement.

API Call: POST /cohorts/search
→ API Documentation: Popcast API

{
    "motionworks_data_product_name": "Popcast At Home",
    "search_text": "retail shopping"
}

Response Structure:

{
    "cohorts": [
        {
            "motionworks_segment_id": "b2862ed4-68c9-4124-971b-1c8e03362451",
            "cohort_description": "Frequent retail shopper past 30 days"
        }
        ...
    ]
}

Step 3: Track Campaign Period Performance

Monitor audience behavior and visitation patterns during active campaign flights using the same measurement approach.

API Call: POST /measures/placecast/report
→ API Documentation: Placecast Profiles

Note: The Placecast Profiles API provides the most recent data available. For historical period analysis, you would make this same call during the campaign period to capture that timeframe's data.

{
    "place_id": [1234, 1235, 1236]
}

Campaign Period Monitoring:

  • Daily Visitation Changes: Compare current visits to baseline
  • Audience Composition Shifts: Changes in segments percentages and indices
  • Geographic Response: Variations in county and dma visitor distributions
  • Engagement Pattern Changes: Differences in dwell and temporal patterns

Step 4: Analyze Target Cohort Geographic Presence

Use Popcast At Home to understand where your target audience is concentrated geographically.

API Call: POST /measures/popcast/at_home
→ API Documentation: Popcast API

{
    "motionworks_segment_id": "b2862ed4-68c9-4124-971b-1c8e03362451",
    "geography_type": ["DMA"]
}

Response Structure:

{
    "motionworks_segment_id": "b2862ed4-68c9-4124-971b-1c8e03362451",
    "geographic_type": ["DMA"],
    "customer_segment_name": "Frequent retail shopper past 30 days",
    "year": 2022,
    "persons": 45200906,
    "all_persons": 333633487,
    "composition_percent": 0.13548072289278323,
    "results": [
        {
            "geography_id": "US2020XDMA501",
            "description": "New York, NY",
            "persons": 3917399,
            "all_persons": 22015625,
            "composition_index": 131,
            "composition_percent": 0.177937215046132,
            "geo_type": "DMA",
            "customer_segment_name": "Frequent retail shopper past 30 days",
            "vintage": "20230909"
        }
        ...
    ],
    "ids": [...],
    "vintage": "20230909",
    "pagination": {...}
}

Step 5: Measure Post-Campaign Impact

Assess sustained impact and behavior changes following campaign completion using the same Placecast measurement approach.

Implementation Note: Campaign lift measurement requires collecting baseline data before the campaign, during the campaign, and after campaign completion, then calculating the differences to determine attributed lift.

Lift Calculation Framework:

  • Baseline Performance: Pre-campaign visitor metrics
  • Campaign Performance: During-campaign visitor metrics
  • Post-Campaign Performance: Sustained behavior changes
  • Statistical Validation: Compare results to control markets or historical trends

Expected Outputs

Campaign Performance Report

  • Visitation Lift: Quantified increase in foot traffic during campaign period
  • Audience Impact: Demographic and behavioral changes in visitor composition
  • Geographic Performance: Market-by-market campaign effectiveness based on DMA analysis
  • Temporal Analysis: How campaign impact varied over time and sustained post-campaign

ROI Analysis

  • Cost Per Visit: Campaign cost divided by incremental visits generated
  • Customer Acquisition Cost: Cost to acquire new visitors/customers during campaign
  • Audience Quality Assessment: Changes in visitor engagement and dwell time
  • Media Efficiency: Performance comparison across different campaign elements

Strategic Insights

  • Audience Optimization: Which demographic segments (segments with highest index scores) responded best
  • Geographic Effectiveness: Markets showing strongest visitation increases
  • Engagement Patterns: Changes in visits_avg_dwell and temporal visit patterns
  • Long-term Impact: Sustained changes in visitor behavior post-campaign

Business Application

Campaign Optimization

Use real-time performance data to optimize active campaigns and improve results.

Optimization Strategies:

  • Geographic Reallocation: Focus budget on markets showing strongest response
  • Audience Refinement: Target demographic segments with highest engagement
  • Timing Optimization: Adjust campaign flights based on optimal visitor response periods
  • Location Selection: Prioritize measurement locations showing strongest lift

Future Campaign Planning

Apply learnings from measured campaigns to improve future media investments.

Strategic Applications:

  • Audience Targeting: Refine target segments based on proven response patterns
  • Market Selection: Prioritize markets that showed strongest campaign lift
  • Budget Allocation: Distribute investment based on demonstrated ROI by market
  • Campaign Structure: Optimize flight patterns based on visitor response data

Client Reporting and Business Development

Use population intelligence to demonstrate campaign value and win future business.

Reporting Framework:

  • Executive Dashboards: High-level campaign performance and visitor lift metrics
  • Detailed Analysis: Granular audience behavior and response patterns
  • Competitive Benchmarking: How campaign performance compares to market baselines
  • Success Stories: Case studies demonstrating proven campaign effectiveness

Out-of-Home Advertising Applications

Measure billboard and digital display campaign effectiveness using population movement data.

Strategic Applications:

  • Foot Traffic Attribution: Measure incremental store visits generated by billboard campaigns using baseline vs. campaign period visitor volumes
  • Audience Delivery Verification: Validate billboard audience delivery against campaign targets using actual demographic data from segments arrays
  • Cross-Media Attribution: Analyze how billboard campaigns complement digital and traditional media using geographic visitor pattern changes
  • Campaign Optimization: Use real-time visitor lift data to optimize billboard creative rotation, scheduling, and geographic allocation during active campaigns

Related Use Cases

Technical Resources