Seções da documentação

Calcular

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

Executa qualquer uma das 255 calculadoras com as entradas que você digitaria na página dela, nas unidades que a página mostra, e devolve cada saída, os avisos e a procedência em JSON.

Autentique-se com o cabeçalho X-API-Key. As chaves começam com rfc_ e são criadas no painel. Toda chamada é contabilizada na cota mensal da conta: 5 no Free, 100 no Pro, 10.000 no API.

Corpo da requisição

CalculateRequest
Campo	Descrição
slugobrigatóriostring	A calculadora, pelo slug do endereço da página dela, por exemplo rf-link-budget. Todos os slugs estão listados em Slugs e entradas.
inputsobrigatórioobject of numbers	Valores de entrada sob as chaves de entrada da calculadora, nas unidades que a referência dela lista. Envie todas as entradas: a maioria é obrigatória, e uma chamada sem alguma delas é recusada (400); uma entrada opcional omitida assume o padrão mostrado na referência. Uma chave que a calculadora não lê é ignorada com um aviso.

Entradas de rf-link-budget

Geradas a partir da definição da calculadora. Uma entrada fora da sua faixa ainda é calculada e sinalizada na procedência. As entradas de cada calculadora estão em Slugs e entradas.

Entradas de rf-link-budget
Nome	Unidade	Faixa	Padrão	Descrição
txPowernúmero	dBm	−30 … 100	30	Potência de saída do transmissor
txGainnúmero	dBi	−30 … 60	3	Ganho da antena TX em dBi
txCableLossnúmero	dB	0 … 20	1	Perdas de cabo TX + conector (valor positivo)
frequencynúmero	MHz	0.1 … 1000000	2400	Frequência central
distancenúmero	km	0.001 … 1000000	1	Distância entre TX e RX
rainFadenúmero	dB	0 … 50	0	Atenuação da chuva de acordo com ITU-R P.838. Use 0 para links terrestres com linha de visão; 3—20 dB para links de satélite acima de 10 GHz em zonas de chuva forte.
atmosphericLossnúmero	dB	0 … 20	0.5	Absorção gasosa (O₂ a 60 GHz: ~15 dB/km; H₂O a 22 GHz: ~0,2 dB/km). Use 0,5 dB típico para links terrestres abaixo de 6 GHz.
pointingLossnúmero	dB	0 … 10	0	Perda de desalinhamento da antena. Pratos com feixe de lápis: 0,5—3 dB. Antenas omnidirecionais ou de feixe amplo: 0 dB.
extraLossCountnúmero	nenhuma	0 … 4	0	Quantos termos extras de perda o orçamento inclui, como descasamento de polarização, perda pelo corpo ou folhagem
extraLoss1número	dB	0 … 50	0	Uma perda extra no percurso, como descasamento de polarização, perda pelo corpo, folhagem ou uma parede
extraLoss2número	dB	0 … 50	0	Uma perda extra no percurso, como descasamento de polarização, perda pelo corpo, folhagem ou uma parede
extraLoss3número	dB	0 … 50	0	Uma perda extra no percurso, como descasamento de polarização, perda pelo corpo, folhagem ou uma parede
extraLoss4número	dB	0 … 50	0	Uma perda extra no percurso, como descasamento de polarização, perda pelo corpo, folhagem ou uma parede
rxGainnúmero	dBi	−30 … 60	3	Ganho de antena RX em dBi
rxCableLossnúmero	dB	0 … 20	1	Perdas de cabo RX e conector
rxSensitivitynúmero	dBm	−160 … 0	-90	Nível mínimo de sinal a receber
targetMarginnúmero	dB	0 … 60	10	A margem de esmaecimento que o link deve manter acima da sensibilidade do receptor. O status passa igual ou superior a ele e falha abaixo de 0 dB.

Resposta

CalculateResponse
Campo	Descrição
slugstring	A calculadora, como pedida.
valuesobject of numbers	Cada saída pela chave, nas unidades que a referência lista. null quando um valor é ilimitado ou indefinido, como a perda de retorno de um casamento perfeito.
warningsstring[]	Os avisos da própria calculadora e depois os da API: uma entrada não lida, uma entrada fora da faixa para a qual a calculadora é declarada.
errorsstring[]	Os erros da calculadora; vazio em caso de sucesso.
provenanceobject	Como os valores foram calculados: método, versão do motor, referência da fórmula, premissas e faixa válida. Veja Procedência.

As saídas de rf-link-budget, em values:

Saídas de rf-link-budget
Campo	Unidade	Descrição
fspl	dB	Perda de caminho de espaço livre
eirp	dBm	EIRP
rxPower	dBm	Potência recebida
linkMarginprincipal	dB	Margem do link
maxRangeKm	km	Alcance máximo
totalAdditionalLoss	dB	Perda adicional total
maxRangeAtTarget	km	Intervalo na margem alvo
wavelength	mm	Comprimento de onda
fresnelRadius	m	Raio da primeira zona de Fresnel

Erros

Erros de POST /calculate
Status	Exceção Python	Quando
400	ValidationError	A requisição não pode ser respondida como foi enviada: uma entrada que não é um número finito, uma resolução que não pode ser montada, um corpo de trabalho fora do contrato, ou um lote vazio ou acima do limite. Nada é contabilizado.
401	AuthError	Nenhuma chave foi enviada (o corpo traz keyUrl), ou a chave não foi emitida por nós, ou foi revogada. Nunca diz respeito à cota.
402	QuotaError	A cota mensal da conta se esgotou, em toda rota contabilizada. Nada foi contabilizado. Retry-After dá os segundos até resetAt.
404	NotFound	Não existe esse slug de calculadora, tipo de trabalho ou trabalho. Nada é contabilizado.
422	ValidationError	O corpo não pode ser lido: falta um campo obrigatório, ou um valor tem o tipo errado (uma entrada enviada como texto). Respondido antes de a rota ser executada.
429	RateLimitError	Requisições demais em um minuto para a credencial, ou trabalhos demais na fila ou em execução ao mesmo tempo. Retry-After diz quando tentar de novo.
500	APIError	O resultado foi calculado mas não pôde ser devolvido, ou uma resolução falhou. Nada foi cobrado.
503	APIError	Não foi possível verificar a chave ou o contador da cota, ou não foi possível colocar um trabalho na fila. Nada entrou na fila nem foi cobrado; tente de novo.

Todas as verificações acontecem antes de qualquer contabilização: a chave, a calculadora e depois as entradas. Veja Erros para cada corpo.

Experimente

Envie uma requisição desta página com a sua própria chave. Ela é contabilizada como qualquer outra chamada.

CalculadoraEntradas (JSON)Chave de API

Uma requisição precisa de uma chave e é contabilizada na cota da conta dessa chave. Obtenha uma chave gratuita.

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"
}

Um slug que não existe. Nada foi contabilizado.

{
  "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"
    }
  ]
}

Uma entrada enviada como texto. Respondido antes de a rota ser executada; nada foi contabilizado.

{
  "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"
}

A cota do mês se esgotou, com 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/"
}

Requisições demais em um minuto, com Retry-After.

As mesmas entradas na página da calculadoraCalculadora de orçamento RF Link, com estes valores no endereço