API Overview

The Cloud-RF API offers a powerful and versatile system to model any radio, anywhere.

API functions are grouped into CREATE, ANALYSE and MANAGE categories.

Authentication

Each user has a unique private API key which resembles a long random string of characters.

API Key Security

It is important to keep your API key secure. Publicly exposing your key can compromise your account, which could result in a loss of data or unexpected charges. To keep your API keys secure, follow these best practices:

Keys as Environment Variables

Store API keys as environment variables.

Do not embed API keys directly in code. API keys that are embedded in code can be accidentally exposed outside your circle of trust.

Keys as Files

If you store API keys in files, store those files outside your application’s source tree.

This helps to ensure that your keys do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub.

Using the API key

The CloudRF API 2.0 requires API key auth in the request header. This provides a key-value pair with “key” as the first value and your personal key as the second, paired value.

For example, Postman allows you to enter your key from their interface:

CREATE functions

CREATE is comprised of 3 endpoints that accept data via a POST command:

  • Area

  • Post

  • Path

Note Remember to include your unique identifier, the API key in your header.

Area

The area endpoint accepts a JSON object describing your network. Some objects/data are required, i.e., they must be provided for your network to be registered:

  • Transmitter

  • Receiver

  • Antenna

  • Output

The following example excludes the optional objects, model and environment and provides the required data to model a transmitter with many receivers at 2m height:

{
    "site": "A1",
    "network": "Testing",
    "transmitter": {
        "lat": 38.916,
        "lon": 1.448,
        "alt": 2,
        "frq": 868,
        "txw": 0.1,
        "bwi": 1
    },
    "receiver": {
        "lat": 0,
        "lon": 0,
        "alt": 2,
        "rxg": 3,
        "rxs": -100
    },
    "antenna": {
        "txg": 2.15,
        "txl": 1,
        "ant": 0,
        "azi": 1,
        "tlt": 10,
        "hbw": 2,
        "vbw": 2,
        "pol": "h"
    },
    "output": {
        "units": "metric",
        "col": "RAINBOW.dBm",
        "out": 2,
        "ber": 2,
        "mod": 7,
        "nf": -80,
        "res": 10,
        "rad": 5
    }
}

Make the API Call

Send the JSON as a HTTP POST to https://api.cloudrf.com/area

Path

The following example excludes the optional objects, model and environment and provides the required data to model a link with 1 receiver. Notice it looks very similar to the area call except for the receiver object’s latitude and longitude.

{
    "site": "A1",
    "network": "Testing",
    "transmitter": {
        "lat": 38.916,
        "lon": 1.448,
        "alt": 2,
        "frq": 868,
        "txw": 0.1,
        "bwi": 1
    },
    "receiver": {
        "lat": 38.91612,
        "lon": 1.49999,
        "alt": 2,
        "rxg": 3,
        "rxs": -100
    },
    "antenna": {
        "txg": 2.15,
        "txl": 1,
        "ant": 0,
        "azi": 1,
        "tlt": 10,
        "hbw": 2,
        "vbw": 2,
        "pol": "h"
    },
    "output": {
        "units": "metric",
        "col": "RAINBOW.dBm",
        "out": 2,
        "ber": 2,
        "mod": 7,
        "nf": -80,
        "res": 10,
        "rad": 5
    }
}

Points

The following example excludes the optional objects, model and environment and provides the required data to model an array of transmitters back to one receiver. With this structure you can test a polyline, route or lots of sensors talking to a single base station. The transmitter block contains a location but this is ignored when a points array is supplied.

{
    "site": "A1",
    "network": "Testing",
    "transmitter": {
        "lat": 38.916,
        "lon": 1.448,
        "alt": 2,
        "frq": 868,
        "txw": 0.1,
        "bwi": 1
    },
    "points": [
        {
            "lat": 38.916,
            "lon": 1.411,
            "alt": 1
        },
        {
            "lat": 38.916,
            "lon": 1.411,
            "alt": 1
        }
    ],
    "receiver": {
        "lat": 38.916,
        "lon": 1.448,
        "alt": 0.1,
        "rxg": 2.15,
        "rxs": -90
    },
    "antenna": {
        "txg": 2.15,
        "txl": 1,
        "ant": 0,
        "azi": 1,
        "tlt": 10,
        "hbw": 2,
        "vbw": 2,
        "pol": "h"
    },
    "output": {
        "units": "metric",
        "col": "RAINBOW.dBm",
        "out": 2,
        "ber": 2,
        "mod": 7,
        "nf": -80,
        "res": 10,
        "rad": 5
    }
}

More information

See more example requests and responses on the official API documentation on the Postman network here: https://docs.cloudrf.com

Swagger specification / OpenAPI3

The full OpenAPI 3 specification for the API is here

Examples

cURL

Note the API key sits within the header, not the data.

curl --location --request POST 'https://api.cloudrf.com/points' \
--header 'key: 101-IBIZA.DEMO.KEY' \
--data-raw '{
    "site": "Points",
    "network": "Testing",
    "transmitter": {
        "lat": 38.916,
        "lon": 1.448,
        "alt": 1,
        "frq": 868,
        "txw": 0.1,
        "bwi": 0.1
    },
    "points": [
        {
            "lat": 38.916,
            "lon": 1.411,
            "alt": 1
        },
        {
            "lat": 38.916,
            "lon": 1.411,
            "alt": 1
        }
    ],
    "antenna": {
        "txg": 2.15,
        "txl": 0,
        "ant": 1,
        "azi": 0,
        "tlt": 0,
        "hbw": 0,
        "vbw": 0,
        "pol": "v"
    },
    "receiver": {
        "lat": 38.916,
        "lon": 1.448,
        "alt": 0.1,
        "rxg": 2.15,
        "rxs": -90
    },
    "model": {
        "pm": 1,
        "pe": 2,
        "cli": 6,
        "ked": 0,
        "rel": 95,
        "ter": 4
    },
    "environment": {
        "clm": 1,
        "cll": 2,
        "mat": 0.25
    },
    "output": {
        "units": "metric",
        "col": "RAINBOW.dBm",
        "out": 2,
        "ber": 0,
        "mod": 0,
        "nf": -114,
        "res": 10,
        "rad": 5
    }
}'

Output

The API output is JSON which can be easily parsed by any language.

{
	"Engine": "Sleipnir 1.4.3",
	"kmz": "https://api.cloudrf.com/API/archive/data?points=0827174656_Testing_POINTS&uid=101",
	"elapsed": 99,
	"Frequency MHz": 868,
	"Propagation model": "ITM",
	"Earth dielectric constant": 13, "Earth conductivity": 0.002,
	"Radio climate": "Maritime Temperate (Land)", "Atmospheric bending constant": 301,
	"Fraction of situations": 95, "Fraction of time": 95,
	"Receiver": [{
		"Latitude": 38.916, "Longitude": 1.448,
		"Ground elevation m": 1, "Antenna height m": 0.1,
		"Receiver gain dBd": 0, "Receiver gain dBi": 2.15
	}],
	"Transmitters": [
		{
            "Latitude": 38.916, "Longitude": 1.411,
            "Ground elevation m": 59, "Antenna height m": 1,
            "Distance to receiver km": 3.205,
            "Azimuth to receiver deg": 89.99,
            "Downtilt angle deg": 1.1,
            "Antenna gain dBd": 0, "Antenna gain dBi": 2.15,
            "Polarisation": "Vertical",
            "Power W": "0.1",
            "Power dBm": "25.47",
            "ERP W": 0.22, "EIRP W": 0.16,
            "ERP dBm": 23.32, "EIRP dBm": 25.47,
            "Free space path loss dB": 97,
            "Bandwidth MHz": 0.1,
            "Signal power at receiver dBm": -147.8,
            "server": 1
		},
		{
            "Latitude": 38.916, "Longitude": 1.411,
            "Ground elevation m": 59, "Antenna height m": 1,
            "Distance to receiver km": 3.205,
            "Azimuth to receiver deg": 89.99,
            "Downtilt angle deg": 1.1,
            "Antenna gain dBd": 0, "Antenna gain dBi": 2.15,
            "Polarisation": "Vertical",
            "Power W": "0.1",
            "Power dBm": "22.15",
            "ERP W": 0.1, "EIRP W": 0.16,
            "ERP dBm": 20, "EIRP dBm": 22.15,
            "Free space path loss dB": 97,
            "Bandwidth MHz": 0.1,
            "Signal power at receiver dBm": -147.8,
            "server": 2
		}
	]
}