CloudRF API (3.31)

Download OpenAPI specification:

The CloudRF API enables users to model and test radio propagation for any radio, anywhere. Authenticate by passing your API key in the request header as key. Set up a CloudRF.com account to generate this key. All data is transferred as JSON. For detailed documentation, visit docs.cloudrf.com.

Create

This set of endpoints allows the user to create new links, site heatmaps, routes, and networks.

Multipoint coverage heatmap

This endpoint returns an omni-directional coverage plot (point-to-multipoint) as an image. This function assumes a consistent receiver height at all locations out to fixed radius. Speed can be improved by adjusting the resolution with the "res" parameter. A standard request requires a transmitter, receiver, antenna and output objects. Providing a model and environment enhances accuracy.

Authorizations:
ApiKeyAuth
Request Body schema: application/json

The request payload providing the site properties.

site
string [ 2 .. 50 ] characters
Default: "A1"

Site name.

network
required
string [ 2 .. 50 ] characters
Default: "Testing"

Network name/group.

engine
number <float>
Default: 2
Enum: 1 2

Processing engine to handle the request:

  • 1 - GPU (requires a GPU enabled server)
  • 2 - CPU
required
object
required
object (Receiver)
required
object (Antenna)
object (Model)
object (Environment)
required
object (OutputWithBounds)

Responses

Request samples

Content type
application/json
{
  • "site": "A1",
  • "network": "Testing",
  • "transmitter": {
    },
  • "receiver": {
    },
  • "antenna": {
    },
  • "environment": {
    },
  • "output": {
    }
}

Response samples

Content type
application/json
{}

Point-to-point (Tx to Rx)

This endpoint allows users to analyse a point-to-point path. A path profile is a single link from A to B. A basic request requires transmitter, receiver, antenna, and output objects; providing the model and environment objects enhances accuracy.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
site
string [ 2 .. 50 ] characters
Default: "Link"

Site name.

network
string [ 2 .. 50 ] characters
Default: "Testing"

Network name/group.

required
object (Transmitter)
required
object (Antenna)
required
object (Receiver)
object (Model)
object (Environment)
required
object (Output)

Responses

Request samples

Content type
application/json
{
  • "site": "Link",
  • "network": "Testing",
  • "transmitter": {
    },
  • "antenna": {
    },
  • "receiver": {
    },
  • "model": {
    },
  • "environment": {
    },
  • "output": {
    }
}

Response samples

Content type
application/json
{
  • "Engine": "Sleipnir 1.18",
  • "Frequency MHz": 868,
  • "Propagation model": "ITM",
  • "Earth dielectric constant": 14,
  • "Earth conductivity": 0.01,
  • "Radio climate": "Maritime Temperate (Land)",
  • "Atmospheric bending constant": 301,
  • "Fraction of situations": 90,
  • "Fraction of time": 90,
  • "Receiver": {
    },
  • "Transmitters": {
    },
  • "calculation_adjusted": [ ],
  • "elapsed": 135,
}

Multiple links to a single point (many Tx, one Rx)

This endpoint allows users to test many point-to-point links in one call. The points function tests an array of transmitters to one receiver and is designed for route analysis, mesh networks and dynamic modelling. The simplest request requires: transmitter’s array of tuples (latitude, longitude, altitude) locations, antenna, receiver, and output objects defined. Model and environment options enhance accuracy.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
site
string [ 2 .. 50 ] characters
Default: "Points"

Name of site.

network
string [ 2 .. 50 ] characters
Default: "Testing"

Network name/group.

object (Transmitter)
Array of objects (Point)
object (Antenna)
object (Receiver)
object (Model)
object (Environment)
object (Output)

Responses

Request samples

Content type
application/json
{
  • "site": "Points",
  • "network": "Testing",
  • "transmitter": {
    },
  • "points": [
    ],
  • "antenna": {
    },
  • "receiver": {
    },
  • "model": {
    },
  • "environment": {
    },
  • "output": {
    }
}

Response samples

Content type
application/json
{
  • "Engine": "Sleipnir 1.18",
  • "Frequency MHz": 868,
  • "Propagation model": "ITM",
  • "Earth dielectric constant": 14,
  • "Earth conductivity": 0.01,
  • "Radio climate": "Maritime Temperate (Land)",
  • "Atmospheric bending constant": 301,
  • "Fraction of situations": 90,
  • "Fraction of time": 90,
  • "Receiver": {
    },
  • "Transmitters": {
    },
  • "calculation_adjusted": [ ],
  • "elapsed": 135,
}

Multiple multipoint coverage heatmaps

This powerful GPU endpoint allows you request multiple area calculations in one request and response. The layers are returned as a composite super layer. This is useful for planning adhoc radio networks with many radios efficiently.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
site
string

Site name.

network
string

Network name/group.

Array of objects

Array of transmitters part of the multisite

object

Details relating to the receiver in the request.

object (Model)
object (Environment)
object (OutputWithBounds)

Responses

Request samples

Content type
application/json
{
  • "site": "My multisite",
  • "network": "My multisite network",
  • "transmitters": [
    ],
  • "receiver": {
    },
  • "model": {
    },
  • "environment": {
    },
  • "output": {
    }
}

Response samples

Content type
application/json
{}

Point-to-multipoint HF heatmap

This endpoint returns an omni-directional coverage plot (point-to-multipoint) for HF skywave propagation as an image.

Authorizations:
ApiKeyAuth
Request Body schema: application/json

The request payload providing the site properties.

site
required
string [ 1 .. 24 ] characters
Default: "HF1"

Site name.

network
required
string [ 1 .. 24 ] characters
Default: "Testing"

Network name/group.

required
object (HfTransmitter)
object (HfAreaReceiver)
object (HfAntenna)
object (HfAreaModel)
required
object (HfAreaOutput)

Responses

Request samples

Content type
application/json
{
  • "site": "Test",
  • "network": "HFTest",
  • "transmitter": {
    },
  • "antenna": {
    },
  • "model": {
    },
  • "output": {
    }
}

Response samples

Content type
application/json

Point-to-point HF frequency analysis (Tx to Rx)

This endpoint allows users to analyse a point-to-point path to find the best frequency. The result is a graph showing the SNR for a range of nominal HF frequencies plotted against time. This can be used to determine the MUF and LUF.

Authorizations:
ApiKeyAuth
Request Body schema: application/json

The request payload providing the site properties.

site
required
string [ 1 .. 24 ] characters
Default: "HF1"

Site name.

network
required
string [ 1 .. 24 ] characters
Default: "Testing"

Network name/group.

required
object (HfTransmitter)
object (HfPredictionReceiver)
object (HfAntenna)
object (HfPredictionModel)
required
object (HfPredictionOutput)

Responses

Request samples

Content type
application/json
{
  • "site": "Test",
  • "network": "HFTest",
  • "transmitter": {
    },
  • "receiver": {
    },
  • "antenna": {
    },
  • "model": {
    },
  • "output": {
    }
}

Response samples

Content type
application/json
{}

Analyse

This set of endpoints allows the user to use and analyse information from pre-defined networks and layers.

Find the best site within an area

The best site analysis (BSA) endpoint can be used to find the best locations in a wider area for a transmitter. It uses a GPU accelerated Monte Carlo simulation with hundreds of random locations to compare and grade radio intervisibility. Please note that the response of a BSA calculation is not signal strength. It is a normalised heatmap, relative to the best site, with settings for a user defined transmitter. For best results, focus onto a single feature, like a valley or a ridge, not an entire mountain range.

There are two methods to define an area of interest for a BSA caluclation:

  1. Specify the transmitter.lat and transmitter.lon, along with the output.rad to define the circular area of interest.
  2. Pass in an array of edges, each with a lat and lon which defines the area of interest. When using this method, you should ensure that the transmitter.lat and transmitter.lon are not set.

The response for BSA is a greyscale image.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
site
string [ 1 .. 24 ] characters
Default: "BSA"

Name of site.

network
string [ 1 .. 24 ] characters
Default: "BSA"

Network name/group.

object (Transmitter)
object

An array of edges which can be used to define a bounding box for your area of interest for BSA. When using this please remove your transmitter.lat and transmitter.lon values.

object (Antenna)
object
object

Responses

Request samples

Content type
application/json
{
  • "site": "BSA",
  • "network": "BSA",
  • "transmitter": {
    },
  • "edges": [
    ],
  • "antenna": {
    },
  • "receiver": {
    },
  • "output": {
    }
}

Response samples

Content type
application/json
{}

Merge sites into a super layer

This endpoint returns a consolidated layer of many area calculations as a single super layer. Stronger signals are promoted over weaker ones regardless of colour schema but units must match eg. dBm. Merging a dozen sites should take only a few seconds. Merging a large network or at very high resolution can take minutes. If you experience a timeout on a long running API request it can still succeed later if you check back in your archive.

Authorizations:
ApiKeyAuth
query Parameters
network
required
string
Example: network=100_repeaters_nationwide.

Network name.

name
required
string
Example: name=National_map

Super layer name.

Responses

Find interference for two networks

This endpoint compares a set pre-calculated 'signal' sites with a set of pre-calculated 'noise' sites to calculate the Jamming-to-Signal ratio, considering frequency, power and bandwidth. Signal sites can be specified with either a network name s_network or an array of site names s_sites, jammers are specified similarly with j_network and j_sites.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
s_network
string

Name of the 'signal' network.

s_sites
Array of strings

A list of 'signal' sites.

j_network
string

Name of the 'noise' network.

j_sites
Array of strings

A list of "noise" sites which are potentially interfering.

name
string

Interference layer name.

colour_key
string

Colour key name.

Responses

Request samples

Content type
application/json
{
  • "s_network": "MyNetwork",
  • "s_sites": [
    ],
  • "j_network": "OtherNetwork",
  • "j_sites": [
    ],
  • "name": "InterferenceExample",
  • "colour_key": "JS.dB"
}

Response samples

Content type
application/json
{}

Find the best server for a receiver

This endpoint allows users to query the network to find the best server(s) for a given receiver/customer location. A previously generated network is required. This method returns more data than the points API as it includes the arrays for terrain, landcover, obstructions, and path loss for each server.

Authorizations:
ApiKeyAuth
query Parameters
net
required
string

Network name.

nam
required
string

Super layer name.

lat
required
number <float>

Latitude in decimal degrees.

lon
required
number <float>

Longitude in decimal degrees.

alt
required
number <float>

Height above ground level in meters.

rxg
number <float>

Receiver gain in dBi.

Responses

Geo-locate a signal using received power measurements

This endpoint allows users to query sites to find areas of mutual interest where a signal might be. It uses receiver power measurements (including nil returns) and modelling to produce a much more accurate output than legacy trilateration using circles. The accuracy is determined by both the modelling and the errordB value which lets users specify trilateration error. About 10dB is recommended.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
colourKey
string

Colour key name. Recommended value is 9 (Greyscale)

errordB
number <float>

Trilateration error in decibels. This should be set with care as too low will produce no matches and too high will show signals everywhere. Recommend 10dB.

Array of objects

Array of sites and rssi values from where a signal has been detected

Array of objects

Array of sites from where a signal has NOT been detected

Responses

Request samples

Content type
application/json
{
  • "colourKey": 9,
  • "errordB": 10,
  • "connected": [
    ],
  • "disconnected": [
    ]
}

Response samples

Content type
application/json
{}

3D

This set of endpoints allows the user to interact with the 3D processing engine.

Calculate 3D coverage for a model

This endpoint allows you to model 3D propagation inside a user-supplied building or tunnel. It can handle reflections, material attenuation, fast-fading (dead-spots), 3D antenna patterns and multisite requests for many transmitters. This uses GPU acceleration and is resource intensive.

One of "res" and "megavoxels" is required, and calculation speed can be increased significantly by reducing "megavoxels" or increasing "res".

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array of objects

Array of transmitters part of the 3D multisite request

object (3d)
object

Details relating to the output file.

object

Details relating to the receiver in the request.

object
Array of objects

An array of custom materials as used within the input. Optional.

Responses

Request samples

Content type
application/json
{
  • "transmitters": [
    ],
  • "3d": {
    },
  • "output": {
    },
  • "receiver": {
    },
  • "default_material": {
    },
  • "materials": [
    ]
}

Response samples

Content type
application/json
{}

Upload a GLB model to use with a 3D calculation request.

Upload a GLB model which can be used in combination with the /3d request.

Please note that only a single model can be uploaded with each request.

The example below gives a named value of file, but this can be anything. The API doesn't look for a particular name, rather it takes the first file which was sent.

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
file
required
string <binary>

The file to upload.

Responses

Response samples

Content type
application/json
{}

Manage

This set of endpoints allow the user to administer data, including enumeration, deletion, and exporting of data in open formats.

List calculations from archive

This endpoint allows users to list 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.

Authorizations:
ApiKeyAuth
query Parameters
n
number <float>
Example: n=65

North bounding box. WGS84 decimal degrees.

e
number <float>
Example: e=2

East bounding box. WGS84 decimal degrees.

s
number <float>
Example: s=50

South bounding box. WGS84 decimal degrees.

w
number <float>
Example: w=-5

West bounding box. WGS84 decimal degrees.

Responses

Delete calculation from database

Warning! You could lose data. This endpoint deletes the entry from the database and the file from the disk. This deletes a single calculation from the database and from your folder.

Authorizations:
ApiKeyAuth
query Parameters
cid
required
integer

Unique calculation ID number.

Responses

Delete entire network

Warning! You could lose lots of data. This endpoint deletes all associated child entries from the database and the files from the disk.

Authorizations:
ApiKeyAuth
query Parameters
nid
required
string

Network name.

Responses

Export calculation in GIS file format

This endpoint downloads your data in a format suitable for a third-party viewer such as Google Earth or ESRI Arcmap. Supported formats:

  • KML
  • KMZ
  • GeoTIFF
  • SHP
  • URL
  • HTML
Authorizations:
ApiKeyAuth
query Parameters
file
required
string

Calculation file name.

fmt
required
string
Enum: "kml" "kmzppa" "shp" "tiff" "zip"

Required file format: KML; KMZ; SHP; GeoTIFF or ATAK ZIP

Responses

Upload clutter data as GeoJSON

This endpoint supports upload of GeoJSON lineString and polygon features to your account.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
name
string
Default: "Clutter"
type
string
Default: "FeatureCollection"
Array of objects (Feature)

Responses

Request samples

Content type
application/json
{
  • "name": "Clutter",
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Response samples

Content type
application/json
{
  • "info": "Added 1 item(s) of clutter. Rejected 0 item(s) of clutter. Total 1 items(s) of clutter exist on your profile."
}

Get private clutter data for a location.

This endpoint fetches private clutter items for the given co-ordinates out to 1 decimal degree radius (approximately 120 km at the equator). Results are limited to 100 items sorted by nearest first. GeoJSON coordinates are passed as a clean URL, for example, https://api.cloudrf.com/clutter/get/51.637723/-2.649606

Authorizations:
ApiKeyAuth
path Parameters
latitude
required
number <float>
Example: 51.637723

GeoJSON coordinate latitude in decimal degrees.

longitude
required
number <float>
Example: -2.649606

GeoJSON coordinate longitude in decimal degrees.

Responses

Response samples

Content type
application/json
{
  • "features": {
    },
  • "id": {
    }
}

Delete clutter item by its ID

Delete a private clutter item referenced by its id passed as a clean URL. For example, /clutter/delete/123 The id is returned by the get clutter endpoint (/clutter/get) Please note that if you pass in an id value of 0 then all clutter for your profile will be deleted.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Clutter id number.

Responses

Response samples

Content type
application/json
{
  • "info": "Deleted a total of 1 clutter entries. ID #2858 deleted."
}

Delete all clutter on your profile

Similar to /clutter/delete/{id}, however if you pass an id value of 0 then you will delete all clutter on your profile.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "info": "Deleted a total of 4 clutter entries."
}

Submit noise data for an array of locations which is referenced by other APIs for accurate, time sensitive simulations.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array
frequency
number <integer>

Center frequency in megahertz for the noise data.

noise
number <integer> [ -144 .. -20 ]

Noise data value in dBm.

latitude
number <float>

Latitude of noise value in WGS84 decimal degrees.

longitude
number <float>

Longitude of noise value in WGS84 decimal degrees.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "message": "Noise data successfully stored."
}

Get the average noise recorded for locations radii over the last 24 hours. Other APIs will do this automatically when the nf field is set to 'database'

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array
frequency
number <integer>

Center frequency in megahertz for the noise data to retrieve.

bandwidth
number

Bandwidth in MHz.

latitude
number <float>

Latitude of noise value in WGS84 decimal degrees.

longitude
number <float>

Longitude of noise value in WGS84 decimal degrees.

radius
number <integer> [ 1 .. 200 ]

Radius from the latitude/longitude location to include noise data.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • [
    ]
]

Get a map of database noise.

Returns an 8-bit greyscale geotiff where the value of each pixel is abs(noise floor) in dBm. Used for the user interface so users can see the noise.

Authorizations:
ApiKeyAuth
query Parameters
frequency
number
Example: frequency=446

Center frequency in megahertz for the noise data to retrieve.

north
number
Example: north=38.92

North bound of the noise map.

south
number
Example: south=38.9

South bound of the noise map.

east
number
Example: east=1.45

East bound of the noise map.

west
number
Example: west=1.43

West bound of the noise map.

resolution
number
Example: resolution=20

The resolution of the noise map in meters.

point_limit
integer
Example: point_limit=20

The maximum number of noise data points to use in calculating noise map.

Responses

Delete noise data.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Successfully deleted 10 piece(s) of noise data."
}

Account

This set of endpoints allow the user to manage their account.

Get metrics for API usage

Get a detailed breakdown of metrics and statistics for your account API usage over your purchase period. This includes a breakdown of total API requests and their types, along with the different types of requests which were made on each day.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "from": "2022-07-10 13:06:36.851",
  • "count_total": 2279,
  • "time_series": [
    ],
  • "types_total": {
    },
  • "remaining_calculations_since_last_purchase": 2983
}

Template

This set of endpoints allow the user to manage reusable radio templates with pre-defined values.

Get custom templates for your account

Get an array of all custom templates which have been created by your user account.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get system templates which available

Get an array of all system templates which are available on the system.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • "TW-900",
  • "TW-950",
  • "MPU5"
]

Get templates favourited by your account.

Get an array of system templates which have been favourited by your user account.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get a template's details

Get the content of a template. This is requested in one of 2 ways:

  • Specifying the id of the custom template which you have previously created.
  • Specifying the name of the system template which is available. Please note that some system templates may not have the same number of response values as a custom template.
Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The id of a custom template which has been created, or the name of a system template which is available.

Responses

Response samples

Content type
application/json
{
  • "version": "CloudRF-API-v3.4.0",
  • "template": {
    },
  • "site": "Site",
  • "network": "Network",
  • "engine": 2,
  • "coordinates": 1,
  • "transmitter": {
    },
  • "receiver": {
    },
  • "feeder": {
    },
  • "antenna": {
    },
  • "model": {
    },
  • "environment": {
    },
  • "output": {
    }
}

Download a template as a file

Download the content of a template. Please note that this request returns exactly the same JSON as /template/{id|name} The id|name is requested in one of 2 ways:

  • Specifying the id of the custom template which you have previously created.
  • Specifying the name of the system template which is available. Please note that some system templates may not have the same number of response values as a custom template.
Authorizations:
ApiKeyAuth
path Parameters
id|name
required
integer

The id of a custom template which has been created, or the name of a system template which is available.

Responses

Delete a custom template

Delete a custom template which has been created by your user account.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The id of a custom template which should be deleted.

Responses

Response samples

Content type
application/json
{
  • "message": "Successfully deleted template with ID 59324."
}

Favourite a system template

Favourite a system template.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

The name of the system template which you would like to favourite.

Responses

Response samples

Content type
application/json
{
  • "message": "Successfully favourited template 'MPU5'."
}

Unfavourite a system template

Unfavourite a system template.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

The name of the system template which you would like to unfavourite.

Responses

Response samples

Content type
application/json
{
  • "message": "Successfully unfavourited template 'MPU5'."
}

Store a new custom template

Store a new custom template. This endpoint accepts either a JSON data payload, or it can be requested by sending multipart form data of a JSON file with the same contents as the JSON data payload.

Authorizations:
ApiKeyAuth
Request Body schema: application/json

This endpoint accepts either a JSON data payload, or it can be requested by sending multipart form data of a JSON file with the same contents as the JSON data payload.

site
string

Site name

network
string

Network name

engine
number <integer>

The processing engine associated with the template.

  • 1 - GPU
  • 2 - CPU
coordinates
number <integer>

The coordinates system associated with the template.

  • 1 - Decimal Degrees
  • 2 - Degrees Minutes Seconds
  • 3 - MGRS / UTM
object
object (Receiver)
object
object
object
object (Environment)
object

Responses

Request samples

Content type
application/json
{
  • "site": "Site",
  • "network": "Network",
  • "engine": 2,
  • "coordinates": 1,
  • "transmitter": {
    },
  • "receiver": {
    },
  • "feeder": {
    },
  • "antenna": {
    },
  • "model": {
    },
  • "environment": {
    },
  • "output": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Successfully stored template."
}

Satellite

Query the satellite database

This endpoint returns a paginated list of TLE results (Over 6000 active satellites) from the database. The data is updated regularly from a third party source.

Authorizations:
ApiKeyAuth
query Parameters
name
string
Example: name=skynet

Satellite name. Not case sensitive and can be partial eg skynet*

norad_cat_id
integer
Example: norad_cat_id=20776

NORAD catalogue number

Responses

Model coverage for a satellite to an area

This GPU accelerated endpoint allows you to test coverage from a satellite, by name, to a defined box on the earth.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
satellites
Array of strings

Array of satellites to test, listed by name

date_time
string

ISO-8601 timestamp for querying TLE data.

object

Details relating to the receiver in the request.

object (Environment)
object

Details relating to the output

Responses

Request samples

Content type
application/json
{
  • "satellites": [
    ],
  • "date_time": "2024-07-23T04:54:28Z",
  • "receiver": {
    },
  • "environment": {
    },
  • "output": {
    }
}

Response samples

Content type
application/json
{}