Documentation sections

Calculate

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

Runs any of the 255 calculators with the inputs you would type on its page, in the units the page shows, and returns every output, the warnings and the provenance as JSON.

Authenticate with the X-API-Key header. Keys start with rfc_ and are created on the dashboard. Every call counts against the account's monthly allowance: 5 on Free, 100 on Pro, 10,000 on API.

Request body

CalculateRequest
Field	Description
slugrequiredstring	The calculator, by the slug in its page's address, e.g. rf-link-budget. Every slug is listed under Slugs and inputs.
inputsrequiredobject of numbers	Input values keyed by the calculator's input keys, in the units its reference lists. Send every input: most are required, and a call without one is refused (400); an optional one left out takes the default the reference shows. A key the calculator does not read is ignored with a warning.

Inputs for rf-link-budget

Generated from the calculator's definition. An input outside its range is still computed and flagged in the provenance. Every calculator's inputs are under Slugs and inputs.

Inputs of rf-link-budget
Name	Unit	Range	Default	Description
txPowernumber	dBm	−30 … 100	30	Transmitter output power
txGainnumber	dBi	−30 … 60	3	TX antenna gain in dBi
txCableLossnumber	dB	0 … 20	1	TX cable + connector losses (positive value)
frequencynumber	MHz	0.1 … 1000000	2400	Center frequency
distancenumber	km	0.001 … 1000000	1	Distance between TX and RX
rainFadenumber	dB	0 … 50	0	Rain attenuation per ITU-R P.838. Use 0 for line-of-sight ground links; 3–20 dB for satellite links above 10 GHz in heavy rain zones.
atmosphericLossnumber	dB	0 … 20	0.5	Gaseous absorption (O₂ at 60 GHz: ~15 dB/km; H₂O at 22 GHz: ~0.2 dB/km). Use 0.5 dB typical for sub-6 GHz terrestrial links.
pointingLossnumber	dB	0 … 10	0	Antenna misalignment loss. Pencil-beam dishes: 0.5–3 dB. Omnidirectional or wide-beam antennas: 0 dB.
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
rxGainnumber	dBi	−30 … 60	3	RX antenna gain in dBi
rxCableLossnumber	dB	0 … 20	1	RX cable + connector losses
rxSensitivitynumber	dBm	−160 … 0	-90	Minimum receivable signal level
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.

Response

CalculateResponse
Field	Description
slugstring	The calculator, as asked for.
valuesobject of numbers	Each output by key, in the units its reference lists. null where a value is unbounded or undefined, such as the return loss of a perfect match.
warningsstring[]	The calculator's own warnings, then the API's: an input not read, an input outside the range the calculator is stated for.
errorsstring[]	The calculator's errors; empty on success.
provenanceobject	How the values were computed: method, engine version, formula reference, assumptions and valid range. See Provenance.

The outputs of rf-link-budget, in values:

Outputs of rf-link-budget
Field	Unit	Description
fspl	dB	Free Space Path Loss
eirp	dBm	Effective Isotropic Radiated Power
rxPower	dBm	Received Power
linkMarginheadline	dB	Link Margin
maxRangeKm	km	Max Range
totalAdditionalLoss	dB	Sum of rain fade, atmospheric loss, pointing loss and any extra loss terms
maxRangeAtTarget	km	The distance at which the link margin falls to the target margin
wavelength	mm	Wavelength
fresnelRadius	m	Radius of the first Fresnel zone at the middle of the path. Keep at least 60 % of it clear of obstacles.

Errors

Errors of POST /calculate
Status	Python exception	When
400	ValidationError	The request cannot be answered as sent: an input that is not a finite number, a solve that cannot be set up, a job body outside its contract, or a batch that is empty or over its limit. Nothing is counted.
401	AuthError	No key was sent (the body carries keyUrl), or the key is not one we issued, or was revoked. Never about the allowance.
402	QuotaError	The account's monthly allowance is spent, on every metered route. Nothing was counted. Retry-After gives the seconds until resetAt.
404	NotFound	No such calculator slug, job type or job. Nothing is counted.
422	ValidationError	The body does not parse: a required field is missing, or a value is of the wrong type (an input sent as text). Answered before the route runs.
429	RateLimitError	Too many requests in a minute for the credential, or too many jobs queued or running at once. Retry-After says when to try again.
500	APIError	The result was computed but could not be returned, or a solve failed. Nothing was charged.
503	APIError	The key or the allowance counter could not be checked, or a job could not be queued. Nothing was queued or charged; try again.

Every check runs before anything is counted: the key, the calculator, then the inputs. See Errors for each body.

Try it

Send a request from this page with your own key. It counts like any other call.

CalculatorInputs (JSON)API key

A request needs a key, and counts against its account's allowance. Get a free key.

curl -X POST https://rftools.io/api/py/v1/calculate \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "rf-link-budget",
    "inputs": {
      "txPower": 20,
      "txGain": 2,
      "txCableLoss": 1,
      "frequency": 2400,
      "distance": 0.5,
      "rainFade": 0,
      "atmosphericLoss": 0.5,
      "pointingLoss": 0,
      "extraLossCount": 0,
      "extraLoss1": 0,
      "extraLoss2": 0,
      "extraLoss3": 0,
      "extraLoss4": 0,
      "rxGain": 2,
      "rxCableLoss": 1,
      "rxSensitivity": -90,
      "targetMargin": 10
    }
  }'

import rftools

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

result = client.calculate("rf-link-budget", {
    "txPower": 20,
    "txGain": 2,
    "txCableLoss": 1,
    "frequency": 2400,
    "distance": 0.5,
    "rainFade": 0,
    "atmosphericLoss": 0.5,
    "pointingLoss": 0,
    "extraLossCount": 0,
    "extraLoss1": 0,
    "extraLoss2": 0,
    "extraLoss3": 0,
    "extraLoss4": 0,
    "rxGain": 2,
    "rxCableLoss": 1,
    "rxSensitivity": -90,
    "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": "rf-link-budget",
    "inputs": {
      "txPower": 20,
      "txGain": 2,
      "txCableLoss": 1,
      "frequency": 2400,
      "distance": 0.5,
      "rainFade": 0,
      "atmosphericLoss": 0.5,
      "pointingLoss": 0,
      "extraLossCount": 0,
      "extraLoss1": 0,
      "extraLoss2": 0,
      "extraLoss3": 0,
      "extraLoss4": 0,
      "rxGain": 2,
      "rxCableLoss": 1,
      "rxSensitivity": -90,
      "targetMargin": 10
    }
  }),
});
console.log(response.status, await response.json());

package main

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

func main() {
	body := []byte(`{
	  "slug": "rf-link-budget",
	  "inputs": {
	    "txPower": 20,
	    "txGain": 2,
	    "txCableLoss": 1,
	    "frequency": 2400,
	    "distance": 0.5,
	    "rainFade": 0,
	    "atmosphericLoss": 0.5,
	    "pointingLoss": 0,
	    "extraLossCount": 0,
	    "extraLoss1": 0,
	    "extraLoss2": 0,
	    "extraLoss3": 0,
	    "extraLoss4": 0,
	    "rxGain": 2,
	    "rxCableLoss": 1,
	    "rxSensitivity": -90,
	    "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": "rf-link-budget",
  "values": {
    "fspl": 94.03140814283587,
    "eirp": 21,
    "rxPower": -72.53140814283587,
    "linkMargin": 17.468591857164128,
    "maxRangeKm": 3.73593745752468,
    "totalAdditionalLoss": 0.5,
    "wavelength": 124.91352416666666,
    "fresnelRadius": 3.951479535671839,
    "maxRangeAtTarget": 1.181407156171655
  },
  "warnings": [],
  "errors": [],
  "provenance": {
    "method": "calculator:rf-link-budget",
    "version": "api@3f2c1a9b04de",
    "formulaRef": "Friis, \"A Note on a Simple Transmission Formula\" (1946)",
    "assumptions": [],
    "validRange": {
      "status": "inside",
      "bounds": {
        "txPower": {
          "min": -30,
          "max": 100,
          "unit": "dBm"
        },
        "txGain": {
          "min": -30,
          "max": 60,
          "unit": "dBi"
        },
        "txCableLoss": {
          "min": 0,
          "max": 20,
          "unit": "dB"
        },
        "frequency": {
          "min": 0.1,
          "max": 1000000,
          "unit": "MHz"
        },
        "distance": {
          "min": 0.001,
          "max": 1000000,
          "unit": "km"
        },
        "rainFade": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        },
        "atmosphericLoss": {
          "min": 0,
          "max": 20,
          "unit": "dB"
        },
        "pointingLoss": {
          "min": 0,
          "max": 10,
          "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"
        },
        "rxGain": {
          "min": -30,
          "max": 60,
          "unit": "dBi"
        },
        "rxCableLoss": {
          "min": 0,
          "max": 20,
          "unit": "dB"
        },
        "rxSensitivity": {
          "min": -160,
          "max": 0,
          "unit": "dBm"
        },
        "targetMargin": {
          "min": 0,
          "max": 60,
          "unit": "dB"
        }
      },
      "outside": [],
      "model": null
    },
    "computedAt": "2026-09-24T14:05:11.003Z",
    "inputs": {
      "txPower": 20,
      "txGain": 2,
      "txCableLoss": 1,
      "frequency": 2400,
      "distance": 0.5,
      "rainFade": 0,
      "atmosphericLoss": 0.5,
      "pointingLoss": 0,
      "extraLossCount": 0,
      "extraLoss1": 0,
      "extraLoss2": 0,
      "extraLoss3": 0,
      "extraLoss4": 0,
      "rxGain": 2,
      "rxCableLoss": 1,
      "rxSensitivity": -90,
      "targetMargin": 10
    },
    "seed": null,
    "elapsedSeconds": 0.003
  }
}

{
  "detail": "Calculator 'rf-link-budgett' not found",
  "errorKind": "invalid_request"
}

A slug that does not exist. Nothing was counted.

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

An input sent as text. Answered before the route runs; nothing was counted.

{
  "detail": "This account's 100 API calls for September are used. They reset on 2026-10-01. The API plan includes 10,000 a month.",
  "errorKind": "rate_limited",
  "reason": "allowance",
  "limit": 100,
  "used": 100,
  "upgradeUrl": "https://rftools.io/pricing/",
  "overageUrl": null,
  "resetAt": "2026-10-01T00:00:00+00:00"
}

The month's allowance is spent, with Retry-After.

{
  "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 Budget Calculator, with these values in its address