Documentation sections

Antenna Beamwidth & Gain Calculator

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

Slug antenna-beamwidth. Calculate antenna 3 dB beamwidth, gain from aperture, and effective area. Determine HPBW for dish, horn, and aperture antennas. 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 antenna-beamwidth
Name	Unit	Range	Default	Description
gainnumber	dBi	at least 0	20	Antenna Gain
frequencynumber	GHz	at least 0.1	10	Frequency
apertureDiameternumber	m	at least 0.001	0.3	Physical aperture diameter (for dish/horn antennas)
apertureEfficiencynumber	%	10 … 100	55	Typical: 55-65% for parabolic dish

Outputs

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

Outputs of antenna-beamwidth
Field	Unit	Description
beamwidthHPBWheadline	°	3 dB Beamwidth
beamwidthNulls	°	First Null Beamwidth
effectiveArea	m²	Effective Aperture Area
wavelength	mm	Wavelength
gainFromAperture	dBi	Gain from Aperture

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": "antenna-beamwidth",
    "inputs": {
      "gain": 20,
      "frequency": 10,
      "apertureDiameter": 0.3,
      "apertureEfficiency": 55
    }
  }'

import rftools

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

result = client.calculate("antenna-beamwidth", {
    "gain": 20,
    "frequency": 10,
    "apertureDiameter": 0.3,
    "apertureEfficiency": 55,
})
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": "antenna-beamwidth",
    "inputs": {
      "gain": 20,
      "frequency": 10,
      "apertureDiameter": 0.3,
      "apertureEfficiency": 55
    }
  }),
});
console.log(response.status, await response.json());

package main

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

func main() {
	body := []byte(`{
	  "slug": "antenna-beamwidth",
	  "inputs": {
	    "gain": 20,
	    "frequency": 10,
	    "apertureDiameter": 0.3,
	    "apertureEfficiency": 55
	  }
	}`)
	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": "antenna-beamwidth",
  "values": {
    "beamwidthHPBW": 6.995157353333334,
    "beamwidthNulls": 13.990314706666668,
    "effectiveArea": 0.007152066466270221,
    "wavelength": 29.979245799999998,
    "gainFromAperture": 27.352635384659813
  },
  "warnings": [],
  "errors": [],
  "provenance": {
    "method": "calculator:antenna-beamwidth",
    "version": "api@3f2c1a9b04de",
    "formulaRef": "Antenna Theory: Analysis and Design, 4th ed., Constantine A. Balanis (2016), Chapter 2 — Directivity, gain, and half-power beamwidth",
    "assumptions": [],
    "validRange": {
      "status": "inside",
      "bounds": {
        "gain": {
          "min": 0,
          "max": null,
          "unit": "dBi"
        },
        "frequency": {
          "min": 0.1,
          "max": null,
          "unit": "GHz"
        },
        "apertureDiameter": {
          "min": 0.001,
          "max": null,
          "unit": "m"
        },
        "apertureEfficiency": {
          "min": 10,
          "max": 100,
          "unit": "%"
        }
      },
      "outside": [],
      "model": null
    },
    "computedAt": "2026-09-24T14:05:11.003Z",
    "inputs": {
      "gain": 20,
      "frequency": 10,
      "apertureDiameter": 0.3,
      "apertureEfficiency": 55
    },
    "seed": null,
    "elapsedSeconds": 0.003
  }
}

{
  "detail": [
    {
      "type": "float_parsing",
      "loc": [
        "body",
        "inputs",
        "gain"
      ],
      "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 pageAntenna Beamwidth & Gain Calculator, at these values