Set Dynamics scenarios are submitted as JSON requests that define the advertising inventory, target audience, geographic market, and analysis parameters. Each request triggers a comprehensive reach and frequency analysis.

Request Structure

{
    "created_timestamp": "2024-10-26T14:30:00-05:00",
    "type_list": ["lts_freq_per_period", "ots_freq_per_period"],
    "periods": {
        "name": "spring_2024",
        "start_date": "2024-02-19",
        "end_date": "2024-05-19"
    },
    "customer": {
        "customer_id": 125,
        "customer_name": "Geopath",
        "customer_scenario_id": "4db7092ff5df9ff7c9b2e431b1d18616",
        "customer_scenario_name": "National Billboard Campaign Analysis",
        "customer_scenario_info": "Q2 2024 reach analysis for premium billboard inventory"
    },
    "cohort": {
        "customer_segment_id": 2035,
        "customer_base_segement_id": 9330,
        "geography_ids": ["US2020XDMA524", "US2020XDMA501"]
    },
    "effective_freq_list": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 20, 50, 100],
    "duration_list": [7, 14, 21, 28],
    "geopath_spot_list": ["351760", "31090438", "30905792"]
}

Field Specifications

created_timestamp

Type: String (ISO 8601)
Required: Yes
Description: UTC timestamp when the scenario request was created.
Example: "2024-10-26T14:30:00-05:00"

type_list

Type: Array of strings
Required: Yes
Description: Specifies which out-of-home exposure measures to include in the analysis. Multiple measures can be requested simultaneously.

Valid Values:

• "visits_freq_per_period": Visits - Basic presence measurement
• "circ_freq_per_period": Circulation - Visits adjusted for occupancy
• "ots_freq_per_period": Opportunity to See - Circulation adjusted for dwell time
• "lts_freq_per_period": Likelihood to See - OTS adjusted by VAI
• "traffic_freq_per_period": Deprecated, use visits_freq_per_period

Default: ["visits_freq_per_period"] if omitted

periods

Type: Object
Required: Yes
Description: Defines the time window for analysis.

periods.name

Type: String
Required: Yes
Description: User-defined identifier for the analysis period.
Example: "spring_2024"

periods.start_date

Type: String (YYYY-MM-DD)
Required: Yes
Description: Analysis start date. Must be a Monday; if not, will be adjusted to the preceding Monday.
Example: "2024-02-19"

periods.end_date

Type: String (YYYY-MM-DD)
Required: Yes
Description: Analysis end date. Must be a Sunday; if not, will be adjusted to the following Sunday.
Example: "2024-05-19"

customer

Type: Object
Required: Yes
Description: Customer identification and scenario metadata.

customer.customer_id

Type: Integer
Required: Yes
Description: Motionworks customer identification number.
Example: 125 (Geopath)

customer.customer_name

Type: String
Required: Yes
Description: Customer organization name.
Example: "Geopath"

customer.customer_scenario_id

Type: String
Required: Yes
Description: Unique identifier for this scenario, used for tracking and reference.
Example: "4db7092ff5df9ff7c9b2e431b1d18616"

customer.customer_scenario_name

Type: String
Required: No
Description: Human-readable name for the scenario.
Example: "National Billboard Campaign Analysis"

customer.customer_scenario_info

Type: String
Required: No
Description: Additional notes or description about the scenario.
Example: "Q2 2024 reach analysis for premium billboard inventory"

cohort

Type: Object
Required: Yes
Description: Defines the target audience and geographic scope for analysis.

cohort.customer_segment_id

Type: Integer
Required: Yes
Description: Consumer demographic segment to analyze. Can be total population or specific consumer interests.
Example: 2035

cohort.customer_base_segement_id

Type: Integer
Required: Yes
Description: Base age segment for analysis (0+, 5+, 18+, 21+).
Example: 9330 (All persons 0+)

cohort.geography_ids

Type: Array of strings
Required: Yes
Description: Geographic markets to include in analysis. Can be counties, DMAs, metros, or national.
Examples:

• ["GLOBAL"] - National analysis
• ["US2020XDMA524"] - Atlanta DMA
• ["US2020XCO13121", "US2020XCO13135"] - Multiple counties

effective_freq_list

Type: Array of integers
Required: No
Description: Frequency thresholds for effective reach calculation (e.g., reach at 3+ frequency).
Default: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 20, 50, 100]
Example: [1, 3, 5, 10]

duration_list

Type: Array of integers
Required: No
Description: Analysis periods in days within the overall time window. Must be multiples of 7 (weeks).
Valid Values: [7, 14, 21, 28]
Default: Full period if omitted
Example: [7, 14, 28]

geopath_spot_list

Type: Array of strings
Required: Yes
Description: List of Geopath spot IDs to include in the scenario. Spots represent individual advertising displays from the Geopath inventory.
Example: ["351760", "31090438", "30905792"]

Validation Rules

• Date alignment: Start dates are adjusted to Mondays, end dates to Sundays
• Duration constraints: All duration values must be ≤ total period length
• Geographic validity: All geography IDs must exist in the Motionworks geography library
• Spot availability: All spot IDs must be active in the current Geopath inventory
• Segment compatibility: Segment IDs must be valid for the specified customer

Submission

Requests are submitted as JSONL files via cloud data storage
Each line in the JSONL file represents a separate scenario request. Multiple scenarios can be processed in a single batch submission.