get_aprs_history
Retrieve historical position data for a callsign within a specified timeframe using the APRS.fi API, enabling ham radio tracking and balloon chase analysis.
Instructions
Get position history for a callsign with time range
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| apiKey | No | APRS.fi API key (optional if set via /set-api-key) | |
| callsign | Yes | The callsign to look up | |
| lastHours | No | Number of hours to look back (default: 24) |
Implementation Reference
- index.ts:116-170 (handler)Core handler function in APRSMCPService that fetches and returns APRS position history for a callsign over the last N hours using the APRS.fi API.async getPositionHistory( callsign: string, apiKey?: string, lastHours: number = 24 ): Promise<APRSPosition[]> { const keyToUse = apiKey || this.apiKey; if (!keyToUse) { throw new APRSError('APRS API key not provided. Use /set-api-key command or provide apiKey parameter.'); } if (!callsign?.trim()) { throw new APRSError('Callsign is required'); } const params = new URLSearchParams({ name: callsign.trim().toUpperCase(), what: 'loc', apikey: keyToUse, format: 'json', last: lastHours.toString() }); try { const response = await fetch(`${this.baseUrl}?${params}`); if (!response.ok) { throw new APRSError( `APRS API request failed: ${response.status} ${response.statusText}`, response.status ); } const data: APRSResponse = await response.json(); if (data.result !== 'ok') { throw new APRSError(`APRS API error: ${data.result}`); } return data.entries.map(entry => ({ ...entry, timestamp: entry.timestamp * 1000, })).sort((a, b) => a.timestamp - b.timestamp); } catch (error) { if (error instanceof APRSError) { throw error; } if (error instanceof TypeError && error.message.includes('fetch')) { throw new APRSError('Network error: Unable to connect to APRS.fi API. Check your internet connection.'); } throw new APRSError(`Unexpected error: ${error instanceof Error ? error.message : 'Unknown error'}`); } }
- index.ts:306-328 (registration)Tool registration in the ListToolsRequestSchema handler, defining name, description, and input schema.{ name: 'get_aprs_history', description: 'Get position history for a callsign with time range', inputSchema: { type: 'object', properties: { callsign: { type: 'string', description: 'The callsign to look up', }, apiKey: { type: 'string', description: 'APRS.fi API key (optional if set via /set-api-key)', }, lastHours: { type: 'number', description: 'Number of hours to look back (default: 24)', default: 24, }, }, required: ['callsign'], }, },
- index.ts:394-407 (handler)Dispatching handler in the CallToolRequestSchema switch statement that invokes the service method and formats the response.case 'get_aprs_history': const history = await this.aprsService.getPositionHistory( args.callsign as string, args.apiKey as string, args.lastHours as number ); return { content: [ { type: 'text', text: JSON.stringify(history, null, 2), }, ], };
- index.ts:309-327 (schema)Input schema definition for the get_aprs_history tool, specifying parameters and validation.inputSchema: { type: 'object', properties: { callsign: { type: 'string', description: 'The callsign to look up', }, apiKey: { type: 'string', description: 'APRS.fi API key (optional if set via /set-api-key)', }, lastHours: { type: 'number', description: 'Number of hours to look back (default: 24)', default: 24, }, }, required: ['callsign'], },
- index.ts:15-35 (schema)Type definitions for APRS position data and API response used by the tool.interface APRSPosition { name: string; callsign: string; lat: number; lng: number; altitude?: number; timestamp: number; comment?: string; speed?: number; course?: number; symbol?: string; path?: string; } interface APRSResponse { command: string; result: string; what: string; found: number; entries: APRSPosition[]; }