Viewcast Spot

Endpoint

POST /measures/viewcast/spot

Report on detailed spot-level data including historical measurements, circulation patterns, and geographic context. This call will gather comprehensive data for specific spots, providing detailed measurement history, circulation patterns by day of week and hour, market information, and physical characteristics of the advertising face.

Type

POST

Request Parameters

Required
- spots: array of integers representing spot ids

Responses

200 OK: Successfully retrieved report
400 Bad Request: Issue with input parameters to request
404 Not Found: No spots requested were found

Response includes:

results: Array of spot objects containing detailed information for each requested spot
spot_id: The unique identifier for the spot (advertisement)
place_id: Corresponding Motionworks Place ID for the Face (display location)
location: Geographic coordinates in POINT format
market: Geographic market information including county, CBSA, DMA, and postal code identifiers
Physical characteristics: construction_type, classification_type, media_type, digital flag, face dimensions and orientation
Measurement data: Current period traffic (synonym for visits), circulation (person-exposures), impressions, and dwell time
history: Historical measurement data organized by year and month, extending back to 2019
- Year-level aggregates with annual traffic, circulation, and impression totals
- Month-level data showing monthly variations and trends over time
percent_circ: Circulation distribution patterns showing how impressions are distributed across:
- Days of the week (Monday through Sunday)
- Hours of the day (24-hour breakdown) for each day
- Values represent the percentage of total weekly circulation occurring during each time period
assignment_status: Current assignment status in the system (Industry Assigned, System Assigned, or Unverified Assignments)
assignment_paths: Path assignment details and audit status information
geopath: Additional Geopath-specific measurements including face and spot circulation data

Example Request

curl --location 'https://intermx-test.apigee.net/v1/measures/viewcast/spot' \
--header 'Content-Type: application/json' \
--header 'apikey: {YOUR API KEY HERE}' \
--data '{
    "spots": [50807190]
}'

Example Response

Note that the history and percent_circ arrays are truncated in this example to show the structure.

{
    "results": [
        {
            "place_id": 166050675241,
            "location": "POINT(-73.999612 40.723536)",
            "market": {
                "co_geoid": "US2020STCO36061",
                "co_name": "New York County",
                "st_name": "New York",
                "cbsa_geoid": "US2020XMSA35620",
                "cbsa_name": "New York-Newark-Jersey City, NY-NJ-PA",
                "cbsa_type": "Metropolitan",
                "dma_geoid": "US2020XDMA501",
                "dma_name": "New York, NY",
                "postal_code": "10012"
            },
            "construction_type": "Exterior Wall",
            "classification_type": "Roadside",
            "media_type": "Murals",
            "digital": false,
            "face_orientation": 125,
            "face_height": 60,
            "face_width": 252,
            "viewable_distance": 137.19508,
            "face_audit_status": 12,
            "period_start": "2023-09-01",
            "period_end": "2024-08-31",
            "period_days": 366,
            "traffic": 19410,
            "face_circ": 38987,
            "face_ots": 38987,
            "spot_length": null,
            "share_of_voice": 1,
            "face_share_of_voice": 1,
            "spot_id": 50807190,
            "spot_circ": 38987,
            "spot_ots": 38987,
            "dwell": 8.137192,
            "percent_circ": {
                "day": [
                    {
                        "id": "mo",
                        "description": "Monday",
                        "value": 0.1273,
                        "hourly": [
                            0.0215, 0.0148, 0.0083, 0.0053, 0.0037, 0.0044,
                            0.0069, 0.0127, 0.0261, 0.0401, 0.0448, 0.0582,
                            0.0679, 0.0735, 0.0764, 0.0809, 0.0902, 0.1017,
                            0.0763, 0.0608, 0.0448, 0.0336, 0.0274, 0.0196
                        ]
                    },
                    {
                        "id": "fr",
                        "description": "Friday",
                        "value": 0.1662,
                        "hourly": [
                            0.0166, 0.0089, 0.0048, 0.003, 0.0024, 0.0034,
                            0.0063, 0.0133, 0.0254, 0.0423, 0.0476, 0.0585,
                            0.0639, 0.0716, 0.074, 0.0796, 0.0957, 0.1043,
                            0.0727, 0.0574, 0.051, 0.0379, 0.0335, 0.0257
                        ]
                    }
                ]
            },
            "history": {
                "year": [
                    {
                        "id": "2025",
                        "period_start": "2025-01-01",
                        "traffic": 23095,
                        "face_circ": 46390,
                        "spot_circ": 46390,
                        "spot_ots": 46390,
                        "dwell": 8,
                        "period_days": 365
                    },
                    {
                        "id": "2024",
                        "period_start": "2024-01-01",
                        "traffic": 20724,
                        "face_circ": 41626,
                        "spot_circ": 41626,
                        "spot_ots": 41626,
                        "dwell": 8,
                        "period_days": 366
                    }
                ],
                "month": [
                    {
                        "id": "2025-05",
                        "period_start": "2025-05-01",
                        "traffic": 21624,
                        "face_circ": 43434,
                        "spot_circ": 43434,
                        "spot_ots": 43434,
                        "dwell": 8,
                        "period_days": 31
                    },
                    {
                        "id": "2025-04",
                        "period_start": "2025-04-01",
                        "traffic": 24432,
                        "face_circ": 49075,
                        "spot_circ": 49075,
                        "spot_ots": 49075,
                        "dwell": 8,
                        "period_days": 30
                    }
                ]
            },
            "assignment_status": "System Assigned",
            "assignment_paths": [
                {
                    "path_id": "c78f634b6c9f8ce1e5fb53e15c238c0f",
                    "audit_status_id": 12,
                    "gp_assignments": [
                        2156073295
                    ]
                }
            ],
            "geopath": {
                "face_id": 50675241,
                "spot_id": 50807190,
                "face_traffic": 131986,
                "face_circ": 135340,
                "spot_circ": 135340,
                "spot_ots": 135340,
                "spot_lts": 97860
            }
        }
    ]
}