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"
• 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",
  "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": {
    ......
  }
}

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

NA

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

NA

Responses

NA

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

NA

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

NA

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

NA

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

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
      },
      ......
    ]
  }, 
  "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": {
    ......
  }
}