Skip to main content
Skip table of contents

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

  • hasMeterReadings: Indicates if this input has meter readings available. BOOLEAN

  • 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

Meter Reading For Meter Id

  • outpostId: Outpost Id for the site. STRING

  • siteId: UUID of the site. STRING

  • meterId: Meter Id from the custom field. STRING

  • inputId: UUID of the input. STRING

  • readingDateTimeUtc: Timestamp of the meter reading. STRING

  • readingValue: Value of the meter reading. DOUBLE

Meter Reading For Meter Id Paged Results

  • data: List of METERREADINGFORMETERID.

  • nextPageUrl: URL to retrieve the next page of results. STRING

  • metadata:

    • count: count of the records returned in data list. INTEGER

    • nextStart: Date and time in UTC for the next page request. STRING NULLABLE

    • pageSize: Record of the page size originally requested. INTEGER

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

Categories

  • URL: /api/v1/categories

  • Method: GET

  • Description: Fetches available categories for the user.

  • Response Format: Array of STRING

  • Response Example:

    JSON 
    [
	"Electric Conductivity - Soil",
	"Moisture - Soil",
	"Rain",
	"Signal strength - device",
	"Soil Moisture",
	"Temperature - Soil",
	"Unknown"
]

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,
                "hasMeterReadings": false,
				"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,
                "hasMeterReadings": false,
				"customFields": []
			},
			{
				"id": "8c9239ec-2a8a-40b0-8182-b0981cda84d5",
				"name": "NACS #1 - Counter",
				"logical": "C1",
				"scada": null,
				"loggingInterval": 0,
				"unit": "",
				"category": null,
				"sensor": null,
				"sensorType": null,
                "hasMeterReadings": false,
				"customFields": []
			},
			{
				"id": "8c9239ec-297c-40b0-a8d7-68141ed869b7",
				"name": "Precipitation",
				"logical": "C2",
				"scada": null,
				"loggingInterval": 600,
				"unit": "",
				"category": null,
				"sensor": null,
				"sensorType": null,
                "hasMeterReadings": false,
				"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",
                "hasMeterReadings": false,
				"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",
                "hasMeterReadings": false,
				"customFields": []
			},
			.....
		],
		"customFields": [
		  {
		     "name": "License",
		     "value": "1234567"
		  }		
		]	
	},
	....
]

Measurements

Measurements are the individual reading values returned for an input. It is possible to get readings for multiple sites, inputs or input categories from this endpoint in one request.

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

  1. By Device IDs:
    Query: deviceids=['op74525', 'op70449']
    Example Request:

    CODE 
    GET /api/v1/measurements?query=deviceids=['op74525','op70449']

  2. 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

  3. By Input IDs:
    Query: ids=[9e33b4a4-6b98-40dc-88f0-761057e76940]
    Example Request:

    CODE 
    GET /api/v1/measurements?query=ids=[9e33b4a4-6b98-40dc-88f0-761057e76940]

  4. 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

Meter Readings

Meter readings are the manually entered meter readings associated with an input. The time of these inputs depends on the date and time entered when the manual reading is taken. In the case of manual readings we return the value entered by the user of the application.

We support three types of filters to retrieving meter readings 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=['Flow Meter - Irrigation']

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.

Meter readings based on time range

  • URL: /api/v1/meterreadings

  • 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": "029c99f0-f53a-4e05-bb86-1db8dc19f634",
    "measurements": [
      {
        "time": "2025-04-01T08:49:00",
        "value": 152031
      },
      {
        "time": "2025-05-01T09:23:00",
        "value": 152122
      },
      {
        "time": "2025-06-01T06:30:00",
        "value": 152352
      }
    ]
  }
]

    ​

Latest Meter Readings

  • URL: /api/v1/meterreadings/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": "2025-06-01T06:30:00",
        "value": 152352
      }
    ]
  }
]

    ​

Meter Readings For Meter Ids

The MeterReadingsForMeterIds endpoint returns meter readings for inputs that include custom fields called MeterId, Meter Id, Meter Number, or Meter Serial Number. This endpoint is designed to handle large datasets efficiently using time-based pagination.

  • URL: /api/v1/meterreadingsformeterids

  • Method: GET

  • Query Parameters:

    • start: Start date and time in UTC (ISO 8601 format) (Optional: defaults to 1 day ago)

    • end: End date and time in UTC (ISO 8601 format) (Optional: defaults to current time)

    • meterIds: A list of Meter IDs to filter the results by. (Optional: defaults to include all Meter IDs)

    • pageSize: Maximum number of meter readings per page. (Optional: defaults to 10,000, maximum 50,000)

  • Response Format: ​METERREADINGFORMETERIDPAGEDRESULTS

  • Response Example:

JSON 
{
  "data": [
    {
      "outpostId": "op-test1",
      "siteId": "550e8400-e29b-41d4-a716-446655440000",
      "meterId": "METER-001",
      "inputId": "660e8400-e29b-41d4-a716-446655440001",
      "readingDateTimeUtc": "2023-06-01T08:15:30.000Z",
      "readingValue": 1234.56
    },
    {
      "outpostId": "op-test2",
      "siteId": "550e8400-e29b-41d4-a716-446655440002",
      "meterId": "METER-002",
      "inputId": "660e8400-e29b-41d4-a716-446655440003",
      "readingDateTimeUtc": "2023-06-01T08:16:45.000Z",
      "readingValue": 987.65
    }
  ],
  "nextPageUrl": "https://api.example.com/api/v1/MeterReadingsForMeterIds?start=2023-06-01T08:16:45.003Z&end=2023-06-30T23:59:59Z&pageSize=10000",
  "metadata": {
    "count": 2,
    "nextStart": "2023-06-01T08:16:45.003Z",
    "pageSize": 10000
  }
}

Pagination

This endpoint uses time-based pagination rather than traditional offset/limit pagination for better performance with large datasets.

How it works:

  1. Results are ordered chronologically by ReadingDateTimeUtc

  2. Each response includes a nextPageUrl for the next page

Pagination Flow:

  1. First request: Use start and end parameters

  2. Subsequent requests: Use the nextPageUrl from the previous response, or manually set start to the nextStart value from metadata

Example Queries

Basic Query (First Page)
HTTP 
GET /api/v1/MeterReadingsForMeterIds?start=2023-06-01T00:00:00Z&end=2023-06-30T23:59:59Z
With Specific Meter IDs
HTTP 
GET /api/v1/MeterReadingsForMeterIds?start=2023-06-01T00:00:00Z&end=2023-06-30T23:59:59Z&meterIds=METER-001&meterIds=METER-002
Custom Page Size
HTTP 
GET /api/v1/MeterReadingsForMeterIds?start=2023-06-01T00:00:00Z&end=2023-06-30T23:59:59Z&pageSize=1000
Subsequent Page (using nextStart)
HTTP 
GET /api/v1/MeterReadingsForMeterIds?start=2023-06-05T14:30:00.123Z&end=2023-06-30T23:59:59Z&pageSize=1000

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

Swagger - 2025-07-09.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

Insomnia Document & Collection - 2025-07-09.yaml

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close