Menu
Back to Documentation Index

vNAS Integration

vNAS ERAM/STARS push integration with VATSWIM

Download Markdown Interactive API Docs All Documentation

vNAS → VATSWIM Push Integration

This document describes how vNAS (Virtual National Airspace System) can push ATC automation data to PERTI's VATSWIM API.

Overview

PERTI receives ATC automation data from vNAS to update track surveillance, automation tags, handoff state, and metering data for flights on the VATSIM network. This enables real-time coordination between vNAS ERAM/STARS systems and the PERTI SWIM platform.

Endpoints

EndpointMethodPurpose
/api/swim/v1/ingest/vnas/trackPOSTTrack/surveillance data (radar positions)
/api/swim/v1/ingest/vnas/tagsPOSTAutomation tags (assigned alt/speed/heading)
/api/swim/v1/ingest/vnas/handoffPOSTSector handoff data

Authentication

Use the Authorization header with a Bearer token:

Authorization: Bearer swim_sys_vnas_zdc_a1b2c3d4e5f6

Alternative: Use the X-API-Key header if Bearer tokens are inconvenient:

X-API-Key: swim_sys_vnas_zdc_a1b2c3d4e5f6

Rate Limits

  • 30,000 requests per minute (system tier)
  • Track data: up to 1,000 tracks per request
  • Tags data: up to 500 tags per request
  • Handoff data: up to 200 handoffs per request

    • Track/Surveillance Data

    Endpoint

    POST /api/swim/v1/ingest/vnas/track

    Request Format

    {
  "facility_id": "ZDC",
  "system_type": "ERAM",
  "timestamp": "2026-01-27T15:30:00.000Z",
  "tracks": [
    {
      "callsign": "UAL123",
      "gufi": "VAT-20260127-UAL123-KORD-KJFK",
      "beacon_code": "1234",
      "position": {
        "latitude": 40.6413,
        "longitude": -73.7781,
        "altitude_ft": 35000,
        "altitude_type": "barometric",
        "ground_speed_kts": 450,
        "track_deg": 270,
        "vertical_rate_fpm": -500
      },
      "track_quality": {
        "source": "radar",
        "mode_c": true,
        "mode_s": true,
        "ads_b": false,
        "position_quality": 9
      },
      "timestamp": "2026-01-27T15:30:00.000Z"
    }
  ]
}

    Field Reference

    FieldTypeRequiredDescription
    facility_idstringYesSource facility (e.g., "ZDC", "N90")
    system_typestringRecommended"ERAM" or "STARS"
    tracks[].callsignstringYesAircraft callsign
    tracks[].gufistringOptionalDirect GUFI lookup
    tracks[].beacon_codestringOptionalMode A/3 squawk code
    tracks[].position.latitudenumberYesLatitude (-90 to 90)
    tracks[].position.longitudenumberYesLongitude (-180 to 180)
    tracks[].position.altitude_ftintegerOptionalAltitude in feet MSL
    tracks[].position.ground_speed_ktsintegerOptionalGround speed in knots
    tracks[].position.track_degintegerOptionalTrue track (0-360)
    tracks[].position.vertical_rate_fpmintegerOptionalVertical rate (ft/min)
    tracks[].track_quality.mode_cbooleanOptionalMode C validity
    tracks[].track_quality.mode_sbooleanOptionalMode S validity
    tracks[].track_quality.ads_bbooleanOptionalADS-B equipped
    tracks[].track_quality.position_qualityintegerOptionalQuality 0-9

    Automation Tags

    Endpoint

    POST /api/swim/v1/ingest/vnas/tags

    Request Format

    {
  "facility_id": "ZDC",
  "system_type": "ERAM",
  "tags": [
    {
      "callsign": "UAL123",
      "gufi": "VAT-20260127-UAL123-KORD-KJFK",
      "assigned_altitude": 35000,
      "interim_altitude": 28000,
      "assigned_speed": 280,
      "assigned_heading": 270,
      "scratchpad": "KJFK/31L",
      "scratchpad2": "GDP+15",
      "point_out_sector": "33",
      "coordination_status": "TRACKED",
      "conflict_alert": false,
      "msaw_alert": false,
      "timestamp": "2026-01-27T15:30:00Z"
    }
  ]
}

    Field Reference

    FieldTypeDescription
    assigned_altitudeintegerController-assigned altitude (ft)
    interim_altitudeintegerERAM interim altitude (ft)
    assigned_speedintegerAssigned IAS (kts)
    assigned_machnumberAssigned Mach (e.g., 0.82)
    assigned_headingintegerAssigned heading (magnetic)
    scratchpadstringPrimary scratchpad (8 chars ERAM, 3 chars STARS)
    scratchpad2stringSecondary scratchpad (ERAM)
    scratchpad3stringTertiary scratchpad (ERAM)
    point_out_sectorstringPoint-out target sector
    coordination_statusstringUNTRACKED/TRACKED/ASSOCIATED/SUSPENDED
    conflict_alertbooleanConflict alert active
    msaw_alertbooleanMSAW alert active

    Handoff Data

    Endpoint

    POST /api/swim/v1/ingest/vnas/handoff

    Request Format

    {
  "facility_id": "ZDC",
  "handoffs": [
    {
      "callsign": "UAL123",
      "gufi": "VAT-20260127-UAL123-KORD-KJFK",
      "handoff_type": "AUTOMATED",
      "from_sector": "ZDC_33_CTR",
      "to_sector": "ZNY_42_CTR",
      "from_facility": "ZDC",
      "to_facility": "ZNY",
      "status": "INITIATED",
      "initiated_at": "2026-01-27T15:30:00Z",
      "accepted_at": null,
      "boundary_fix": "SWANN"
    }
  ]
}

    Field Reference

    FieldTypeRequiredDescription
    handoff_typestringYesAUTOMATED/MANUAL/POINT_OUT
    from_sectorstringYesTransferring sector (e.g., "ZDC_33_CTR")
    to_sectorstringYesAccepting sector
    statusstringYesINITIATED/ACCEPTED/REJECTED/RECALLED/COMPLETED
    initiated_atstringYesISO 8601 timestamp
    accepted_atstringOptionalWhen accepted
    boundary_fixstringOptionalFix at sector boundary

    Response Format

    Success Response (HTTP 200)

    {
  "success": true,
  "data": {
    "processed": 50,
    "updated": 48,
    "not_found": 2,
    "errors": 0,
    "error_details": []
  },
  "meta": {
    "source": "vnas",
    "facility": "ZDC",
    "system": "ERAM",
    "batch_size": 50
  },
  "timestamp": "2026-01-27T15:30:00Z"
}

    Error Codes

    CodeHTTPDescription
    UNAUTHORIZED401Invalid or missing API key
    NOT_AUTHORITATIVE403API key lacks write permission
    MISSING_FACILITY400facility_id is required
    INVALID_SYSTEM_TYPE400system_type must be ERAM or STARS
    BATCH_TOO_LARGE400Exceeds batch size limit

    Example cURL Requests

    Track Update

    curl -X POST https://perti.vatcscc.org/api/swim/v1/ingest/vnas/track \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer swim_sys_vnas_zdc_a1b2c3d4e5f6" \
  -d '{
    "facility_id": "ZDC",
    "system_type": "ERAM",
    "tracks": [{
      "callsign": "UAL123",
      "beacon_code": "4521",
      "position": {
        "latitude": 39.8561,
        "longitude": -77.0369,
        "altitude_ft": 35000,
        "ground_speed_kts": 485
      },
      "track_quality": {
        "mode_c": true,
        "mode_s": true,
        "position_quality": 9
      }
    }]
  }'

    Tags Update

    curl -X POST https://perti.vatcscc.org/api/swim/v1/ingest/vnas/tags \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer swim_sys_vnas_zdc_a1b2c3d4e5f6" \
  -d '{
    "facility_id": "ZDC",
    "system_type": "ERAM",
    "tags": [{
      "callsign": "UAL123",
      "assigned_altitude": 35000,
      "assigned_speed": 280,
      "scratchpad": "KJFK/31L",
      "coordination_status": "TRACKED"
    }]
  }'

    Handoff Update

    curl -X POST https://perti.vatcscc.org/api/swim/v1/ingest/vnas/handoff \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer swim_sys_vnas_zdc_a1b2c3d4e5f6" \
  -d '{
    "facility_id": "ZDC",
    "handoffs": [{
      "callsign": "UAL123",
      "handoff_type": "AUTOMATED",
      "from_sector": "ZDC_33_CTR",
      "to_sector": "ZNY_42_CTR",
      "status": "INITIATED",
      "initiated_at": "2026-01-27T15:30:00Z",
      "boundary_fix": "SWANN"
    }]
  }'

    Data Authority

    vNAS has priority 1 for track data in VATSWIM. This means:

  • vNAS track updates will override data from lower-priority sources
  • Track quality and beacon code from vNAS are considered authoritative

Document version: 1.0.0 | Last updated: 2026-01-27