API Documentation

This document is intended for experienced developers and technical professionals who are familiar with the purpose and function of APIs, as well as general programming principles. If you are not confident in your understanding of API usage, integration, or the foundational concepts of software development, this document may not be suitable for your needs. Incorrect implementation based on an incomplete understanding can lead to unexpected behaviors, errors, or system vulnerabilities. Please consult with a knowledgeable developer or technical expert before proceeding.

Overview

The Wildeye API allows users to extract time-series information recorded by Wildeye. It supports providing information on the type of data the time-series represents, and the measurements.

The API current does not support any form of aggregation of the time-series information.

Base URL: https://api.mywildeye.com

Authentication

The API uses JWT Bearer token authentication. A token (API Key) can be obtained from a client administrator through Wildeye’s web interface. The token (API Key) provides access control restrictions to the set of Clients, set of Groups, or set of Sites that can be access via the API.

Include the token (API Key) in the Authorization header of your request.

See this API Keys for how to setup API keys.

Example Header:

CODE

Authorization: Bearer <your-token>

Endpoint for Testing Authentication:

URL: /api/v1/ping/auth
Method: GET
Description: Verifies if the authentication header is correct.
Response: 200 OK
Response Example:
authenticated pong (id, ...) (clientId, ....) (nbf, ....) (exp, .....) (iat, .....)

API Rate Limits

Currently, there are no enforced rate limits on API usage. However, we reserve the right to implement rate limits or restrict access if we detect excessive usage or abuse. To ensure continued access, we encourage responsible usage of the API.

Date Formats

Dates and times returned via the API will all be in UTC.

Example:

CODE

"lastUpload": "2025-01-10T20:02:21.31",

Dates and times used in the query string are in UTC. It is not required to send through the time component of the date, if a time component is not supplied it will default to midnight.

Data Model

Site

id: UUID of the site. STRING
name: Name of the site. STRING NULLABLE
projectReference: Project reference stored against the site. STRING NULLABLE
lastUpload: Date and time of the last upload received. STRING DATE/TIME NULLABLE
deviceId: Device ID associated with the site. STRING NULLABLE
gps: Location of the site. GPS NULLABLE
displayTimezone: Timezone information is displayed in for this site. TIMEZONE NULLABLE
client: Client the site belongs to. CLIENT NULLABLE
inputs: List of inputs at the site. INPUT NULLABLE
customFields: List of custom fields and their values. CUSTOM FIELD

GPS

latitude: Latitude DOUBLE
longitude: Longitude DOUBLE

Time Zone

offset: Offset of the time zone from UTC. STRING
followsDST: Indicates if the time zone follows daylight savings time or is a fixed offset from UTC. BOOLEAN

Client

id: UUID of the client. STRING
name: Name of the client. STRING NULLABLE

Input

id: UUID of the input. STRING
name: Name of the input. STRING NULLABLE
logical: Logical name of the input. STRING NULLABLE
scada: Scada ID tag for the input. STRING NULLABLE
loggingInterval: Interval for logging in seconds. DOUBLE
unit: Unit of measurement. STRING NULLABLE
category: Category of the measurement. STRING NULLABLE
sensor: Sensor name for the input. STRING NULLABLE
sensorType: Sensor type for the input. STRING NULLABLE
customFields: List of custom fields and their values. CUSTOM FIELD

Input Measurement

id: UUID of the input. STRING
measurements: List of measurements for the referenced input. MEASUREMENT NULLABLE

Measurement

time: Timestamp of the measurement. STRING
value: Value recorded at the time. DOUBLE

Custom Field

name: Name of the custom field. STRING
value: Value of the custom field. STRING

Available Endpoints

Ping

URL: /api/v1/ping
Method: GET
Description: Checks if the service is alive.
Response: 200 OK
Response Format: STRING
Response Example:
TEXT
```
pong
```

Sites

URL: /api/v1/sites
Method: GET
Description: Fetches a list of sites and their associated inputs.
Response Format: Array of SITE

Response Example:

JSON

[
	{
		"id": "32525cb8-1934-4bcf-a5c8-c7fdfc6671c5",
		"name": "North Pole",
		"projectReference": null,
		"lastUpload": "2025-01-10T20:02:21.31",
		"deviceId": "op999999",
		"gps": {
			"latitude": 90.000,
			"longitude": 0.000
		},
		"displayTimezone": {
			"offset": "+10:00",
			"followsDST": true
		},
		"client": {
			"id": "8d6e9408-c086-429e-b995-448196610c06",
			"name": "Santa Services Limited"
		},
		"inputs": [
			{
				"id": "2bc976f0-f2ac-48f7-a1b3-09e21d0845ed",
				"name": "NACS #1 - 4-20mA Analogue",
				"logical": "A1",
				"scada": null,
				"loggingInterval": 0,
				"unit": null,
				"category": null,
				"sensor": null,
				"sensorType": null,
				"customFields": []
			},
			{
				"id": "eba49c05-f2ac-472d-85ec-b0981cda84d5",
				"name": "NACS #2 - 4-20mA Analogue",
				"logical": "A2",
				"scada": null,
				"loggingInterval": 0,
				"unit": "",
				"category": null,
				"sensor": null,
				"sensorType": null,
				"customFields": []
			},
			{
				"id": "8c9239ec-2a8a-40b0-8182-b0981cda84d5",
				"name": "NACS #1 - Counter",
				"logical": "C1",
				"scada": null,
				"loggingInterval": 0,
				"unit": "",
				"category": null,
				"sensor": null,
				"sensorType": null,
				"customFields": []
			},
			{
				"id": "8c9239ec-297c-40b0-a8d7-68141ed869b7",
				"name": "Precipitation",
				"logical": "C2",
				"scada": null,
				"loggingInterval": 600,
				"unit": "",
				"category": null,
				"sensor": null,
				"sensorType": null,
				"customFields": []
			},
			{
				"id": "7706c201-43c9-b5e8-b327-233175c5f7d8",
				"name": "Signal Strength",
				"logical": "RSRP",
				"scada": null,
				"loggingInterval": 0,
				"unit": "dBm",
				"category": "Signal strength - device",
				"sensor": "Default",
				"sensorType": "Default",
				"customFields": []
			},
			{
				"id": "73344c201-b5e8-45eb-b5e8-9b12342d0855",
				"name": "Soil Moisture",
				"logical": "3S",
				"scada": null,
				"loggingInterval": 3600,
				"unit": "",
				"category": "Unknown",
				"sensor": "Soil sensor (8 level)",
				"sensorType": "EnviroPro soil moisture probes",
				"customFields": []
			},
			.....
		],
		"customFields": [
		  {
		     "name": "License",
		     "value": "1234567"
		  }		
		]	
	},
	....
]

Measurements

We support three types of filters to retrieving measurements at present. The filters are applied in the query parameter and query by Input Category, Input Id, or Device Id. Each of these allows you to pass an array for filtering. You can not combine the filters in a single request.

By Device Ids: query=deviceids=['op999999', 'op999998', 'op999997']
By Input Ids: query=ids=['73344c201-b5e8-45eb-b5e8-9b12342d0855', '8c9239ec-297c-40b0-a8d7-68141ed869b7']
By Categories: query=categories=['Wind Speed', 'Rain', 'Signal Strength - device']

Paginated Results

Measurement results are paginated into pages of 10,000 results. If you are querying for a large range of data from the API your client will need to support paging through the results. Pass the page parameter in the query string to request a specific page of results.

Measurements based on time range

URL: /api/v1/measurements
Method: GET
Query Parameters:
- query: Query string (e.g., ids=[...] or categories=[...] or deviceids=[...]).
- start: Start date-time (optional, defaults to 1 day ago).
- end: End date-time (optional).
- page: Page number for pagination.
Response Format: Array of INPUT MEASUREMENT

Response Example:

JSON

[
  {
    "id": "d18bca39-4ff9-40e8-8596-2b690a55b064",
    "measurements": [
      {
        "time": "2024-03-07T04:31:00",
        "value": -10.43
      },
      ....
    ]
  },
  ....
]

Latest Measurements

URL: /api/v1/measurements/latest
Method: GET
Query Parameters:
- query: Query string (e.g., ids=[...]).
- count: Number of latest measurements (optional).
- page: Page number for pagination.
Response Format: Array of INPUT MEASUREMENT

Response Example:

JSON

[
  {
    "id": "029c99f0-f53a-4e05-bb86-1db8dc19f634",
    "measurements": [
      {
        "time": "2024-03-07T04:31:00",
        "value": -10.43
      }
    ]
  }
]

How to Retrieve Measurements

By Device IDs:
Query: deviceids=['op74525', 'op70449']
Example Request:
CODE
```
GET /api/v1/measurements?query=deviceids=['op74525','op70449']
```
By Categories:
Query: categories=['Wind Speed']&start=2024-10-07
Example Request:
CODE
```
GET /api/v1/measurements?query=categories=['Wind Speed']&start=2024-10-07
```
By Input IDs:
Query: ids=[9e33b4a4-6b98-40dc-88f0-761057e76940]
Example Request:
CODE
```
GET /api/v1/measurements?query=ids=[9e33b4a4-6b98-40dc-88f0-761057e76940]
```
Latest 5 measurements from an Input ID :
Query: ids=[9e33b4a4-6b98-40dc-88f0-761057e76940]
Example Request:
CODE
```
GET /api/v1/measurements/latest?query=ids=[9e33b4a4-6b98-40dc-88f0-761057e76940]&count=5
```

Swagger Documentation

We have attached the Swagger documentation below. This can be viewed in opened and viewed in https://editor.swagger.io/ , or used to generate an API client with software development tools.

Swagger - 2024-11-27.json

Insomnia Collection

We have also created a collection of Insomnia requests, that can both aid in development, and testing the API.
Insomnia Document & Collection - 2024-11-27.json

Overview

Authentication

API Rate Limits

Date Formats

Data Model

Site

GPS

Time Zone

Client

Input

Input Measurement

Measurement

Custom Field

Available Endpoints

Ping

Categories

Sites

Measurements

Paginated Results

Measurements based on time range

Latest Measurements

How to Retrieve Measurements

Swagger Documentation

Insomnia Collection