ElectroSense Data API

Base URL: /api, Version: 1.0 (released 2016-12-12)

This Web API allows for retrieval of raw and aggregated spectrum data.

Schemes: https

Summary

Path Operation Description
/sensor/list GET

Get a list of all sensors

/sensor/details/{serial} GET

Get information about a single sensor

/spectrum/aggregated GET

Retrieve (aggregated) spectrum measurements of a particular sensor

/spectrum/fft GET

Retrieve FFT measurements as received by the sensor

Security

basicAuth

Type: basic

Access via basic auth is simple. Just include username and password in the request URI like this: https://username:password@electrosense.org/api/...

Paths

Get a list of all sensors

GET /sensor/list

Sensor information for others' sensors does not contain exact location information to preserve privacy.

200 OK

Details for all sensors

400 Bad Request

Bad Request (wrong or missing parameters)

basicAuth
Get information about a single sensor

GET /sensor/details/{serial}

By default, information is returned for the current state of the sensor. As this information is subject to change, e.g., when the location changes, the meta information for a device can be retrieved for an arbitrary point in time.

serial

sensor serial number

path integer (int64)
time

Time to retrieve meta information in seconds since epoch (Unix time), default is the time of the method call.

query integer (int32)
200 OK

Details for the requested sensor

400 Bad Request

Bad Request (wrong or missing parameters)

404 Not Found

No sensor with the given name

basicAuth
Retrieve (aggregated) spectrum measurements of a particular sensor

GET /spectrum/aggregated

Data can be retrieved for a single sensor within a time window [timeBegin, timeEnd] and for frequency range [freqMin, freqMax]. Aggregation takes place in time and frequency domain with the given resolutions aggTime and aggFreq. Samples having time tSample and frequency fSample are put into bins with

  • time tBin = tSample - tSample mod aggTime
  • frequency fBin = fSample - fSample mod aggFreq

Each bin contains a single value which results from the application of an aggregation function over all squared magnitudes of the bin's samples. It can be chosen between the maximum and the average.

Limitations

  • No restrictions for own device
  • Highest resolution for all other devices: 60s, 100kHz. This means that the lowest values for aggTime and aggFreq are 60 and 100000 if you want to retrieve data other than from your own device.
  • The query must not ask for more than an expected number of 2 million result values. The expected number of values depends on all parameters and can be computed using the following formula: |V| = ((freqMax - freqMin) / aggFreq) * ((timeEnd - timeBegin) / aggTime)
sensor

sensor serial number

query number
timeBegin

start time in seconds since epoch (Unix time)

query number
timeEnd

end time in seconds since epoch (Unix time)

query number
freqMin

lower bound for frequency in Hz

query number
freqMax

upper bound for frequency in Hz

query number
aggFreq

frequency resolution

query number
aggTime

time resolution

query number
aggFun

aggregation function, either "MAX" or "AVG", default is "AVG"

query string

application/json

200 OK

Aggregated spectrum data

400 Bad Request

Bad Request (wrong or missing parameters)

Retrieve FFT measurements as received by the sensor

GET /spectrum/fft

Access FFT measurements as we receive them by the sensor.

Limitations

  • No restrictions for own device
  • No access for all other devices
  • The query must not ask for more than 3 minutes of data, i.e., it must hold that timeEnd - timeBegin <= 180.
sensor

sensor serial number

query integer (int64)
timeBegin

start time in seconds since epoch (Unix time)

query number
timeEnd

end time in seconds since epoch (Unix time)

query number

application/json

200 OK

Raw FFT measurements for the requested time span

400 Bad Request

Bad Request (wrong or missing parameters)

basicAuth

Schema definitions

AggregatedData: object

startFreq: integer (int64)

Frequency of the first entry in 'values'

startTime: integer (int64)

Time of the first entry in 'values'

timeRes: integer (int64)

Time difference between two consecutive rows in 'values'. The i-th row in values has time startTime + i*(timeRes - 1)

freqRes: integer (int64)

Difference in frequency between two consecutive columns in 'values'. The j-th column in values has frequency startFreq + j*(freqRes - 1)

noiseFloor: number (float)

An estimation for the noise floor. See the external documentation.

values: number[][]

A two-dimensional Array (Matrix) of SNR values in dB. Each row contains (aggregated) measurements for the same time t, each column measurements for the same frequency f. An entry v[i][j] has time startTime + i(timeRes - 1) and frequency startFreq + j(freqRes - 1).

There might be no measurements available for certain frequencies and times. In this case the entry v[i][j] = 'null'.

The SNR is computed based on the estimated noise floor. If you need the squared magnitudes, add the value of the noiseFloor field.

number[]
number (float)

ErrorMessages: string[]

Contains a list of errors

string

RawFFTData: object

SenId: integer (int64)

sensor serial number (MAC address in decimal representation)

SenConf: object
HoppingStrategy: integer

Identifier of the hopping strategy used to overcome the bandwidth limitations of the RF front-end. [0:Sequential, 1:Random, 2:Similarity]

WindowingFunction: integer

Identifier of the windowing function used to reshape the time-domain samples. [0:Rectangular, 1:Hanning, 2:BlackmanHarris]

FFTSize: integer

Size of the fast Fourier transform (FFT), i.e. the number of samples in the frequency-domain representation of a signal. [2^i, where i in {8,...,17}]

AveragingFactor: integer

Number of frequency-domain signals to average. [>0]

FrequencyOverlap: number

Fraction of the frequency-domain signals to drop due to non-linear frequency responses of the RF front-end. The effective number of samples in frequency-domain signals is reduced from FFTSize to (1-FrequencyOverlap)(FFTSize+1). The bandwidth of the frequency-domain signals is reduced from FFTSizeFrequencyResolution to (1-FrequencyOverlap)FFTSizeFrequencyResolution. [0,...,1]

FrequencyResolution: number

Frequency difference in Hz between successive samples within the frequency-domain signals. [>0]

Gain: number

RF gain in dB. [-1 for automatic gain control]

SenPos: object
PosSys: string

Description/identification of the used positioning system.

PosVal: number[]

Position values in the corresponding positioning system.

number
SenTemp: number

Optional Filed - Ambient temperature of the sensor in degrees Celsius.

SenTime: object
TimeSecs: integer (int64)

Number of seconds since the UNIX epoch start on January 1st, 1970 at UTC.

TimeMicrosecs: integer (int32)

Microseconds extension for the UNIX time stamp.

SenData: object
CenterFreq: integer

Center frequency in Hz to which the RF front-end was tuned to while recording the associated spectrum data.

SquaredMag: number[]

Actual spectrum data recorded for the associated center frequency. The (1-FrequencyOverlap)*(FFTSize+1) data points represent the squared magnitudes of the frequency-domain signal on a dB scale.

number (float)

Sensor: object

type: string

Device type ('esraspi2psdr' or 'misc')

id: integer (int32)

Unique sensor id for internal use.

serial: integer (int64)

Sensor's serial number. This is used as an identifier for the API.

name: string

A unique name for the sensor (which user can choose)

uid: string

Username of device owner. Can be 'null' in case he wants for privacy reasons.

operator: string

Full name of device owner. Can be 'null' in case he wants for privacy reasons.

contact: string

Contact address of device owner. Can be 'null' in case he wants for privacy reasons.Legacy Note: This field will be removed in the future.

address: string

Address of the sensor's location. Only shown for own sensors, otherwise 'null'!

position: object

Geographical coordinates of the device.

longitude: number (double)
latitude: number (double)
altitude: number (double)
indoor: boolean
anonymized: boolean

If 'false' the user did not provide the exact position for privacy reasons.

deployed: string (date-time)

Date and time of this sensor's deployment in seconds since epoch (Unix time). The date will change under certain conditions, i.e.,

  • position is changed
  • radio frontend is changed
  • after a firmware upgrade which has large influence on measured values
firmware: string

Firmware version running if sensor is a device is running a firmware provided by ElectroSense.

frontend: string

Radio Frontend of the device. Can be null

antenna: object

Detailed information about the antenna used. Can be 'null' if information is missing.

directional: boolean

true for a directional antenna

angle: number (float)

Only for directional antenna. In decimal degrees, north is 0, counting up clockwise.

gain: number (float)

Antenna's gain

minFreq: integer (int64)

Minimum frequency of the antenna according to its specs.

maxFreq: integer (int64)

Maximum frequency of the antenna according to its specs.

connected: boolean

Indicates that sensor is connected to ElectroSense.

sensing: boolean

Indicates that sensor is currently collecting measurements

lastConnectionEvent: integer (int32)

Date and time of last connection state update in seconds since epoch (Unix time). If 'connected' is false this gives the last time the device has been connected to ElectroSense. If 'connected' is true, this field provides the time since the device is connected.