action cloudrf_area {
  label: "Create a point-to-multipoint heatmap"
  description: "An area coverage assumes the same receiver height at all locations out to fixed radius (maximum 300km). Due to it's exhaustive processing it is the slowest of all the API calls. Speed can be improved significantly by adjusting the resolution 'res' parameter. A basic request needs transmitter, receiver, antenna and output objects defined as a minimum. Model and environment options will enhance accuracy."
  provider: cloudrf
  method: POST
  path: "/area"
  encoding: json
  input: {
    type: "object"
    properties: {
      antenna: {
        type: "object"
        properties: {
          ant: {
            type: "integer"
            format: "int32"
            description: "Antenna pattern code. 1=Vertical dipole (Omni-directional)"
          }
          azi: {
            type: "integer"
            format: "int32"
            description: "Antenna azimuth in degrees north"
          }
          hbw: {
            type: "integer"
            format: "int32"
            description: "Custom antenna horizontal beamwidth in degrees. For use only with ant=0"
          }
          pol: {
            type: "string"
            description: "Antenna polarization as either h or v"
            enum: ["h", "v"]
          }
          tlt: {
            type: "number"
            format: "float"
            description: "Antenna tilt in degrees below the horizon (inverted)"
          }
          txg: {
            type: "number"
            format: "float"
            description: "Transmitter antenna gain in dBi"
          }
          txl: {
            type: "number"
            format: "float"
            description: "Feeder loss in dB"
          }
          vbw: {
            type: "integer"
            format: "int32"
            description: "Custom antenna vertical beamwidth in degrees. For use only with ant=0"
          }
        }
      }
      environment: {
        type: "object"
        properties: {
          cll: {
            type: "integer"
            format: "int32"
            description: "Clutter loss. 0=None/DSM only, 1=Hard / LOS mode, 2=Soft / NLOS mode"
          }
          clm: {
            type: "integer"
            format: "int32"
            description: "Clutter mode. 0=None/DSM only, 1=System & custom clutter, 2=Custom clutter only"
          }
          mat: {
            type: "number"
            format: "float"
            description: "Clutter attenuation override in dB/m based on a tree block OR hollow building. Light foliage=0.1dB/m, brick=1.0dB/m, concrete=5dB/m"
          }
        }
      }
      model: {
        type: "object"
        properties: {
          cli: {
            type: "integer"
            format: "int32"
            description: "Radio climate for ITM model (1). 1: Equatorial (Congo) 2: Continental Subtropical (Sudan) 3: Maritime Subtropical (West coast of Africa) 4: Desert (Sahara) 5: Continental Temperate 6: Maritime Temperate, over land (UK and west coasts of US & EU) 7: Maritime Temperate, over sea"
          }
          ked: {
            type: "integer"
            description: "Knife edge diffraction for enhancing basic empirical models (Already in ITM)"
          }
          pe: {
            type: "integer"
            format: "int32"
            description: "Propagation model subtype/environment. 1=Conservative/Urban,2=Average/Suburban,3=Optimistic/rural"
          }
          pm: {
            type: "integer"
            format: "int32"
            description: "Propagation model. 1=Irregular Terrain Model, 2=Line of Sight (LOS), 3=Hata, 4=ECC33, 5=SUI Microwave, 6=COST231, 7=Free space path loss, 9=Ericsson9999, 10=Plane earth loss, 11=Egli."
          }
          rel: {
            type: "integer"
            format: "int32"
            description: "ITM model required reliability as %"
          }
          ter: {
            type: "integer"
            format: "int32"
            description: "Terrain code for ITM model (1). 1=Water,2=Wet ground,3=Farmland,4=Forest/Average,5=Mountain/Sand,6=City/Poor ground"
          }
        }
      }
      network: {
        type: "string"
        description: "Network name/group"
      }
      output: {
        type: "object"
        properties: {
          ber: {
            type: "integer"
            format: "int32"
            description: "Bit error rate. 1=0.1, 2=0.01, 3=0.001, 4=0.0001,5=0.00001,6=0.000001. >6=Lora: 7=SF7,8=SF8,9=SF9,10=SF10,11=SF11,12=SF12"
          }
          col: {
            type: "string"
            description: "Colour schema code OR filename. 1 = Cellular (5), 2=Red, 3=Green, 4=Blue, 5=Microwave(7), 7=Custom RGB, 8=Automatic by frequency, 9=Greyscale / GIS, 10=Rainbow(24), 11=Green/Blue/Red, 13=Sub noise floor (10), 14=TV broadcasting (4), 15=Red threshold, 16=Green threshold, 17=Blue threshold. RAINBOW.dBm, CUSTOMSCHEMA.dBm.."
          }
          mod: {
            type: "integer"
            format: "int32"
            description: "Modulation. 1=4QAM,2=16QAM,3=64QAM,4=256QAM,5=1024QAM,6=BPSK,7=QPSK,8=8PSK,9=16PSK,10=32PSK,11=LoRa"
          }
          nf: {
            type: "integer"
            format: "int32"
            description: "Noise floor in dBm for use with out=4 / SNR"
          }
          out: {
            type: "integer"
            format: "int32"
            description: "Measured units. 1=dB,2=dBm,3=dBuV,4=SNR"
          }
          rad: {
            type: "number"
            format: "float"
            description: "Radius in kilometres for output"
          }
          res: {
            type: "integer"
            format: "int32"
            description: "Resolution in metres for output"
          }
          units: {
            type: "string"
            description: "Distance units in either metres/kilometres (metric) or feet/miles (imperial)"
            enum: ["metric", "imperial"]
          }
        }
      }
      receiver: {
        type: "object"
        properties: {
          alt: {
            type: "number"
            format: "float"
            description: "Altitude above ground level in metres OR feet"
          }
          lat: {
            type: "number"
            format: "float"
            description: "Latitude in decimal degrees"
          }
          lon: {
            type: "number"
            format: "float"
            description: "Longitude in decimal degrees"
          }
          rxg: {
            type: "number"
            format: "float"
            description: "Receiver antenna gain in dBi"
          }
          rxs: {
            type: "number"
            format: "float"
            description: "Receiver sensitivity/threshold in measured units defined by 'out' param"
          }
        }
      }
      site: {
        type: "string"
        description: "Site name"
      }
      transmitter: {
        type: "object"
        properties: {
          alt: {
            type: "number"
            format: "float"
            description: "Altitude above ground level in metres OR feet"
          }
          bwi: {
            type: "number"
            format: "float"
            description: "Bandwidth in MHz. 1MHz has a noise floor of -114dBm. 10MHz = -104dBm, 20MHz = -101dBm"
          }
          frq: {
            type: "number"
            format: "float"
            description: "Centre frequency in megahertz"
          }
          lat: {
            type: "number"
            format: "float"
            description: "Latitude in decimal degrees"
          }
          lon: {
            type: "number"
            format: "float"
            description: "Longitude in decimal degrees"
          }
          txw: {
            type: "number"
            format: "float"
            description: "Transmitter power in watts before the antenna"
          }
        }
      }
    }
  }
  output: {
    type: "object"
    additionalProperties: true
  }
}