Control Your Netro Devices Through a Public API

Published on 2021-03-31

Netro Public API Manual

Overview

The NPA (Netro Public API) allows you to control your Netro devices through a public API, which also provides infinite flexibility in integrating with other services.

If you have any questions or feedback you can send email to support@netrohome.com.

You need a key to access the API, which is the serial number or your Netro devices. For Netro controllers (e.g. Sprite, Spark, Pixie), the serial number is provided in the Netro App (Settings -> controller -> serial number). For Netro sensors (e.g. Whisperer), the serial number is in (Setting->Sensors -> Serial Number). Please keep your serial number as secret as anyone with this key could access your NPA APIs.

NPA API has rate limiting in order to improve server performance for all users. We only allow 2,000 calls per day, which is over 1 call per minute. Limits are reset in midnight UTC time.

Each API returns a JSON data as response. The JSON is a dictionary with

status: 'OK'/'ERROR'
data: Returned data for OK status, could be empty
errors: only for ERROR status, it is an array of json dictionary with
- code: error code.
- message: error message.
meta: meta information.
- time: Current UTC time
- tid: unique transaction ID.
- version: API version, "1.0".
- token_limit: 2000 or 0 if invalid key
- token_remaining: remaining token of today, access will be denied if no token
- token_reset: token reset time
- last_active: last access time

For example:

{
  "status": "OK",
  "meta": {
    "time": "2020-12-24T11:41:34",
    "tid": "1608810094_AisU",
    "version": "1.0",
    "token_limit": 2000,
    "token_remaining": 1980,
    "last_active": "2020-12-24T11:41:34",
    "token_reset": "2020-12-25T00:00:00"
  },
  "data": {
      ......
  }
}

API list

NPA provides the following APIs:

API Action Note

Device

info GET Get basic information of the device

schedules GET Get schedules
moisture GET Get moisture data
events GET Get events
set_status POST update status to online or standby
water POST Start watering
stop_water POST Stop watering
no_water POST Do not water
report_weather POST report weather
set_moisture POST set moisture
Sensor
sensor_data GET Get sensor data

Making your first request

Once you have acquired your device serial, you can grab the basic information of the device and begin making requests

curl -v https://api.netrohome.com/npa/v1/info.json?key=ABCDEFG

The response is like

{
  "status": "OK",
  "data": {
    "device": {
      "name": "Netro Device",
      "zone_num": 12,
      "serial": "ABCDEFG",
      "version": "2.2",
      "status": "ONLINE",
      "sw_version": "2.2.0",
      "zones": [
        {
          "name": "frontyard",
          "ith": 1,
          "enabled": true,
          "smart": "SMART"
        },
        ......
      ]
    }
  },
  "meta": {
    ......
  }
}

Device APIs

GET /npa/v1/info.json

This API provides basic information of the device.

Params

key: required

Responses

name: device name
zone_num: number of devices
serial: device serial number
status: current status of device, could be "STANDBY" "SETUP" "ONLINE" "WATERING" "OFFLINE" "SLEEPING" "POWEROFF"
version: hardware version
sw_version: firmware version
last_active: the UTC time when your device last connects server, e.g. "2021-03-13T03:28:58"
battery_level: battery level, for Pixie only, float value in range of [0,1]
zones: array of zone information, for each zone, includes
- name: name of the zone
- ith: index of the zone
- enabled: zone is enabled or not
- smart: smart configuration of the zone. could be
  - "SMART": Advanced smart
  - "ASSISTANT": Basic smart
  - "TIMER": No smart

Example

Request:

curl "https://api.netrohome.com/npa/v1/info.json?key=ABCDEFG"

Response:

{
  "status": "OK",
  "meta": {
    ...
  },
  "data": {
    "device": {
      "name": "Netro Device",
      "serial": "ABCDEFG",
      "zone_num": 1,
      "status": "OFFLINE",
      "version": "1.3",
      "sw_version": "1.3.2",
      "last_active": "2022-06-27T10:24:41",
      "battery_level": 1.0,
      "zones": [
        {
          "name": "Zone",
          "ith": 1,
          "enabled": true,
          "smart": "TIMER"
        }
      ]
    }
  }
}

GET /npa/v1/schedules.json

This API provides device schedules in specific range. The schedules are typically updated at least once per day, or requested by customers via Netro APP.

Params

zones: (optional), array of zone index. Use all zones if not specified.
start_date/end_date: (optional), specify the date range of schedules. Return schedules in the past month and next month if not specified.

Responses

Array of schedules, each schedule includes

id: unique ID
zone: zone index
start_time, end_time: schedule start and end time (UTC time)
local_date, local_start_time, local_end_time: schedule start and end time (local time)
source: source of the schedule, could be
- SMART: Netro generated schedule
- FIX: schedules from programs
- MANUAL: manual watering
status: status of the schedule, could be
- VALID: New schedules, not executed
- EXECUTING: Watering schedules
- EXECUTED: Executed schedules in the past

Example

Request:

curl "http://api.netrohome.com/npa/v1/schedules.json?key=ABCDEFG&start_date=2020-12-30&end_date=2021-01-30&zones=[1,2]"

Response:

{
  "status": "OK",
  "data": {
    "schedules": [
      {
        "id": 63828923,
        "zone": 4,
        "start_time": "2020-12-30T13:00:00",
        "end_time": "2020-12-30T13:01:00",
        "local_date": "2020-12-30",
        "local_start_time": "05:00:00",
        "local_end_time": "05:01:00",
        "source": "SMART",
        "status": "VALID"
      },
      ......
    ]
  }, 
  "meta": {
    ......
  }
}

GET /npa/v1/moistures.json

This API provides zone moisture level information in the past. This data is typically updated once per day.

Params

zones: (optional), array of zone index. Use all zones if not specified.
start_date/end_date: (optional), specify the date range of moisture. Return moistures in the past month and next month if not specified.

Responses

Array of moisture data, each includes:

id: unique ID
zone: zone index
date: local date
moisture: moisture level of the zone, in the range of [0,100]

Example

Request:

curl "http://api.netrohome.com/npa/v1/moistures.json?key=ABCDEFG&start_date=2020-12-30&end_date=2021-01-30&zones=[1,2]"

Response:

{
  "status": "OK",
  "data": {
    "moistures": [
      {
        "id": 9255769,
        "zone": 1,
        "date": "2020-09-09",
        "moisture": 69
      },
      ......
    ]
  },
  "meta": {
    ......
  }
}

GET /npa/v1/events.json

This API provides device events.

Params

event: (optional), specify the type of events. Return all types of events if not specified. We support the following types:
- 1: device offline event
- 2: device online event
- 3: schedule start event
- 4: schedule end event
start_date/end_date: (optional), specify the date range of moisture. Return moistures in the past month and next month if not specified.

Responses

Array of events, each event includes:

id: unique ID
event: type of the event
time: event time (UTC time)
message: description of the device

Example

Request:

curl "http://api.netrohome.com/npa/v1/events.json?key=ABCDEFG&event=1"

Response:

{
  "status": "OK",
  "data": {
    "events": [
      {
        "event": 3,
        "id": 638289413,
        "time": "2021-01-09T03:00:00",
        "message": "Start to water zone 4 at 19:00:00 on 2021-01-08"
      },
      ......
    ]
  },
  "meta": {
    ......
  }
}

POST /npa/v1/set_status.json

This API is for disabling or enabling a device.

Params

status: device status to set
- 0: disable, change status to STANDBY
- 1: enable, change status to ONLIN

Responses

Example

Request:

curl -X POST -H "Accept: application/json" -H 'Content-Type:application/json' -d '{"key":"ABCDEFG", "status":0}' "https://api.netrohome.com/npa/v1/set_status.json"

Response:

{
  "status": "OK",
  "data": {
  },
  "meta": {
    ......
  }
}

POST /npa/v1/water.json

This API is water the yard immediately or at specific time.

Params

zones: (optional), specify the zones to water, array of zone index. Water all zones if not specified.
duration: number of minutes to water.
delay: (optional) start watering after delay minutes.
start_time: (optional), specify the start time (UTC time), must be later than current time. It has higher priority than delay if both provided.

Responses

Array of created schedules, each schedule includes

id: unique ID
zone: zone index
start_time, end_time: schedule start and end time (UTC time)
local_date, local_start_time, local_end_time: schedule start and end time (local time)
source: source of the schedule, "MANUAL"
status: status of the schedule, "VALID"

Example

Request:

curl -X POST -H "Accept: application/json" -H 'Content-Type:application/json' -d '{"key":"ABCDEFG", "zones": [1], "duration":1,"delay":5,"start_time":"2020-12-30 08:00"}' "https://api.netrohome.com/npa/v1/water.json"

Response:

{
  "status": "OK",
  "data": {
    "schedules": [
      {
        "id": 63828923,
        "zone": 4,
        "start_time": "2020-12-30T13:00:00",
        "end_time": "2020-12-30T13:01:00",
        "local_date": "2020-12-30",
        "local_start_time": "05:00:00",
        "local_end_time": "05:01:00",
        "source": "SMART",
        "status": "VALID"
      },
      ......
    ]
  },
  "meta": {
    ......
  }
}

POST /npa/v1/stop_water.json

This API is for stopping current watering schedules and all remaining manual schedules.

Params

Responses

Example

Request:

curl -X POST -H "Accept: application/json" -H 'Content-Type:application/json' -d '{"key":"ABCDEFG"}' "https://api.netrohome.com/npa/v1/stop_water.json"

Response:

{
  "status": "OK",
  "data": {
  },
  "meta": {
    ......
  }
}

POST /npa/v1/no_water.json

This API is for stopping all schedules today and following number of days.

Params

days: (optional), no water days, in the range of [1,100], 1 for today, default is 1.

Responses

Example

Request:

curl -X POST -H "Accept: application/json" -H 'Content-Type:application/json' -d '{"key":"ABCDEFG", "days":2}' "https://api.netrohome.com/npa/v1/no_water.json"

Response:

{
  "status": "OK",
  "data": {
  },
  "meta": {
    ......
  }
}

POST /npa/v1/set_moisture.json

This API is for setting zone moisture, overriding system estimated moisture.

Params

zones: (optional), specify the zones to water, array of zone index. Water all zones if not specified.
moisture: moisture level, in the range of [0,100]

Responses

Example

Request:

curl -X POST -H "Accept: application/json" -H 'Content-Type:application/json' -d '{"key":"ABCDEFG", "moisture":100}' "https://api.netrohome.com/npa/v1/set_moisture.json"

Response:

{
  "status": "OK",
  "data": {
  },
  "meta": {
    ......
  }
}

POST /npa/v1/report_weather.json

This API is for reporting weather data, overriding system default weather data.

Params

date: weather date, can not be earlier than yesterday
condition: (optional), weather condition, in the list of:
- 0: clear
- 1: cloudy
- 2: rain
- 3: snow
- 4: wind
rain: (optional), rainfall amount, in the unit of mm
rain_prob: (optional), rainfall probability, in the range of [0,100]
temp: (optional) average temperature, Celsius temperature.
t_min: (optional) minimum temperature.
t_max: (optional) maximum temperature.
t_dew: (optional),dew point temperature.
wind_speed: (optional), wind speed, unit of m/s
humidity: (optional), humidity, in the range of [0,100]
pressure: (optional), air pressure, in the unit of hpa

Responses

Example

Request:

curl -X POST -H "Accept: application/json" -H 'Content-Type:application/json' -d '{"key":"ABCDEFG", "date":"2020-12-30", "rain": 0.1, "condition":1, "rain_prob":50, "temp":20.0}' "https://api.netrohome.com/npa/v1/report_weather.json"

Response:

{
  "status": "OK",
  "data": {
  },
  "meta": {
    ......
  }
}

Sensor APIs

GET /npa/v1/sensor_data.json

This API provides sensor reported data in specific range. A sensor typically reports a set of data per hour.

Params

start_date/end_date: (optional), specify the date range of schedules. Return schedules in the past month if not specified.

Responses

Array of sensor data, each data includes

id: unique
time: UTC time
local_date, local_time: local time
moisture: moisture level, in the range of [0,100]
sunlight: sunlight, unit of klux
celsius: temperature
fahrenheit: temperature
battery_level: level of battery, in the range of [0,100]

Example

Request:

curl "http://api.netrohome.com/npa/v1/sensor_data.json?key=ABCDEFG&start_date=2020-12-30&end_date=2021-01-30

Response:

{
  "status": "OK",
  "data": {
    "sensor_data": [
      {
        "id": 4933685,
        "time": "2020-07-04T23:07:17",
        "local_date": "2020-07-04",
        "local_time": "16:07:17",
        "moisture": 78,
        "sunlight": 120.312,
        "celsius": 34.0,
        "fahrenheit": 93.2,
        "battery_level": 95
      },
      ......
    ]
  }, 
  "meta": {
    ......
  }
}

Errors

NPA APIs will provide both error code and message in case of any error. Here is the list of error code:

Code Note 1 Invalid key 3 Exceed limit 4 Invalid device or sensor 5 Internal error 6 Parameter error

For example

{
  "status": "ERROR",
  "errors": [
    {
      "code": 1,
      "message": "Invalid key: invalid",
    }
  ],
  "meta": {
    ......
  }
}

Back