Documentation sections

Antenna Downtilt Calculator

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

Slug antenna-downtilt. Find the downtilt that puts a sector antenna's upper half-power edge on the cell edge, the ground footprint of the half-power beam, and the gain toward the cell edge from the 3GPP vertical pattern, with Earth curvature included.

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-downtilt
Name	Unit	Range	Default	Description
antennaHeightnumber	m	at least 0.1	30	Height of the antenna's centre above the ground
ueHeightnumber	m	at least 0	1.5	Height of the handset or terminal above the ground
cellEdgenumber	m	at least 1	1000	Ground distance from the mast to the edge of the cell
verticalBeamwidthnumber	°	0.1 … 179	7	Vertical half-power beamwidth from the antenna datasheet
kFactornumber	none	at least 0.1	1.3333333333333333	k = 4/3 for the standard atmosphere
appliedTiltnumber	°	−90 … 90	5	The total tilt actually set (electrical plus mechanical), for the footprint and the edge gain

Outputs

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

Outputs of antenna-downtilt
Field	Unit	Description
recommendedTiltheadline	°	Recommended Downtilt
depressionAngle	°	Depression Angle to Cell Edge
innerEdge	m	Inner Half-Power Edge (recommended tilt)
appliedInnerEdge	m	Inner Half-Power Edge (applied tilt)
appliedOuterEdge	m	Outer Half-Power Edge (applied tilt)
edgeGain	dB	Relative Gain Toward Cell Edge (applied tilt)
losDistance	km	Line-of-Sight Distance

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-downtilt",
    "inputs": {
      "antennaHeight": 30,
      "ueHeight": 1.5,
      "cellEdge": 1000,
      "verticalBeamwidth": 7,
      "kFactor": 1.3333333333333333,
      "appliedTilt": 5
    }
  }'

import rftools

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

result = client.calculate("antenna-downtilt", {
    "antennaHeight": 30,
    "ueHeight": 1.5,
    "cellEdge": 1000,
    "verticalBeamwidth": 7,
    "kFactor": 1.3333333333333333,
    "appliedTilt": 5,
})
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-downtilt",
    "inputs": {
      "antennaHeight": 30,
      "ueHeight": 1.5,
      "cellEdge": 1000,
      "verticalBeamwidth": 7,
      "kFactor": 1.3333333333333333,
      "appliedTilt": 5
    }
  }),
});
console.log(response.status, await response.json());

package main

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

func main() {
	body := []byte(`{
	  "slug": "antenna-downtilt",
	  "inputs": {
	    "antennaHeight": 30,
	    "ueHeight": 1.5,
	    "cellEdge": 1000,
	    "verticalBeamwidth": 7,
	    "kFactor": 1.3333333333333333,
	    "appliedTilt": 5
	  }
	}`)
	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-downtilt",
  "values": {
    "recommendedTilt": 5.135857529058267,
    "depressionAngle": 1.635857529058267,
    "innerEdge": 187.66674981063792,
    "appliedInnerEdge": 190.71227737998746,
    "appliedOuterEdge": 1091.0468217457628,
    "edgeGain": -2.771621526071988,
    "losDistance": 27.624261535006116
  },
  "warnings": [],
  "errors": [],
  "provenance": {
    "method": "calculator:antenna-downtilt",
    "version": "api@3f2c1a9b04de",
    "formulaRef": "3GPP TR 38.901 V17.0.0, Table 7.3-1; ITU-R P.526-15, Eqs. (21) and (44); ITU-R P.834-9, §2",
    "assumptions": [
      {
        "code": "smooth-earth",
        "text": "The ground is a smooth sphere of effective radius k × 6371 km; terrain and clutter are not modelled."
      },
      {
        "code": "3gpp-vertical-pattern",
        "text": "The vertical pattern is the parabolic main lobe with a 30 dB floor of 3GPP TR 38.901 Table 7.3-1, with the reader's half-power beamwidth."
      }
    ],
    "validRange": {
      "status": "inside",
      "bounds": {
        "antennaHeight": {
          "min": 0.1,
          "max": null,
          "unit": "m"
        },
        "ueHeight": {
          "min": 0,
          "max": null,
          "unit": "m"
        },
        "cellEdge": {
          "min": 1,
          "max": null,
          "unit": "m"
        },
        "verticalBeamwidth": {
          "min": 0.1,
          "max": 179,
          "unit": "°"
        },
        "kFactor": {
          "min": 0.1,
          "max": null,
          "unit": ""
        },
        "appliedTilt": {
          "min": -90,
          "max": 90,
          "unit": "°"
        }
      },
      "outside": [],
      "model": null
    },
    "computedAt": "2026-09-24T14:05:11.003Z",
    "inputs": {
      "antennaHeight": 30,
      "ueHeight": 1.5,
      "cellEdge": 1000,
      "verticalBeamwidth": 7,
      "kFactor": 1.3333333333333333,
      "appliedTilt": 5
    },
    "seed": null,
    "elapsedSeconds": 0.003
  }
}

{
  "detail": [
    {
      "type": "float_parsing",
      "loc": [
        "body",
        "inputs",
        "antennaHeight"
      ],
      "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 Downtilt Calculator, at these values