openhamclock/iturhfprop-service

ITURHFProp Service

REST API wrapper for the ITURHFProp HF propagation prediction engine, implementing ITU-R P.533-14 "Method for the prediction of the performance of HF circuits".

Overview

This microservice provides HF propagation predictions as a REST API, suitable for integration with OpenHamClock or any amateur radio application needing professional-grade propagation forecasts.

Why ITURHFProp?

• ITU-R P.533-14 Compliant - The international standard for HF prediction
• Open Source - BSD licensed, freely available
• Accurate - Used by professional HF planning tools
• No API Restrictions - Unlike web services, you control the engine

API Endpoints

Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "service": "iturhfprop",
  "engine": "ITURHFProp (ITU-R P.533-14)"
}

Single Point Prediction

GET /api/predict?txLat=40.1&txLon=-74.8&rxLat=51.5&rxLon=-0.1&month=1&hour=12&ssn=100

Parameters:

Param	Required	Description
txLat	Yes	Transmitter latitude
txLon	Yes	Transmitter longitude
rxLat	Yes	Receiver latitude
rxLon	Yes	Receiver longitude
month	No	Month (1-12), default: current
hour	No	UTC hour (0-23), default: current
ssn	No	Smoothed Sunspot Number, default: 100
year	No	Year, default: current
txPower	No	TX power in watts, default: 100
frequencies	No	Comma-separated MHz values

Response:

{
  "model": "ITU-R P.533-14",
  "engine": "ITURHFProp",
  "muf": 28.5,
  "frequencies": [
    { "freq": 14.1, "reliability": 85, "snr": 25, "sdbw": -95 },
    { "freq": 21.1, "reliability": 72, "snr": 18, "sdbw": -102 }
  ],
  "elapsed": 150
}

24-Hour Prediction

GET /api/predict/hourly?txLat=40.1&txLon=-74.8&rxLat=51.5&rxLon=-0.1&month=1&ssn=100

Returns predictions for each hour (0-23 UTC).

Band Conditions (Simplified)

GET /api/bands?txLat=40.1&txLon=-74.8&rxLat=51.5&rxLon=-0.1

Response:

{
  "model": "ITU-R P.533-14",
  "muf": 28.5,
  "bands": {
    "20m": { "freq": 14.1, "reliability": 85, "status": "GOOD" },
    "15m": { "freq": 21.1, "reliability": 72, "status": "GOOD" },
    "10m": { "freq": 28.1, "reliability": 45, "status": "FAIR" }
  }
}

Deployment

Railway (Recommended)

1. Create a new project on Railway
2. Connect this directory as a service
3. Deploy!

The Dockerfile will:

• Clone and build ITURHFProp from source
• Set up the Node.js API wrapper
• Configure all necessary data files

Docker

# Build
docker build -t iturhfprop-service .

# Run
docker run -p 3000:3000 iturhfprop-service

# Test
curl http://localhost:3000/api/health

Local Development

Requires ITURHFProp to be installed locally:

# Install ITURHFProp (Linux)
git clone https://github.com/G4FKH/ITURHFProp.git
cd ITURHFProp/Linux
make

# Set environment variables
export ITURHFPROP_PATH=/path/to/ITURHFProp/Linux/ITURHFProp
export ITURHFPROP_DATA=/path/to/ITURHFProp/Data

# Run service
npm install
npm start

Integration with OpenHamClock

In your OpenHamClock server.js, add:

const ITURHFPROP_SERVICE = process.env.ITURHFPROP_URL || 'http://localhost:3001';

app.get('/api/propagation', async (req, res) => {
  const { deLat, deLon, dxLat, dxLon } = req.query;
  
  try {
    const response = await fetch(
      `${ITURHFPROP_SERVICE}/api/bands?txLat=${deLat}&txLon=${deLon}&rxLat=${dxLat}&rxLon=${dxLon}`
    );
    const data = await response.json();
    res.json(data);
  } catch (err) {
    // Fallback to built-in estimation
    res.json(calculateFallbackPropagation(deLat, deLon, dxLat, dxLon));
  }
});

Performance

• Cold start: ~5 seconds (Docker container initialization)
• Prediction time: 100-300ms per calculation
• 24-hour forecast: 3-7 seconds

Technical Details

ITU-R P.533-14

The prediction model accounts for:

• F2-layer propagation (main HF mode)
• E-layer propagation
• Sporadic-E when applicable
• D-layer absorption
• Ground wave (short paths)
• Antenna gains
• Man-made noise levels
• Required SNR and reliability

Limitations

• Single-hop paths only (< 4000 km optimal)
• Does not predict sporadic-E openings
• Monthly median predictions (not real-time ionospheric conditions)

For real-time enhancement, combine with ionosonde data from KC2G/GIRO network.

License

This service wrapper is MIT licensed.

ITURHFProp is BSD licensed - see G4FKH/ITURHFProp for details.

Credits

• ITURHFProp by G4FKH (Martin) - The core prediction engine
• ITU-R P.533 - International Telecommunication Union recommendation
• OpenHamClock - Integration target

---

73 de OpenHamClock contributors