The entire API documentation is available here: http://docs.rainmachine.apiary.io/

The RainMachine provides a REST API to interact with your device either remotely or on local network.

The first step is to authenticate with the device, the authentication flow for remote access is different than the one to directly access RainMachine on local network.

 For Remote Access service (my.rainmachine.com):

- (1) POST https://my.rainmachine.com/login/auth with body:

{"user": {"email": "email@account.com","pwd":"xxxxx","remember": true}}

This will authenticate the account with RainMachine Remote Access Service and return a JSON response. Check the  errorType field:

    - If  0 then get the access_token field and proceed to step (4)

     - If -1 then user has multiple sprinklers, get the access_token and proceed to step (2)

- (2) POST https://my.rainmachine.com/devices/get-sprinklers?access_token="obtained in step 1" with body as above. This will get a list of sprinklers associated with the account including their sprinklerId and sprinklerUrl.

- (3) POST  https://my.rainmachine.com/login-sprinkler?access_token="obtained in step 1"  with body:

{"sprinklerId": "idabcda", "pwd":"xxxxx"} 

 This will authenticate the sprinklerId specified and return a new access_token that should be included in step (4)

- (4)  You can now call the RainMachine API:

GET https://api.rainmachine.com/sprinklerId/api/4/provision?access_token="newly obtained access token"

 

For local network access on port 8080 HTTPS or 8081 HTTP:

- (1) POST https://rainmachine_ip:8080/api/4/auth/login with body:

{ "pwd": "xxxx", "remember":true}

- (2)  You can now call the RainMachine API with the access_token obtained from above call:

 GET https://rainmachine_ip:8080/api/4/provision?access_token=....

Important: When doing POST requests make sure you include "Content-type: application/json" header and POST call has a body. If you are performing a POST without a body make sure you sent "Content-length: 0" header.

 

Examples:

In the following examples will consider that your RainMachine has the ip address 192.168.12.175. You can replace this ip address with host name, cloud host name or a mock server address from
http://docs.rainmachine.apiary.io/ (eg: https://private-bd9e-rainmachine.apiary-mock.com/)

First API call (getting the basic information about device):
Simply open this url in your browser: https://192.168.12.175:8080/api/4/apiVer you should receive a json with several key/values:

{
"apiVer": "4.0.0",
"hwVer": 2,
"swVer": "4.0.535"
}

Here apiVer means the version of the API available on device, hwVer is the hardware version of the device and swVer is the rainmachine app version.
Notice that this API call didn’t require any authentification with the device, but except this call and auth/login call all other calls must use a OAuth token otherwise an error 401 Unauthorized will be returned.

Authenticating with the device:

The first step on working with API calls that require authentification is obtaining a OAuth token. Once you have this token you should add it to all your requests like this:
https://192.168.12.175:8080/api/4/program?access_token=YOUR_ACCESS_TOKEN.
If you don’t have a token you must login to the device first. This is accomplished by a POST request with /auth/login as URL and with json body containing the password:

curl -X POST -k -d ' { "pwd": "admin", "remember":true}' https://192.168.12.175:8080/api/4/auth/login

The received json will contain:

{
"access_token": "eb426a74a46dfc46b6c991cb21a9901d917e1e57011599d79e248fab",
"checksum": "a31f3570f9ac79387400e87719df93d1028479c45ed46948abf96800218b0c5146dbcd7ce0e11cc1b671e1f579766334d05caf4c9fe80201",
"expires_in": 86400,
"expiration": "Thu, 04 Jun 2015 10:02:50 GMT",
"statusCode": 0
}

Now you can use the value from “access_token” key to call the rest of the API calls. Using the access token to get the daily statistics: Simply issue a GET request with /dailystats call:

curl -k https://192.168.12.175:8080/api/4/dailystats?access_token=eb426a74a46dfc46b6c991cb21a9901d917e1e57011599d79e248fab

The received JSON will look similar to:

{
"DailyStats": [
{
"id": 0,
"day": "2015-06-03",
"mint": 22.699999999999999,
"maxt": 28.800000000000001,
"icon": 2,
"percentage": 87.70151065356437,
"wateringFlag": 0,
"vibration": [
88,
88
],
"simulatedPercentage": 87.70151065356437,
"simulatedVibration": [
88,
88
]
},
{
"id": 1,
"day": "2015-06-04",
"mint": 18.600000000000001,
"maxt": 28.5,
"icon": 2,
"percentage": 0,
"wateringFlag": 0,
"vibration": [
0,
0
],
"simulatedPercentage": 0,
"simulatedVibration": [
0,
0
]
}
]
}

You can parse this json to extract the required data, using your favorite language. More information about the API and JSON responses can be found here: http://docs.rainmachine.apiary.io/

A more complex example:
In this example we’ll use information provided by an API call to perform another call. The task that we want to perform is to activate another weather parser on device that uses Met.no weather service. Once activated this parser will run periodically and fetch data from internet.

Step 1.
List all parsers installed on your system and retrieve the ID of the parser that you want to activate. For this /api/4/parser/ API call is used

curl -k https://192.168.12.175:8080/api/4/parser?access_token=eb426a74a46dfc46b6c991cb21a9901d917e1e57011599d79e248fab

The reply json will contain (the example bellow it’s a stripped down version of the actual response):

{
"parsers":
[
{
"lastRun": null,
"custom": false,
"enabled": false,
"uid": 5,
"name": "METNO Parser"
}
]
}

The key/value that we’re interested in is the "uid": 5 this is the ID of the Met.no parser.

Step 2.
Activate parser by issuing a POST with data and the /api/4/parser/ID/ API call:

curl -X POST -k -d '{"activate": true}' https://192.168.12.175:8080/api/4/parser/5/activate?access_token=eb426a74a46dfc46b6c991cb21a9901d917e1e57011599d79e248fab

The response should be: { "statusCode": 0, "message": "OK"} which means the API call succeeded in setting Met.no parser as active.

This concludes our quick start guide. You can get more information, sample code and full Parser API documentation here: http://docs.rainmachineparsers.apiary.io/#reference

Other API Examples can be found here: https://github.com/sprinkler/rainmachine-developer-resources/tree/master/api-examples