openapi: 3.0.1
servers:
  - url: https://api.cloudrf.com
info:
  contact:
    email: support@cloudrf.com
  description: Use this JSON API to build and test radio links for any radio, anywhere. Authenticate with your API2.0 key in the request header as key
  termsOfService: https://cloudrf.com/terms-and-conditions/
  title: Cloud-RF API
  version: 2.0.0
  x-apisguru-categories:
    - telecom
    - location
  x-logo:
    url: https://cloudrf.com/wp-content/uploads/2021/05/CloudRF_logo_70px.png
  x-origin:
    - format: openapi
      url: https://api.cloudrf.com/swagger-ui/Cloud-RF_API2.0.yaml
      version: "3.0"
  x-providerName: cloudrf.com
security:
  - ApiKeyAuth: []
tags:
  - description: Create and test links, site heatmaps and networks
    externalDocs:
      description: Find out more
      url: https://cloudrf.com
    name: Create, analyse and manage
paths:
  /archive/delete:
    get:
      description: Warning! you could lose data. This function will delete the entry from the database and the file from the disk. Accidental deletion can be reversed by contacting support with biscuits who maintain an offsite backup.
      operationId: delete
      parameters:
        - description: Unique calculation ID number
          in: query
          name: cid
          required: true
          schema:
            type: integer
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: Delete a calculation from the database.
      tags:
        - Manage
  /archive/delete/network:
    get:
      description: Warning! you could lose data. This function will delete the entry from the database and the file from the disk. Accidental deletion can be reversed by contacting support with biscuits who maintain an offsite backup.
      operationId: deleteNetwork
      parameters:
        - description: Network name
          in: query
          name: nid
          required: true
          schema:
            type: string
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: Delete an entire network
      tags:
        - Manage
  /archive/export:
    get:
      description: Download your data in a format suitable for a third party viewer like Google Earth or ESRI Arcmap.
      operationId: export
      parameters:
        - description: Calculation file name
          in: query
          name: file
          required: true
          schema:
            type: string
        - description: "Raster/Vector file format: KML, KMZ, SHP, GeoTIFF"
          in: query
          name: fmt
          required: true
          schema:
            enum:
              - kml
              - kml
              - kmzppa
              - shp
              - tiff
            type: string
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: Export a calculation in a GIS file format
      tags:
        - Manage
  /archive/list:
    get:
      description: List your area and path calculations, sorted by time and limited to the last few hundred. To fetch all for a given network append a 'net' filter with the network name.
      operationId: list
      parameters:
        - description: North bounding box
          in: query
          name: n
          required: false
          schema:
            format: float
            type: number
        - description: East bounding box
          in: query
          name: e
          required: false
          schema:
            format: float
            type: number
        - description: South bounding box
          in: query
          name: s
          required: false
          schema:
            format: float
            type: number
        - description: West bounding box
          in: query
          name: w
          required: false
          schema:
            format: float
            type: number
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: List calculations from your archive
      tags:
        - Manage
  /area:
    post:
      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.
      operationId: area
      requestBody:
        content:
          application/json:
            schema:
              properties:
                antenna:
                  $ref: "#/components/schemas/Antenna"
                environment:
                  $ref: "#/components/schemas/Environment"
                model:
                  $ref: "#/components/schemas/Model"
                network:
                  default: Testing
                  description: Network name/group
                  maxLength: 24
                  minLength: 1
                  type: string
                output:
                  $ref: "#/components/schemas/Output"
                receiver:
                  $ref: "#/components/schemas/Receiver"
                site:
                  default: A1
                  description: Site name
                  maxLength: 24
                  minLength: 1
                  type: string
                transmitter:
                  $ref: "#/components/schemas/Transmitter"
              type: object
        description: A basic request needs transmitter, receiver, antenna and output objects defined as a minimum. Model and environment options will enhance accuracy.
        required: true
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: Create a point-to-multipoint heatmap
      tags:
        - Create
  /clutter/add:
    post:
      description: Upload GeoJSON lineString and polygon features to your account. The height property is in metres and the material code / type / attenuation are.. 1	Trees –	0.25,2Trees +	0.5,3	Timber –	1.0,4	Timber +	1.5,5	Brick – 	1.5,6	Brick +	2.0,7	Concrete –	3.0,8	Concrete +	4.0,9	Metal	6.0
      operationId: addClutter
      requestBody:
        content:
          application/json:
            schema:
              properties:
                features:
                  items:
                    $ref: "#/components/schemas/Feature"
                  type: array
                name:
                  default: Clutter
                  type: string
                type:
                  default: FeatureCollection
                  type: string
              type: object
        required: true
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: Upload clutter data as GeoJSON
      tags:
        - Manage
  /interference:
    get:
      description: Merge and analyse sites within a network channel to determine the best server at a given location. Each site will be dynamically allocated a monochrome colour from a palette and the strongest signal promoted at a given location.
      operationId: interference
      parameters:
        - description: Network name eg. Overlapping broadcast stations
          in: query
          name: network
          required: true
          schema:
            type: string
        - description: Interference layer name eg. QRM_map
          in: query
          name: name
          required: true
          schema:
            type: string
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: Find the best server for overlapping coverage
      tags:
        - Analyse
  /mesh:
    get:
      description: A merge of 'area' calculations for a network to create a single super layer. Stronger signals are promoted over weaker ones. The same colour key must be used.
      operationId: mesh
      parameters:
        - description: Network name eg. 100_BLUE_repeaters_nationwide
          in: query
          name: network
          required: true
          schema:
            type: string
        - description: Super layer name eg. National_map
          in: query
          name: name
          required: true
          schema:
            type: string
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: Merge sites into a super layer.
      tags:
        - Analyse
  /network:
    get:
      description: Query your network to find the best server(s) for a given receiver/customer location. A previously generated network is required.
      operationId: network
      parameters:
        - description: Network name
          in: query
          name: net
          required: true
          schema:
            type: string
        - description: Super layer name
          in: query
          name: nam
          required: true
          schema:
            type: string
        - description: Latitude in decimal degrees
          in: query
          name: lat
          required: true
          schema:
            format: float
            type: number
        - description: Longitude in decimal degrees
          in: query
          name: lon
          required: true
          schema:
            format: float
            type: number
        - description: Height above ground level in metres
          in: query
          name: alt
          required: true
          schema:
            format: int32
            type: integer
        - description: Receiver gain in dBi
          in: query
          name: rxg
          required: false
          schema:
            format: float
            type: number
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: Find the best server for somewhere
      tags:
        - Analyse
  /path:
    post:
      description: A path profile is a single link from A to B. It is much faster than an area calculation and can be used out to 300km. A basic request needs transmitter, receiver, antenna and output objects defined as a minimum. Model and environment options will enhance accuracy.
      operationId: path
      requestBody:
        content:
          application/json:
            schema:
              properties:
                antenna:
                  $ref: "#/components/schemas/Antenna"
                environment:
                  $ref: "#/components/schemas/Environment"
                model:
                  $ref: "#/components/schemas/Model"
                network:
                  default: Testing
                  description: Network name/group
                  maxLength: 24
                  minLength: 1
                  type: string
                output:
                  $ref: "#/components/schemas/Output"
                receiver:
                  $ref: "#/components/schemas/Receiver"
                site:
                  default: Link
                  description: Site name
                  maxLength: 24
                  minLength: 1
                  type: string
                transmitter:
                  $ref: "#/components/schemas/Transmitter"
              type: object
        description: A basic request needs transmitter, receiver, antenna and output objects defined as a minimum. Model and environment options will enhance accuracy.
        required: true
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: Point-to-point path profile analysis (Tx to Rx)
      tags:
        - Create
  /points:
    post:
      description: The points function tests many transmitters and one receiver and is designed for route analysis. A minimal request needs a transmitters array of (latitude,longitude,altitude) locations, antenna, receiver and output objects defined as a minimum. Model and environment options will enhance accuracy.
      operationId: points
      requestBody:
        content:
          application/json:
            schema:
              properties:
                antenna:
                  $ref: "#/components/schemas/Antenna"
                environment:
                  $ref: "#/components/schemas/Environment"
                model:
                  $ref: "#/components/schemas/Model"
                network:
                  default: Testing
                  description: Network name/group
                  maxLength: 24
                  minLength: 1
                  type: string
                output:
                  $ref: "#/components/schemas/Output"
                points:
                  items:
                    $ref: "#/components/schemas/Point"
                  type: array
                receiver:
                  $ref: "#/components/schemas/Receiver"
                site:
                  default: Points
                  description: Site name
                  maxLength: 24
                  minLength: 1
                  type: string
                transmitter:
                  $ref: "#/components/schemas/Transmitter"
              type: object
        description: A minimal request needs a transmitters array of (latitude,longitude,altitude) locations, antenna, receiver and output objects defined as a minimum. Model and environment options will enhance accuracy.
        required: true
      responses:
        "200":
          content: {}
          description: Request OK
      security:
        - ApiKeyAuth: []
      summary: Point-to-multipoint path profile analysis (Many Tx, one Rx)
      tags:
        - Create
components:
  schemas:
    Antenna:
      properties:
        ant:
          default: 1
          description: Antenna pattern code. 1=Vertical dipole (Omni-directional)
          format: int32
          type: integer
        azi:
          default: 0
          description: Antenna azimuth in degrees north
          format: int32
          maximum: 360
          minimum: 0
          type: integer
        hbw:
          default: 0
          description: Custom antenna horizontal beamwidth in degrees. For use only with ant=0
          format: int32
          maximum: 360
          minimum: 0
          type: integer
        pol:
          default: v
          description: Antenna polarization as either h or v
          enum:
            - h
            - v
          type: string
        tlt:
          default: 0
          description: Antenna tilt in degrees below the horizon (inverted)
          format: float
          maximum: 90
          minimum: -10
          type: number
        txg:
          default: 2.15
          description: Transmitter antenna gain in dBi
          format: float
          maximum: 60
          minimum: -10
          type: number
        txl:
          default: 0
          description: Feeder loss in dB
          format: float
          maximum: 60
          minimum: 0
          type: number
        vbw:
          default: 0
          description: Custom antenna vertical beamwidth in degrees. For use only with ant=0
          format: int32
          maximum: 360
          minimum: 0
          type: integer
      type: object
    Environment:
      properties:
        cll:
          default: 2
          description: Clutter loss. 0=None/DSM only, 1=Hard / LOS mode, 2=Soft / NLOS mode
          format: int32
          maximum: 2
          minimum: 1
          type: integer
        clm:
          default: 1
          description: Clutter mode. 0=None/DSM only, 1=System & custom clutter, 2=Custom clutter only
          format: int32
          maximum: 2
          minimum: 1
          type: integer
        mat:
          default: 0.25
          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
          format: float
          maximum: 9
          minimum: 0.1
          type: number
      type: object
    Feature:
      properties:
        geometry:
          default: "{'type':'Polygon','coordinates':[[]]}"
          type: string
        properties:
          default: "{'height':4,'material':1}"
          type: string
        type:
          default: Feature
          type: string
      type: object
    Model:
      properties:
        cli:
          default: 6
          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"
          format: int32
          maximum: 7
          minimum: 1
          type: integer
        ked:
          default: 0
          description: Knife edge diffraction for enhancing basic empirical models (Already in ITM)
          maximum: 1
          minimum: 0
          type: integer
        pe:
          default: 2
          description: Propagation model subtype/environment. 1=Conservative/Urban,2=Average/Suburban,3=Optimistic/rural
          format: int32
          maximum: 3
          minimum: 1
          type: integer
        pm:
          default: 1
          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.
          format: int32
          maximum: 20
          minimum: 1
          type: integer
        rel:
          default: 95
          description: ITM model required reliability as %
          format: int32
          maximum: 99
          minimum: 50
          type: integer
        ter:
          default: 4
          description: Terrain code for ITM model (1). 1=Water,2=Wet ground,3=Farmland,4=Forest/Average,5=Mountain/Sand,6=City/Poor ground
          format: int32
          maximum: 6
          minimum: 1
          type: integer
      type: object
    Output:
      properties:
        ber:
          default: 0
          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"
          format: int32
          maximum: 10
          minimum: 0
          type: integer
        col:
          default: RAINBOW.dBm
          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..
          type: string
        mod:
          default: 0
          description: Modulation. 1=4QAM,2=16QAM,3=64QAM,4=256QAM,5=1024QAM,6=BPSK,7=QPSK,8=8PSK,9=16PSK,10=32PSK,11=LoRa
          format: int32
          maximum: 11
          minimum: 1
          type: integer
        nf:
          default: -114
          description: Noise floor in dBm for use with out=4 / SNR
          format: int32
          maximum: -90
          minimum: -120
          type: integer
        out:
          default: 2
          description: Measured units. 1=dB,2=dBm,3=dBuV,4=SNR
          format: int32
          maximum: 4
          minimum: 1
          type: integer
        rad:
          default: 5
          description: Radius in kilometres for output
          format: float
          maximum: 300
          minimum: 0.03
          type: number
        res:
          default: 10
          description: Resolution in metres for output
          format: int32
          maximum: 200
          minimum: 2
          type: integer
        units:
          default: metric
          description: Distance units in either metres/kilometres (metric) or feet/miles (imperial)
          enum:
            - metric
            - imperial
          type: string
      type: object
    Point:
      properties:
        alt:
          default: 1
          description: Altitude above ground level in metres OR feet
          format: float
          maximum: 60000
          minimum: 0.1
          type: number
        lat:
          default: 38.916
          description: Latitude in decimal degrees
          format: float
          maximum: 89
          minimum: -89
          type: number
        lon:
          default: 1.411
          description: Longitude in decimal degrees
          format: float
          maximum: 180
          minimum: -180
          type: number
      type: object
    Receiver:
      properties:
        alt:
          default: 0.1
          description: Altitude above ground level in metres OR feet
          format: float
          maximum: 60000
          minimum: 0.1
          type: number
        lat:
          default: 0
          description: Latitude in decimal degrees
          format: float
          maximum: 89
          minimum: -89
          type: number
        lon:
          default: 0
          description: Longitude in decimal degrees
          format: float
          maximum: 180
          minimum: -180
          type: number
        rxg:
          default: 2.15
          description: Receiver antenna gain in dBi
          format: float
          maximum: 60
          minimum: -10
          type: number
        rxs:
          default: -90
          description: Receiver sensitivity/threshold in measured units defined by 'out' param
          format: float
          maximum: 200
          minimum: -140
          type: number
      type: object
    Transmitter:
      properties:
        alt:
          default: 1
          description: Altitude above ground level in metres OR feet
          format: float
          maximum: 60000
          minimum: 0.1
          type: number
        bwi:
          default: 0.1
          description: Bandwidth in MHz. 1MHz has a noise floor of -114dBm. 10MHz = -104dBm, 20MHz = -101dBm
          format: float
          maximum: 100
          minimum: 0.1
          type: number
        frq:
          default: 868
          description: Centre frequency in megahertz
          format: float
          maximum: 100000
          minimum: 1
          type: number
        lat:
          default: 38.916
          description: Latitude in decimal degrees
          format: float
          maximum: 89
          minimum: -89
          type: number
        lon:
          default: 1.448
          description: Longitude in decimal degrees
          format: float
          maximum: 180
          minimum: -180
          type: number
        txw:
          default: 0.1
          description: Transmitter power in watts before the antenna
          format: float
          maximum: 2000000
          minimum: 0.001
          type: number
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: key
      type: apiKey
