API Reference

Use Case: Site Selection & Trade Area Analysis

Business Challenge

Making informed location decisions requires understanding the true audience potential of a site before significant investment. Traditional site selection relies on demographic estimates and theoretical trade areas, while population intelligence provides actual movement patterns, visitor demographics, and proven trade area boundaries based on real behavior.

Common Scenarios:

  • Retailers evaluating new store locations based on actual foot traffic potential
  • Restaurants analyzing neighborhood demographics and dining patterns
  • Healthcare providers understanding patient population and access patterns
  • Banks assessing branch locations based on customer movement and banking behaviors
  • Developers evaluating mixed-use project potential based on area activity patterns

Required Inputs

  • Potential Location Coordinates: Latitude/longitude for proposed sites
  • Market Boundary: Geographic area for analysis (radius, county, custom polygon)
  • Comparison Criteria: Similar locations or competitor sites for benchmarking
  • Business Requirements: Target demographics, visitor volume thresholds, trade area size

API Workflow

Step 1: Identify Target Demographics

Define the audience characteristics most valuable to your business model.

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 2: Analyze Market Demographics

Understand population characteristics in your target market area using Popcast At Home.

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

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

Key Analysis Points:

  • Population density by market (persons and composition_index)
  • Demographic concentration (composition_percent above market average)
  • Geographic distribution across DMAs or MSAs
  • Market penetration opportunities (composition_index > 100)

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 3: Find Similar Existing Locations

Identify comparable locations in your target market to understand performance benchmarks.

API Call: POST /msearch
→ API Documentation: Places API

{
    "filter": {
        "place_name": "shopping center",
        "city": "New York",
        "state": "NY"
    },
    "pagination": {
        "page": 1,
        "page_size": 20
    },
    "sort": {
        "active": "place_name",
        "direction": "asc"
    }
}

Response Structure:

{
    "status": "success",
    "data": {
        "results": [
            {
                "place_id": "318105",
                "place_name": "Manhattan Shopping Center",
                "place_type_name": "Shopping Mall",
                "street_address": "123 Broadway",
                "city": "New York",
                "state": "NY",
                "zip_code": "10001",
                "dma_id": "501",
                "dma_name": "New York, NY",
                ...
            }
            ...
        ],
        "pagination": {
            "page": 1,
            "page_size": 20,
            "total_results": 45,
            "total_pages": 3
        }
    }
}

Location Discovery Analysis:

  • Find existing locations with similar business models
  • Identify successful locations in target demographics
  • Map competitive landscape and market gaps
  • Collect place IDs for further analysis

Step 4: Analyze Comparable Location Performance

Use Placecast Profiles to understand visitor patterns at similar existing locations.

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

{
    "place_id": [318105, 318107, 318108]
}

Response Structure (key performance metrics):

{
    "places": [
        {
            "name": "Aggregated Shopping Centers",
            "place_id": [318105, 318107, 318108],
            "activities": 2127778,
            "visits": 1693268,
            "visits_unique_persons": 1169734,
            "visits_avg_dwell": 184,
            ...
        }
    ],
    "place_count": 3,
    "segments": [
        {
            "type": "consumer",
            "category": "shopping_behavior",
            "description": "Frequent retail shopper",
            "id": "shop_001",
            "percent": 0.234,
            "index": 156,
            "motionworks_segment_id": "segment-uuid-here"
        }
        ...
    ],
    "county": [...],
    "dma": [...],
    "postal_code": [...],
    ...
}

Key Metrics:

  • Visitor volume: visits and visits_unique_persons
  • Engagement quality: visits_avg_dwell and activities
  • Demographic match: segments array with index scores
  • Trade area definition: Geographic distribution in county, dma, postal_code arrays

Step 5: Map Actual Trade Areas

Analyze visitor origin patterns to understand realistic trade area boundaries.

Trade Area Analysis (from Placecast response geographic arrays):
The response includes multiple geographic distribution arrays:

  • county array: County-level visitor origins
  • postal_code array: ZIP code visitor distribution
  • dma array: Media market visitor patterns
  • state array: State-level visitor origins

Each contains weekly_visits and daily_visits for trade area mapping.

Trade Area Definition:

  • Primary Trade Area: Geographic areas providing 60-70% of visitors
  • Secondary Trade Area: Areas contributing 20-30% of visitor volume
  • Travel Patterns: ZIP codes and counties with highest weekly_visits
  • Market Penetration: daily_visits density by geographic area

Expected Outputs

Site Evaluation Report

  • Market Opportunity Score: Quantified potential based on population and activity data
  • Trade Area Mapping: Geographic boundaries with visitor volume projections
  • Demographic Analysis: Target audience presence and characteristics
  • Competitive Assessment: Market saturation and differentiation opportunities

Strategic Recommendations

  • Location Ranking: Prioritized list of potential sites with performance projections
  • Market Entry Strategy: Optimal timing and positioning recommendations
  • Trade Area Optimization: Geographic focus areas for marketing and operations
  • Risk Assessment: Market challenges and mitigation strategies

Investment Intelligence

  • ROI Projections: Expected performance based on population intelligence
  • Market Validation: Data-driven confirmation of location viability
  • Expansion Strategy: Systematic approach to multi-location growth
  • Portfolio Optimization: How new locations complement existing sites

Business Application

Site Selection Process

Replace demographic assumptions with actual population movement and behavior data for location decisions.

Implementation Framework:

  • Market Screening: Use population density and demographic filters to identify viable markets
  • Site Evaluation: Score potential locations based on visitor potential and target audience match
  • Trade Area Analysis: Define realistic market boundaries for business planning
  • Competitive Intelligence: Understand market dynamics and positioning opportunities

Business Planning

Use population intelligence for accurate market sizing and business projections.

Planning Applications:

  • Revenue Forecasting: Base projections on actual visitor volume potential from comparable locations
  • Market Sizing: Quantify addressable market based on population and behavior data
  • Marketing Budget: Allocate resources based on trade area insights and audience concentration
  • Operational Planning: Staff and inventory planning based on projected visitor patterns

Risk Mitigation

Reduce location investment risk through data-driven market validation.

Risk Factors Analysis:

  • Market Saturation: Competitive density and market capacity
  • Demographic Shifts: Population trends that could impact long-term viability
  • Accessibility Changes: Transportation and development factors affecting visitor access
  • Economic Indicators: Market economic health and consumer spending patterns

Out-of-Home Advertising Applications

Evaluate billboard and digital display location potential using population intelligence.

Strategic Applications:

  • Billboard Site Selection: Assess new billboard locations based on actual traffic patterns and demographic alignment with advertiser targets
  • Market Entry Analysis: Use population density and composition_index data to identify high-value markets for billboard expansion
  • Competitive Gap Analysis: Identify underserved markets with high audience potential but limited existing billboard inventory
  • ROI Forecasting: Project billboard performance using comparable location visitor volumes and demographic match rates

Related Use Cases

Technical Resources