Documentation sections

RF Link Margin Calculator

POSThttps://rftools.io/api/py/v1/calculate

Slug link-margin. Calculate RF link margin from TX power, antenna gains, path loss, and receiver sensitivity. Determine max range and fade margin for wireless links. Free, instant results.

Inputs

Send every one of these in inputs, in the units shown. Most are required: a call without one is refused (400) and costs nothing; one the calculator can do without takes the default shown. An input outside its range is still computed and flagged in the provenance.

Inputs of link-margin
Name	Unit	Range	Default	Description
txPowernumber	dBm	−30 … 60	20	Transmitter output power
txGainnumber	dBi	−10 … 50	3	Transmit antenna gain in dBi
rxGainnumber	dBi	−10 … 50	3	Receive antenna gain in dBi
distancenumber	km	at least 0.001	1	Distance between transmitter and receiver
frequencynumber	GHz	at least 0.001	2.4	Operating frequency in GHz
sensitivitynumber	dBm	−150 … 0	-90	Receiver minimum sensitivity from datasheet
cableLossnumber	dB	at least 0	1	Total cable and connector losses on TX and RX sides combined
extraLossCountnumber	none	0 … 4	0	How many extra loss terms the budget includes, such as polarisation mismatch, body loss or foliage
extraLoss1number	dB	0 … 50	0	An extra loss in the path, such as polarisation mismatch, body loss, foliage or a wall
extraLoss2number	dB	0 … 50	0	An extra loss in the path, such as polarisation mismatch, body loss, foliage or a wall
extraLoss3number	dB	0 … 50	0	An extra loss in the path, such as polarisation mismatch, body loss, foliage or a wall
extraLoss4number	dB	0 … 50	0	An extra loss in the path, such as polarisation mismatch, body loss, foliage or a wall
targetMarginnumber	dB	0 … 60	10	The fade margin the link must keep above the receiver sensitivity. The status passes at or above it and fails below 0 dB.

Outputs

Returned in values, by key. A value that is unbounded or undefined is null.

Outputs of link-margin
Field	Unit	Description
fspl	dB	Free-space path loss at specified frequency and distance
receivedPower	dBm	Received signal power level at receiver input
linkMarginheadline	dB	Margin above receiver sensitivity. Positive = link will work. >10 dB recommended.
maxRange	km	Maximum range where link still has positive margin

Calling it

Calculate: one call, the request and response in full, and its errors.
Batch: this calculator with others, or a sweep, in one request.
Solve for a target: the value of one input that brings an output to a target.

curl -X POST https://rftools.io/api/py/v1/calculate \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "link-margin",
    "inputs": {
      "txPower": 20,
      "txGain": 3,
      "rxGain": 3,
      "distance": 1,
      "frequency": 2.4,
      "sensitivity": -90,
      "cableLoss": 1,
      "extraLossCount": 0,
      "extraLoss1": 0,
      "extraLoss2": 0,
      "extraLoss3": 0,
      "extraLoss4": 0,
      "targetMargin": 10
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

result = client.calculate("link-margin", {
    "txPower": 20,
    "txGain": 3,
    "rxGain": 3,
    "distance": 1,
    "frequency": 2.4,
    "sensitivity": -90,
    "cableLoss": 1,
    "extraLossCount": 0,
    "extraLoss1": 0,
    "extraLoss2": 0,
    "extraLoss3": 0,
    "extraLoss4": 0,
    "targetMargin": 10,
})
print(result.values)
print(result.warnings, result.provenance.formula_ref)

const response = await fetch("https://rftools.io/api/py/v1/calculate", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "slug": "link-margin",
    "inputs": {
      "txPower": 20,
      "txGain": 3,
      "rxGain": 3,
      "distance": 1,
      "frequency": 2.4,
      "sensitivity": -90,
      "cableLoss": 1,
      "extraLossCount": 0,
      "extraLoss1": 0,
      "extraLoss2": 0,
      "extraLoss3": 0,
      "extraLoss4": 0,
      "targetMargin": 10
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "slug": "link-margin",
	  "inputs": {
	    "txPower": 20,
	    "txGain": 3,
	    "rxGain": 3,
	    "distance": 1,
	    "frequency": 2.4,
	    "sensitivity": -90,
	    "cableLoss": 1,
	    "extraLossCount": 0,
	    "extraLoss1": 0,
	    "extraLoss2": 0,
	    "extraLoss3": 0,
	    "extraLoss4": 0,
	    "targetMargin": 10
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/calculate", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

application/json

{
  "slug": "link-margin",
  "values": {
    "fspl": 100.05200805611548,
    "receivedPower": -75.05200805611548,
    "linkMargin": 14.947991943884517,
    "maxRange": 5.589842832887214
  },
  "warnings": [],
  "errors": [],
  "provenance": {
    "method": "calculator:link-margin",
    "version": "api@3f2c1a9b04de",
    "formulaRef": "ITU-R P.525-4, Calculation of free-space attenuation",
    "assumptions": [],
    "validRange": {
      "status": "inside",
      "bounds": {
        "txPower": {
          "min": -30,
          "max": 60,
          "unit": "dBm"
        },
        "txGain": {
          "min": -10,
          "max": 50,
          "unit": "dBi"
        },
        "rxGain": {
          "min": -10,
          "max": 50,
          "unit": "dBi"
        },
        "distance": {
          "min": 0.001,
          "max": null,
          "unit": "km"
        },
        "frequency": {
          "min": 0.001,
          "max": null,
          "unit": "GHz"
        },
        "sensitivity": {
          "min": -150,
          "max": 0,
          "unit": "dBm"
        },
        "cableLoss": {
          "min": 0,
          "max": null,
          "unit": "dB"
        },
        "extraLossCount": {
          "min": 0,
          "max": 4,
          "unit": ""
        },
        "extraLoss1": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        },
        "extraLoss2": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        },
        "extraLoss3": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        },
        "extraLoss4": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        },
        "targetMargin": {
          "min": 0,
          "max": 60,
          "unit": "dB"
        }
      },
      "outside": [],
      "model": null
    },
    "computedAt": "2026-09-24T14:05:11.003Z",
    "inputs": {
      "txPower": 20,
      "txGain": 3,
      "rxGain": 3,
      "distance": 1,
      "frequency": 2.4,
      "sensitivity": -90,
      "cableLoss": 1,
      "extraLossCount": 0,
      "extraLoss1": 0,
      "extraLoss2": 0,
      "extraLoss3": 0,
      "extraLoss4": 0,
      "targetMargin": 10
    },
    "seed": null,
    "elapsedSeconds": 0.003
  }
}

{
  "detail": [
    {
      "type": "float_parsing",
      "loc": [
        "body",
        "inputs",
        "txPower"
      ],
      "msg": "Input should be a valid number, unable to parse string as a number",
      "input": "abc"
    }
  ]
}

An input sent as text. Nothing was counted.

{
  "detail": "More than 120 requests in 60 seconds from this address.",
  "errorKind": "rate_limited",
  "limit": 120,
  "windowSeconds": 60,
  "upgradeUrl": "https://rftools.io/pricing/"
}

Too many requests in a minute, with Retry-After.

Same inputs on the calculator pageRF Link Margin Calculator, at these values