RF Simulation / Reward Estimation API Documentation

Introduction

So you've decided to start programmatically assessing potential hotspot locations? Well, you've come to the right place. A few things to note before we get started.

• You will need to be a subscriber to receive API access: https://hotspotrf.com/pricing/
• You will need an API key to perform simulations. To access your API key please follow this link while you are logged into our website: https://api.hotspotrf.com/v2/api/user
• Each successful API request will deduct 1 credit from your account balance.

Helium IoT Radio Frequency Simulations / Reward Estimation

Endpoint

https://etl.api.hotspotrf.com/simulate/run

Method

POST

Input

The API requires a raw body in JSON format with the following parameters:

If you are not sure what to put for a setting please consult our settings guide, if you are still unsure please feel free to contact us!

Output

The API returns a JSON object with the following parameters:

Example Simulate API Request In Python 3

import requests

url = "https://etl.api.hotspotrf.com/simulate/run"

# Settings used for IoT RF simulation / rewards estimation API call.
payload = {
    "lat": "37.7813",
    "lng": "-122.1594",
    "txh": 40,
    "frq": 915,
    "env": "wooded",
    "ant": 2.3,
    "cbl": 0,
    "unit": "ft",
    "placement": "outdoor",
    "key": "YOUR API KEY", # Can be found here when logged in: https://api.hotspotrf.com/v2/api/user
    "user": "YOUR USER ID" # Can be found here when logged in: https://api.hotspotrf.com/v2/api/user
}

# Set our headers
headers = {
    'Content-Type': 'application/json'
}

# Make the API request with our headers and payload (settings).
response = requests.post(url, json=payload, headers=headers)

# Print the response.
if response.status_code == 200:
    print(response.json())
# Or error code if there is one.
else:
    print("Request failed with status code:", response.status_code)

Example response:

{'result_id': '63dae0668c6164b67052aff3', 'status': 'pending'}

Great, now we made our request, but where are the results? We can use the result_id we received to fetch the results. Note: You can look up a result ID as many times as you'd like for free, it does not cost any credits.

# Grab the result_id.
result_id = response.json()['result_id']
# Fetch the results.
results = requests.get('https://app.hotspotrf.com/api/lookup?id=' + str(result_id))

# Print the simulation results.
print(results.json())

Example results in JSON format.

{
   "message":{
      "_id":"63dae0668c6164b67052aff3", # the result id.
      "settings":{ # settings used.
         "frequency":915,
         "antenna_gain":2.3,
         "cable_loss":0,
         "height":40,
         "height_units":"ft",
         "placement":"outdoor",
         "environment":"wooded"
      },
      "results":{
         "hotspotrf_score":0.7, # the HotspotRF score 1 = average, 1.35 = 35% above average. This is an average of the PoC reward score and comps reward score.
         "poc_reward_score":0.8, # based on the hotspots your RF coverage can reach and their number of witnesses/transmit scales.
         "comps_reward_score":0.59, # based on how comparable hotspots in the area perform.
         "est_avg":-30.34, # how well we estimate the location will perform based in percentage terms
         "comps":[ # the comparable hotspots in the area.
            # redacted to save space.
         ],
         "transmit_scale":0.33, # estimated transmit scale of a hotspot placed at this location.
         "hotspots_reached_total":2382, # the total number of hotspots the simulated RF reaches. Note this is usually very over stated. RF modeling is not a perfect science and many setups are sub-optimal.
         "hotspots_reached_safe":2382, # hotspots that are far enough away that witnesses are valid.
         "hotspots_reached_dead":0, # hotspots that are too close and witnessing will be invalid.
         "rf_image":"https://app.cdn.hotspotrf.com/imgs/163f1498-0897-49a2-a350-a37907a68a09.png", # the RF "splat" image that is overlayed on the map.
         "rf_kmz":"https://app.cdn.hotspotrf.com/imgs/163f1498-0897-49a2-a350-a37907a68a09.kmz", # kmz file of the RF "splat" (can be opened in Google Earth or similar).
         "rf_image_lng_lat":{ # the corners of the RF image so it can be overlayed on map.
            "bottom_left":[
               -122.7094,
               37.3463
            ],
            "bottom_right":[
               -121.6094,
               37.3463
            ],
            "top_right":[
               -121.6094,
               38.2163
            ],
            "top_left":[
               -122.7094,
               38.2163
            ]
         },
         "exec_time":5.4,
         "hotspotrf_rewards":0.07603406326034062 # estimated HNT rewards/day based on HotspotRF_score and current avg rewards per day.
      },
      "location":{ # the lat/lng of the simulated point.
         "lng_lat":[
            -122.1594,
            37.7813
         ],
         "location":"13525 Campus Drive, Oakland, California 94605, United States" # address nearest the simulated point.
      },
      "date_time":"2023-02-01T21:57:58.327497", # date/time the simulate was completed.
      "status":"completed",
      "exec_times":{ # how long each part of the simulation took.
         # redacted to save space
      },
      "hnt_usd":2.78, # the current price of hnt in usd.
      "hnt_per_hotspot_per_day":0.10862009037191518 # the average hnt per hotspot per day.
   },
   "success":true
}

Thats it! You've now made your first API request. Please feel free to reach out with any questions or suggestions!

Full Python 3 code from request --> results.

Random thought: If Python is not your preferred language, you can try asking Chat GPT to re-write this code snippet in your preferred language.

import requests

url = "https://etl.api.hotspotrf.com/simulate/run"

# Settings used for IoT RF simulation / rewards estimation API call.
payload = {
    "lat": "37.7813",
    "lng": "-122.1594",
    "txh": 40,
    "frq": 915,
    "env": "wooded",
    "ant": 2.3,
    "cbl": 0,
    "unit": "ft",
    "placement": "outdoor",
    "key": "YOUR API KEY", # Can be found here when logged in: https://api.hotspotrf.com/v2/api/user
    "user": "YOUR USER ID" # Can be found here when logged in: https://api.hotspotrf.com/v2/api/user
}

# Set our headers
headers = {
    'Content-Type': 'application/json'
}

# Make the API request with our headers and payload (settings).
response = requests.post(url, json=payload, headers=headers)

# Print the response.
if response.status_code == 200:
    print(response.json())
# Or error code if there is one.
else:
    print("Request failed with status code:", response.status_code)

# Now its time to fetch the results with the result_id we received from our API call.
# Grab the result_id.
result_id = response.json()['result_id']
# Fetch the results.
results = requests.get('https://app.hotspotrf.com/api/lookup?id=' + str(result_id))

# Print the simulation results.
print(results.json())