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:
Parameter | Type | Required | Description |
---|---|---|---|
lat | float | Yes | Latitude of the location. |
lng | float | Yes | Longitude of the location. |
txh | integer | Yes | Transmitter height in the specified unit. |
frq | integer | Yes | Frequency in MHz. |
env | string | Yes | Environment type, either 'clear', 'wooded', 'suburbs', 'mixed', or 'urban'. |
ant | integer | Yes | Antenna gain in dB. |
cbl | integer | Yes | Cable loss in dB. |
unit | string | Yes | Unit of measurement for height, either 'ft' or 'm'. |
placement | string | Yes | Placement type, either 'outdoor' or 'indoor'. |
key | string | Yes | API key for authentication. |
user | string | Yes | User ID for authentication. |
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:
Parameter | Type | Description |
---|---|---|
result_id | string | ID of the result that can be used to look up the results. |
status | string | Current status of the job, usually 'pending' until it completes in 5-20 seconds. |
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())
Comments
0 comments
Please sign in to leave a comment.