Viewcast™ API

See the documentation of Viewcast™ for all details of the data provided by this API.

Overview

Viewcast provides the Opportunity to See (OTS) measurement for pedestrian and vehicle paths within a Face Place viewshed. Opportunity to See measures the total number of people who could have seen a particular asset (e.g., billboard advertisement) during their travel. Viewcast aggregates pedestrian and vehicle volumes from Pathcast and combines them with out-of-home industry accepted multipliers to develop OTS statistics.

⚠️ Under Active Development
This API endpoint is currently under active development. Features, parameters, and response formats may change without notice. Please contact your account representative for the latest updates and production readiness status.

Data Definitions

Understanding these key terms will help you interpret the Viewcast API response data:

Core Concepts

Viewcast: Provides the Opportunity to See (OTS) measurement for pedestrian and vehicle paths within a Face Place viewshed. Measures the total number of people who could have seen a particular asset during their travel.
Spot: An advertisement that is presented on a Face (display). This may be static displays (poster or vinyl brand message posted on a billboard) or branded messages displayed digitally as part of a rotating Face.
Face: The physical display or screen where advertisements are shown. A Face can host multiple Spots in digital/rotating scenarios.
Place: The geographic location where the Face is positioned, with associated market and demographic context.

Measurement Metrics

Traffic: Synonym for visits - the average number of vehicles and pedestrians per week during the reporting period observed within the viewshed.
Circulation: Person-exposures to the display. For roadside displays, this is the number of pedestrians plus (vehicles × occupancy) to arrive at total person-exposures.
Opportunity to See (OTS): The total number of people who could have seen a particular asset during their travel, before considering visibility factors.
Likelihood to See (LTS): Also referred to as Impressions - how many times an Opportunity to See resulted in a person likely receiving a brand message. Considers the physical characteristics of the display and proximity to the person.
Dwell: For roadside displays, the estimated amount of time in minutes that a person is present within view of the face. Derived from the average speed of vehicles and weighted by circulation.

Display Classifications

Classification Types:

Roadside: Outdoor media primarily targeting vehicles on roadway (e.g., billboard on side of highway)
Place-Based: Media focused on indoor or outdoor venues primarily targeting pedestrian traffic (e.g., digital screen above a bar)
Construction Types: Include Freestanding, Interior Wall, Furniture, Exterior Wall, Bus Exterior, Exterior Vehicle, Ceiling, Floor, Column, Elevator, Stairs, Rooftop, and others.
Media Types: Based on width and height dimensions - Display, Panel, Junior Poster, Poster, Bulletin, and Murals.

Business Logic

Share of Voice: The percent of time a Spot is visible on a Face; most often used in relation to digital or rotating displays. A value of 1.0 means the spot is always visible (static display), while lower values indicate rotation with other advertisements.
Assignment Status: Indicates the source and reliability of the measurement data:

"Industry Assigned": Published values agree with Geopath Impressions
"System Assigned": Motionworks assignments differ from Geopath Impressions
"Unverified Assignments": Not currently producing expected results and queued for manual audits

Geographic Context

Market Data: Includes standardized geographic identifiers:

County (co_geoid, co_name): County-level geographic boundaries
CBSA (cbsa_geoid, cbsa_name): Core Based Statistical Area (metropolitan/micropolitan areas)
DMA (dma_geoid, dma_name): Designated Market Area for media planning
Postal Code: ZIP code for the display location

Endpoints

Viewcast Report

POST /measures/viewcast/report

Report on the aggregated measures for specific faces for a specific time period. This call will gather data on as many faces as available, replying with a list of which faces were found and which spots were missing from the measurement data.

Type

POST

Request Parameters

Required
- spots: array of integers representing spot ids
- start_date: start date and time of the specific time period user is requesting (2024-03-31 08:00)
- end_date: start date and time of the specific time period user is requesting (2024-04-30 20:00)

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:

spots: Reports the spot id, and corresponding Motionworks Place ID, along with whether the spot was measured.
by_day: measures by day of week, Monday, Tuesday, … Sunday, with an hourly array that corresponds from 0 - 23.
by_date: every calendar date from start date to end date, with the impressions for that date and the status of the impressions for that date.
- Based on the time period defined, impressions are either "Final" or "Projected". Final impressions are from the beginning of the specific time period through the start of the most recent previous month. Projected impressions for the time period are for the remainder of the specific time period. If the time period is entirely in the past, current impressions will match the projected impressions.
- For example, If a user requests a specific period from April 1st, 2025 - July 30th 2025, and queries the data on July 23rd 2025, dates from April 1st - May 31st will appear as "Final", and dates from June 1st - July 30th will appear as "Projected".
impressions: The sum total of the impressions, with the associated LTS impressions.

Example Request

curl --location 'https://intermx-test.apigee.net/v1/measures/viewcast/report' \
--header 'Content-Type: application/json' \
--header 'apikey: {YOUR API KEY HERE}' \
--data '{
    "spots": [50577208, 123],
    "start_date": "2024-03-31 08:00",
    "end_date": "2024-04-30 20:00"
}'

Example Response

{
    "spots": [
        {
            "spot_id": 50577208,
            "place_id": 166050513231,
            "measured": true
        },
        {
            "spot_id": 123,
            "measured": false
        }
    ],
    "by_day": [
        {
            "day": "Sunday",
            "daily": 197883,
            "hourly": [
                362,278,193,145,133,133,176,259,425,470,503,524,544,564,614,644,685,679,691,659,627,608,584,517
            ]
        }
    ],
    "by_date": [
        {
            "date": "2025-05-31",
            "status": "final",
            "impressions": 3130
        },
        {
            "date": "2025-06-01",
            "status": "projected",
            "impressions": 2303
        }
    ],
    "impressions":  {
        "current": 246326,
        "projected": 246326,
        "geopath": 122615,
        "geopath_daily": 1354
    }
}

Spots

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.