Endpoints

POST /measures/viewcast/spot

Retrieve detailed spot-level data including historical measurements, circulation patterns, and geographic context. This call gathers comprehensive data for specific spots, providing detailed measurement history, circulation patterns by day of week and hour, market information, physical characteristics of the advertising face, and reach/frequency metrics.

GET /measures/viewcast/spot/{id}

Retrieve data for a single spot by ID. Returns a single spot result object (not wrapped in a results array).

Type

POST or GET

Request Parameters

POST:

Required
- spots: Array of integers representing spot IDs (maximum 2,000)

GET:

Required
- {id}: Integer - Spot ID in the URL path

Responses

200 OK: Successfully retrieved spot data
400 Bad Request: Issue with input parameters to request
403 Forbidden: Viewcast not enabled on license
404 Not Found: No spots requested were found

Validation error responses:

{
    "FieldErrors": {
        "spots": "one or more spots must be specified"
    }
}

{
    "FieldErrors": {
        "spots": "no more than 2000 spots may be specified"
    }
}

Not found response (all spots invalid):

{
    "Error": "The requested resource could not be found"
}

Response Fields

Response includes a results array. Each result contains:

Identification & Location:

spot_id: Integer - The unique spot identifier
place_id: Integer - Corresponding Motionworks Place ID for the face
location: String - Geographic coordinates in WKT POINT format (e.g., "POINT(-73.999612 40.723536)")
market: Object - Geographic market information:
- co_geoid: String - County FIPS code
- co_name: String - County name
- st_name: String - State name
- cbsa_geoid: String - CBSA identifier
- cbsa_name: String - CBSA name
- cbsa_type: String - CBSA type (e.g., "Metropolitan")
- dma_geoid: String - DMA identifier
- dma_name: String - DMA name
- postal_code: String - ZIP code

Physical Characteristics:

construction_type: String - Construction type (e.g., "Exterior Wall", "Freestanding")
classification_type: String - Classification (e.g., "Roadside", "Place Based")
media_type: String - Media type (e.g., "Bulletin", "Murals", "Panel")
digital: Boolean - Whether the display is digital
face_orientation: Number - Face orientation in degrees
face_height: Number - Face height in inches
face_width: Number - Face width in inches
viewable_distance: Number - Viewable distance in feet

Measurement Data (Current Period):

period_start: String - Measurement period start date
period_end: String - Measurement period end date
period_days: Integer - Number of days in measurement period
traffic: Integer - Average weekly vehicle and pedestrian visits
face_circ: Integer - Face-level circulation (person-exposures)
face_ots: Integer - Face-level Opportunity to See
spot_circ: Integer - Spot-level circulation
spot_ots: Integer - Spot-level Opportunity to See
dwell: Number - Estimated time in minutes within view of face
spot_length: Integer or null - Spot length in seconds (for digital displays)
share_of_voice: Number - Spot share of voice (1.0 = always visible/static)
face_share_of_voice: Number - Face share of voice
face_audit_status: Integer - Audit status code

Reach & Population:

total_population: Integer - Total national population
market_population: Integer - Population within the display's DMA market
total_reach_eff1: Integer - Unique persons reached at frequency 1+ (national)
market_reach_eff1: Integer - Unique persons reached at frequency 1+ (market)
total_reach_eff3: Integer - Unique persons reached at frequency 3+ (national)
market_reach_eff3: Integer - Unique persons reached at frequency 3+ (market)

Circulation Distribution:

percent_circ: Object containing:
- day: Array with 7 entries (Monday through Sunday), each with:
  - id: String - Day abbreviation ("mo", "tu", "we", "th", "fr", "sa", "su")
  - description: String - Day name
  - value: Number - Percentage of total weekly circulation
  - hourly: Array of 24 numbers - Percentage of daily circulation for each hour (0-23)
- segment: Object containing demographic breakdown:
  - basic_demographics: Array of demographic categories, each with:
    - category: String - Demographic category name
    - segments: Array of segment entries, each with:
      - id: String - Segment identifier (e.g., "age_00plus", "age_18plus")
      - description: String - Segment description
      - value: Number - Percentage value for this segment
      - index: Number - Index value for this segment

Historical Measurements:

history: Object containing:
- year: Array of yearly aggregates extending back to 2019, each with:
  - id: String - Year (e.g., "2025")
  - period_start: String - Year start date
  - traffic, face_circ, spot_circ, spot_ots, dwell, period_days
  - avg_daily_ped_traffic: Integer or null - Average daily pedestrian traffic
  - avg_daily_veh_traffic: Integer or null - Average daily vehicle traffic
- month: Array of monthly data, each with:
  - id: String - Year-month (e.g., "2025-05")
  - period_start: String - Month start date
  - traffic, face_circ, spot_circ, spot_ots, dwell, period_days
  - avg_daily_ped_traffic: Integer or null - Average daily pedestrian traffic
  - avg_daily_veh_traffic: Integer or null - Average daily vehicle traffic

Assignment & Audit:

assignment_status: String - Current assignment status ("Industry Assigned", "System Assigned", or "Unverified Assignments")
assignments: Array of assignment objects with:
- id: String - Assignment identifier (path hash)
- type: String - Assignment type (e.g., "path")
- audit_status_id: Integer - Audit status code

Geopath Comparison:

geopath: Object with Geopath-specific measurements:
- face_id: Integer - Geopath Face ID
- spot_id: Integer - Geopath Spot ID
- face_traffic: Integer - Geopath face traffic
- face_circ: Integer - Geopath face circulation
- spot_circ: Integer - Geopath spot circulation
- spot_ots: Integer - Geopath Opportunity to See
- spot_lts: Integer - Geopath Likelihood to See (impressions)

Example Request - Single Spot (GET)

curl --location 'https://intermx-test.apigee.net/v1/measures/viewcast/spot/50807190' \
--header 'apikey: {YOUR API KEY HERE}'

Example Request - Single Spot (POST)

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 Request - Multiple Spots

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, 50577208]
}'

Example Response

Note: 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": 515.29,
            "face_audit_status": 12,
            "period_start": "2023-09-01",
            "period_end": "2024-08-31",
            "period_days": 366,
            "traffic": 50569,
            "face_circ": 60274,
            "face_ots": 60274,
            "spot_length": null,
            "share_of_voice": 1,
            "face_share_of_voice": 1,
            "spot_id": 50807190,
            "spot_circ": 60274,
            "spot_ots": 60274,
            "dwell": 13.955967,
            "total_population": 335954299,
            "market_population": 21664898,
            "total_reach_eff1": 11979,
            "market_reach_eff1": 11501,
            "total_reach_eff3": 3047,
            "market_reach_eff3": 3047,
            "percent_circ": {
                "day": [
                    {
                        "id": "mo",
                        "description": "Monday",
                        "value": 0.1331,
                        "hourly": [
                            0.0139, 0.0127, 0.0092, 0.0043, 0.0053, 0.0055,
                            0.0063, 0.0245, 0.0246, 0.03, 0.041, 0.0472,
                            0.0697, 0.0788, 0.0865, 0.1038, 0.1079, 0.1045,
                            0.0653, 0.0451, 0.034, 0.0265, 0.0354, 0.0179
                        ]
                    },
                    {
                        "id": "fr",
                        "description": "Friday",
                        "value": 0.1595,
                        "hourly": [
                            0.0139, 0.0127, 0.0092, 0.0043, 0.0053, 0.0055,
                            0.0063, 0.0245, 0.0246, 0.03, 0.041, 0.0472,
                            0.0697, 0.0788, 0.0865, 0.1038, 0.1079, 0.1045,
                            0.0653, 0.0451, 0.034, 0.0265, 0.0354, 0.0179
                        ]
                    }
                ]
            },
            "history": {
                "year": [
                    {
                        "id": "2025",
                        "period_start": "2025-01-01",
                        "traffic": 59934,
                        "face_circ": 71441,
                        "spot_circ": 71441,
                        "spot_ots": 71441,
                        "dwell": 14,
                        "period_days": 365
                    },
                    {
                        "id": "2024",
                        "period_start": "2024-01-01",
                        "traffic": 53783,
                        "face_circ": 64109,
                        "spot_circ": 64109,
                        "spot_ots": 64109,
                        "dwell": 14,
                        "period_days": 366
                    }
                ],
                "month": [
                    {
                        "id": "2025-12",
                        "period_start": "2025-12-01",
                        "traffic": 56199,
                        "face_circ": 67,
                        "spot_circ": 67,
                        "spot_ots": 67,
                        "dwell": 14,
                        "period_days": 31
                    }
                ]
            },
            "assignment_status": "Industry Assigned",
            "assignments": [
                {
                    "id": "c29bb3e72c31eb27e6ad61f5ad369026",
                    "type": "path",
                    "audit_status_id": 12
                }
            ],
            "geopath": {
                "face_id": 50675241,
                "spot_id": 50807190,
                "face_traffic": 69204,
                "face_circ": 93035,
                "spot_circ": 93035,
                "spot_ots": 93035,
                "spot_lts": 69827
            }
        }
    ]
}