# PlaneTrackerAPI Module for access to the PlaneTracker HTTP interface. ## Overview - [Constructor](#constructor) - [Methods](#static-methods) - [Static](#static-methods) - [Common](#common-methods) - [Calibration](#calibration-methods): Manage camera calibration. - [Settings](#settings-methods): Manage settings. - [Planes & Tracking](#planes--tracking-management-methods): Manage Planes and Tracking mode. - [Map & Zones](#map--zones-management-methods): Manage Map and Zones. - [Genetec](#genetec-management-methods): Manage connection to Genetec.
## Constructor - **new PlaneTrackerAPI(client, apiUser)** - Look at the [Client](./Client.md) docs. ```javascript import { DefaultClient } from 'camstreamerlib/web'; import { PlaneTrackerAPI } from 'camstreamerlib'; const ptrApi = new PlaneTrackerAPI(new DefaultClient(), { userId: 'asd', userName: 'Asd', userPriority: 1, }); ``` > [!IMPORTANT] > The `apiUser` param is important for correct API behavior The constructor accepts `Omit`. `TApiUser` is exported from `camstreamerlib` (defined in `PlaneTrackerEvents` types) and has the following shape: ```typescript type TApiUser = { userId: string; userName: string; userPriority: number; ip: string; // assigned by the server; not required in the constructor }; ```
> [!TIP] > The majority of PlaneTrackerAPI methods accept optional `options` parameter of type `THttpRequestOptions`: ```typescript type THttpRequestOptions = { timeout?: number; // in miliseconds proxyParams?: { path: string; target: { ip: string; mdnsName: string; port: number; user: string; pass: string; }; }; }; ```
## Static Methods ### getProxyPath() Returns relative path to proxy.cgi - **Returns:** `string` ```javascript const path = PlaneTrackerAPI.getProxyPath(); ``` ### getWsEventsPath() Returns relative path for event websocket - **Returns:** `string` ```javascript const path = PlaneTrackerAPI.getWsEventsPath(); ```
## Common Methods ### getClient(proxyParams?) Returns PlaneTracker client - can be used in custom PlaneTracker API calls. - **Parameters:** - `proxyParams` (`TProxyParams`, optional) ```typescript type TProxyParams = | { path: string; target: { ip: string; mdnsName: string; port: number; user: string; pass: string; }; } | undefined; ``` - **Returns:** `Client | ProxyClient` ```javascript const client = ptrApi.getClient(); ``` ### checkAPIAvailable(options?) Dummy endpoint to check if API is available. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.checkAPIAvailable(); ``` ### checkCameraTime(options?) Check camera time against CamStreamer server. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript const isValid = await ptrApi.checkCameraTime(); ``` ### serverRunCheck(options?) Checks if the http server is running. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** [`Promise`](#common-types) ```javascript await ptrApi.serverRunCheck(); ``` ### getLiveViewAlias(rtspUrl, options?) - **Parameters:** - `rtspUrl` (`string`) - `options` (`THttpRequestOptions`, optional) - **Returns:** ```typescript Promise<{ alias: string; ws: string; ws_initial_message: string; }>; ``` ```javascript const data = await ptrApi.getLiveViewAlias(url); ```
## Calibration Methods ### resetPtzCalibration(options?) - Resets the PTZ calibration data and restarts the script. - The calibration process is started again after the script starts. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.resetPtzCalibration(); ``` ### resetFocusCalibration(options?) - Resets the Focus calibration data and restarts the script. - The calibration process is started again after the script starts. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.resetFocusCalibration(); ``` ### triggerFocusReview(options?) - Requests a focus review tour and restarts the script. - On the next start the script guard-tours through each configured focus calibration point, dwelling at the minimum and maximum calibrated focus on each point while showing an overlay describing the step, then restarts and resumes normal operation. - Requires focus calibration data to be available; otherwise a `BadRequestError` is thrown. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.triggerFocusReview(); ```
## Settings Methods ### fetchCameraSettings(options?) Get the camera settings. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise`: ```typescript type TCameraSettings = { units: 'metric' | 'imperial'; adsbSource: { enabled: boolean; ip: string; port: number }; dronetagSource: { enabled: boolean }; camera: { ip: string; port: number; protocol: 'http' | 'https' | 'https_insecure'; user: string; pass: string; }; cameraCalibrationProcessConfig: { nightSkyCalibrationEnabled: boolean; scheduleNightSkyCalibrationTimestamp: number; focusCalibrationPoints: string; }; cameraConfig: { aircraft: { defaultCaptureSizeMeters: number; captureSizeExtensionMeters: number; }; drone: { defaultCaptureSizeMeters: number; captureSizeExtensionMeters: number; }; }; stream: { width: number; height: number; }; imageConfig: { dayAperture: number; nightAperture: number; maxGain: number; }; airportConfig: { icao: string; centerLat: number; centerLon: number; radius: number; }; trackingConfig: { prioritizeEmergency: boolean; trackingZoneWeightIncrease: number; guardTourEnabled: boolean; guardTourId: number; }; widget: { enabled: boolean; coord: 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right'; posX: number; posY: number; scale: number; units: 'metric' | 'imperial' | 'rotate'; }; airportWidget: { enabled: boolean; coord: 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right'; posX: number; posY: number; scale: number; windSpeedUnits: 'metric' | 'imperial' | 'rotate'; temperatureUnits: 'metric' | 'imperial' | 'rotate'; }; fr24FlightInfoSource: { enabled: boolean; priority: number; apiToken: string; validateFlights: boolean; }; radarcapeFlightInfoSource: { enabled: boolean; ip: string; port: number; priority: number; }; // Legacy settings with the aircraft rows at the top level are still accepted // and parsed as `aircraft`, with the default `drone` label. identificationLabel: { aircraft: { firstRow: 'icao' | 'blank' | 'registration' | 'call_sign' | 'flight_number'; secondRow: 'icao' | 'blank' | 'registration' | 'call_sign' | 'flight_number'; thirdRow: 'icao' | 'blank' | 'registration' | 'call_sign' | 'flight_number'; fourthRow: 'icao' | 'blank' | 'registration' | 'call_sign' | 'flight_number'; opacity: number; }; drone: { firstRow: 'blank' | 'remote_id'; opacity: number; }; }; acs: { enabled: boolean; ip: string; port: number; protocol: 'http' | 'https' | 'https_insecure'; user: string; pass: string; sourceKey: string; }; genetec: { enabled: boolean; ip: string; port: number; protocol: 'http' | 'https' | 'https_insecure'; user: string; pass: string; baseUri: string; appId: string; cameraList: string[]; }; camstreamerIntegration: { adPlacementEnabled: boolean; adMinIntervalSec: number; adShortDurationSec: number; adLongDurationSec: number; }; overlayText: | { displayIcao: boolean | undefined; displayRegistration: boolean | undefined; displayFlightNumber: boolean | undefined; displayAltitude: boolean | undefined; displayVelocity: boolean | undefined; displayDistance: boolean | undefined; displayFOV: boolean | undefined; displayPTError: boolean | undefined; displayPTZSpeed: boolean | undefined; displayVelocityData: boolean | undefined; displayAdsbVelocityData: boolean | undefined; displaySignalQuality: boolean | undefined; displayAutoTrackingInfo: boolean | undefined; displayGPSCoords: boolean | undefined; displayVapixQuery: boolean | undefined; displayFocus: boolean | undefined; displayAperture: boolean | undefined; displaySunDistance: boolean | undefined; displayTickTime: boolean | undefined; displayAircraftInfo: boolean | undefined; displaySystemInfo: boolean | undefined; } | undefined; }; ``` ```javascript const settings = await ptrApi.fetchCameraSettings(); ``` ### setCameraSettings(settings, options?) Set the camera settings. - **Parameters:** - `settings` (`TCameraSettings`): Camera settings configuration. - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.setCameraSettings(settings); ``` ### fetchServerSettings(options?) Get the server settings. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise`: ```typescript type TServerSettings = { cameraCalibration: { posLat: number; posLon: number; geoidHN: number; altitudeAmsl: number; rotationEast: number; rotationNorth: number; rotationUp: number; tiltTransformationCoefA: number; tiltCameraKnownPoint: number; tiltRealKnownPoint: number; panErrorCorrection: { cameraPan: number; realPan: number; }[]; }; }; ``` ```javascript const settings = await ptrApi.fetchServerSettings(); ``` ### exportAppSettings(dataType, options?) Export all settings into a `.zip` file: - `camera_data`: Camera settings - see `TCameraSettings` type. - `map_data`: Map info data, images of map tiles. - `server_data`: Server settings - see `TServerSettings` type. - **Parameters:** - `dataType` (`'ALL'` | `'NIGHT_SKY_CALIBRATION_DATA'`): Specifies which type of data to export. - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ### importAppSettings(dataType, formData, options?) Import all settings in a `.zip` file. - **Parameters:** - `dataType` (`'MAP_DATA'` | `'SERVER_DATA'` | `'ALL'`): Specifies which type of data to import. - `formData` (`Parameters[0]['data']`) - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ### getDomainList(options?) Returns a list of available tracking domains and their target categories. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise`: ```typescript type TDomainId = 'adsb' | 'remoteId'; type TCategoryIcon = 'small' | 'large' | 'heavy' | 'helicopter' | 'drone' | 'operator' | 'unknown'; type TCategoryDescriptor = { categoryId: string; uiName: string; icon: TCategoryIcon; }; type TDomainDescriptor = { uiName: string; icon: TCategoryIcon; categoryList: TCategoryDescriptor[]; }; type TDomainList = Partial>; ``` ```javascript const domainList = await ptrApi.getDomainList(); ```
## Planes & Tracking Management Methods ### types ```typescript //ICAO code of the plane type ICAO = string; ``` ```typescript type TTrackingMode = { mode: 'MANUAL' | 'AUTOMATIC'; }; ``` ### fetchFlightInfo(targetId, options?) Retrieves flight information for the given target. - **Parameters:** - `targetId` (`string`): The target ID of the plane. - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise`: ```typescript type TFlightInfo = { callsign: string | undefined; flightNumber: string | undefined; registration: string | undefined; aircraftType: string | undefined; airlines: string | undefined; originAirport: | { icao: string | undefined; iata: string | undefined; city: string | undefined; } | undefined; destinationAirport: { icao: string | undefined; iata: string | undefined; city: string | undefined; }; flightImages: | { src: string | undefined; photographer: string | undefined; }[] | undefined; }; ``` ```javascript const info = await ptrApi.fetchFlightInfo('target-123'); ``` ### startTrackingTarget(targetId, options?) - Tracks a target by its target ID. - The target is tracked even if it is not available in the FlightRadar24 API. - When the target disappears, tracking is reset to the original state. - **Parameters:** - `targetId` (`string`): The target ID of the plane to track. - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.startTrackingTarget('target-123'); ``` ### stopTrackingTarget(options?) Resets the forced tracking of any target. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.stopTrackingTarget(); ``` ### startTrackingPlane(icao, options?) ⚠️ Deprecated > [!WARNING] > Deprecated — kept for backwards compatibility. Use [`startTrackingTarget`](#starttrackingtargettargetid-options) instead. Will be removed in a future major release. - **Parameters:** - `icao` ([`ICAO`](#types)): The ICAO code of the plane to track. - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.startTrackingPlane('4BAA66'); ``` ### stopTrackingPlane(options?) ⚠️ Deprecated > [!WARNING] > Deprecated — kept for backwards compatibility. Use [`stopTrackingTarget`](#stoptrackingtargetoptions) instead. Will be removed in a future major release. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.stopTrackingPlane(); ``` ### getTrackingMode(options?) Gets the current tracking mode settings. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ([`TTrackingMode`](#types)) ```javascript const mode = await ptrApi.getTrackingMode(); ``` ### setTrackingMode(mode, options?) Sets the tracking mode. - **Parameters:** - `mode` ([`TTrackingMode['mode']`](#types)): Tracking mode. - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.setTrackingMode('AUTOMATIC'); ``` ### getIcao(by, value, options?) Returns the ICAO code (targetId) for a given registration or callsign. - **Parameters:** - `by` (`'registration' | 'callsign'`): Specifies the method used to identify the plane - Use `'registration'` to search by the aircraft's registration number - or `'callsign'` to search by its callsign - `value` (`string`): Value of the registration or callsign. - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript const icao = await ptrApi.getIcao('registration', 'OKFHS'); ``` ### Methods - Lists ```typescript type TListEntry = { domain: 'adsb' | 'remoteId'; idType: 'icao' | 'type_icao' | 'drone_mac' | 'operator_mac' | 'category'; idValue: string; }; type TPriorityListEntry = TListEntry & { priority: number; }; type TWhiteList = { list: TListEntry[]; }; type TBlackList = { list: TListEntry[]; }; type TPriorityList = { list: TPriorityListEntry[]; }; ``` ### get(options?) Get white/black/priority list. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise`, `Promise`, `Promise` ```javascript const priorityList = await ptrApi.getPriorityList(); const whiteList = await ptrApi.getWhiteList(); const blackList = await ptrApi.getBlackList(); ``` ### set(list, options?) Set white/black/priority list. - **Parameters:** - `whiteList` (`TWhiteList`): White list object. - `blackList` (`TBlackList`): Black list object. - `priorityList` (`TPriorityList`): Priority list object. - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.setWhiteList({ list: [{ domain: 'adsb', idType: 'icao', idValue: '4BAA66' }] }); await ptrApi.setBlackList({ list: [{ domain: 'adsb', idType: 'icao', idValue: '4B5288' }] }); await ptrApi.setPriorityList({ list: [ { domain: 'adsb', idType: 'icao', idValue: '4BAA66', priority: 1 }, { domain: 'adsb', idType: 'icao', idValue: '4BCI62', priority: 2 }, ], }); ```
## Map & Zones Management Methods ### fetchMapInfo(options?) Gets the current tracking mode settings. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```typescript type TMapInfo = { minZoom: number; maxZoom: number; mapTypes: ('roadmap' | 'satellite')[]; tileSize: number; }; ``` ```javascript const mapInfo = await ptrApi.fetchMapInfo(); ``` ### getZones(options?) Gets zones config. - **Parameters:** - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```typescript type TZones = { zones: { enabled: boolean; name?: string | undefined; area: [ { lat: number; lon: number; }, ...{ lat: number; lon: number; }[] ]; minAltitudeAmsl?: number | undefined; maxAltitudeAmsl?: number | undefined; minSpeedKmph?: number | undefined; maxSpeedKmph?: number | undefined; flightDirection: 'all' | 'arrival' | 'departure'; runwayDirectionDeg?: number | undefined; weight: number; perimeter: 'none' | 'outer' | 'inner'; trackingDomains: ('adsb' | 'remoteId')[]; }[]; }; ``` ```javascript const zones = await ptrApi.getZones(); ``` ### setZones(zones, options?) Update zones config. - **Parameters:** - `zones` (`TZones`): Configuration of the zones. - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.setZones(zones); ``` ### goToCoordinates(lat, lon, alt?, options?) Focus camera to specified coordinates. - **Parameters:** - `lat` (`number`): Latitude of the target location. - `lon` (`number`): Longitude of the target location. - `alt` (`number`, optional): Altitude of the target location (meters). If not provided, it will be fetched from the elevation service. - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.goToCoordinates(); ```
## Genetec Management Methods > [!TIP] > for more information see [GenetecAgent](GenetecAgent.md) ```typescript type TParameters = { [key: string]: string | number | boolean | null | undefined; }; ``` ### checkGenetecConnection(params, options?) Check the connection to Genetec. - **Parameters:** - `params` ([`TParameters`](#common-types)): Genetec data, example: ```typescript const params = { protocol: 'http' ip: '127.0.0.1'; port: 80; baseUri: 'WebSdk'; appId: 'someAppId'; user: 'userName'; pass: 'password'; }; ``` - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise` ```javascript await ptrApi.checkGenetecConnection(); ``` ### getGenetecCameraList(params, options?) Get the list of cameras available in Genetec. - **Parameters:** - `params` ([`TParameters`](#common-types)): Genetec data, example: ```typescript const params = { protocol: 'http' ip: '127.0.0.1'; port: 80; baseUri: 'WebSdk'; appId: 'someAppId'; user: 'userName'; pass: 'password'; }; ``` - `options` (`THttpRequestOptions`, optional) - **Returns:** `Promise`: ```typescript type TCameraList = { value: string; index: number; label: string; }[]; ``` ```javascript const cameraList = await ptrApi.getGenetecCameraList(); ```