API Overview

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

Full OpenAPI 3 Schema

For a complete OpenAPI 3 schema of the Cloud-RF API please consult the Swagger UI documentation.

API Endpoint

For most users the endpoint for the API is https://api.cloudrf.com.

Users with a private server will have an IP address instead and API functions will be relative to this address.

Security

All requests are encrypted at the transport layer with TLS.

Authentication

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

An example of such API key is as below:

101-ec94622a4cb939a77101a118c6871d03cea88af3

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 some best practices:

Keys as Environment Variables

Store API keys as environment variables. This has an added benefit of accessing your key via a friendly environment variable name rather than having to remember your full key each time.

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

You can store your API key in a file and make reference to that file each time you need to use your API key.

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

Doing so helps to ensure that your keys do not end up in your source code version 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 requires API key authentication 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.

Example API Requests

Below lists some basic examples of some of the most common types of requests made to the Cloud-RF API.

For a complete list of available schemas please consult the Swagger UI documentation.

With all requests some values are required and so the response will return any validation errors or any failures should your request not be able to be processed.

Area

The area endpoint accepts a JSON object describing your network and will run a point-to-multipoint area calculation.

The following example excludes some optional parameters and provides the required data to model a transmitter with many receivers at a height of 2 meters.

The below example is sent as a POST request to https://api.cloudrf.com/area.

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

Path

The path endpoint accepts a JSON object describing your network and will run a point-to-point calculation.

The following example excludes some optional parameters 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 latitude (lat) and longitude (lon) values.

The below example is sent as a POST request to https://api.cloudrf.com/path.

{
    "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 points endpoint accepts a JSON object describing your network.

The following example excludes some optional parameters 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.

The below example is sent as a POST request to https://api.cloudrf.com/points.

{
    "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 at https://docs.cloudrf.com.

For a complete OpenAPI 3 schema of the Cloud-RF API please consult the Swagger UI documentation.

Example Scripts

A list of ready-to-use scripts are available on the Cloud-RF public GitHub repository.

Example cURL Request and Response

The below shows an example cURL request to the points endpoint.

Please 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
        }
    }'

The API output is JSON which can be easily parsed by any language. Using the previous request to points we get the following response.

{
    "Engine": "Sleipnir 1.6.1",
    "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": 0,
            "Antenna height m": 0.1,
            "Receiver gain dBd": 0,
            "Receiver gain dBi": 2.15
        }
    ],
    "Transmitters": [
        {
            "Latitude": 38.916,
            "Longitude": 1.411,
            "Ground elevation m": 58,
            "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,
            "Johnson Nyquist noise dB": 0.2,
            "Noise floor dBm": -114,
            "Channel noise dBm": -113.8,
            "Signal power at receiver dBm": -294.1,
            "Signal to Noise Ratio dB": -180.3,
            "Computed path loss dB": 314.1,
            "Model attenuation dB": 217.1,
            "Field strength at receiver dBuV/m": -152.6,
            "Raise RX antenna for LOS": 18.1,
            "Raise RX antenna for fresnel 60%": 159.1,
            "Raise RX antenna for full fresnel": 321.1,
            "server": 1
        },
        {
            "Latitude": 38.916,
            "Longitude": 1.411,
            "Ground elevation m": 58,
            "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,
            "Johnson Nyquist noise dB": 0.2,
            "Noise floor dBm": -114,
            "Channel noise dBm": -113.8,
            "Signal power at receiver dBm": -294.1,
            "Signal to Noise Ratio dB": -180.3,
            "Computed path loss dB": 314.1,
            "Model attenuation dB": 217.1,
            "Field strength at receiver dBuV/m": -156,
            "Raise RX antenna for LOS": 18.1,
            "Raise RX antenna for fresnel 60%": 159.1,
            "Raise RX antenna for full fresnel": 321.1,
            "server": 2
        }
    ],
    "calculation_adjusted": [],
    "elapsed": 45.0,
    "kmz": "https://api.cloudrf.com/API/archive/data?points=0810163833_Testing_POINTS&uid=101",
    "json": "https://api.cloudrf.com/users/101/0810163833_Testing_POINTS.json"
}