API Reference

Viewcast Spot

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
            }
        }
    ]
}

Updated 4 months ago

Did this page help you?

Updated 4 months ago

Did this page help you?