Our API allows anybody to utilize when2water decisions in their own projects. For example, someone creating their own irrigation controller could use our API to get irrigation decisions, allowing them to reduce wasteful irrigation and save themselves water, electricity, and money.
The API endpoint is at https://api.when2water.org/.
All API requests will begin with the endpoint.
The API is RESTful.
It accepts parameters through the query string.
The API can return either unformatted data or JSON formatted data.
This service is free and always will be.
Parameters are sent through HTTP Get (Query String). Currently, the API accepts two parameters.
| Parameter | Example | Details |
|---|---|---|
| zip | 90210 | Required. This is the zip code you would like a decision for. |
| json | true | Optional. If this parameter is set (to anything), the output will be JSON formatted. If this is not set, the API will respond with unformatted data. |
Example: Sending Parameters
$ curl "https://api.when2water.org/?zip=90210&json=true"
The API will respond with one of five response codes. It does not use HTTP response codes. If it encounters an error, the returned signal will notify you with an error response code, but it will still respond with HTTP 200 OK.
| Response Code | Description |
|---|---|
| 1 | The algorithm determined that there is a need to water for the entered zip code. |
| -1 | The algorithm determined that there is no need to water for the entered zip code. |
| -2 | A required parameter was missing from the query. |
| -3 | The zip code entered does not exist. |
| -4 | The server encountered an internal error while processing the request. |
If you did not specify json in your query, then the response code will be returned unformatted: -3.
If you did specify json in your query, then the response code will be an integer in the
signal variable of the JSON: {"signal":-3}.
Example: Getting an Unformatted Response
$ curl "https://api.when2water.org/?zip=99801" -1
Example: Getting a JSON Formatted Response
$ curl "https://api.when2water.org/?zip=99801&json=true"
{"signal":-1}
Example: Getting an Error Response Code, and an HTTP 200 OK, from an Invalid Request
$ curl -i "https://api.when2water.org/?zip=99999" HTTP/1.1 200 OK Date: Sat, 28 Jun 2014 03:41:07 GMT Server: Apache mod_fcgid/2.3.10-dev X-Powered-By: PHP/5.4.26 Content-Length: 2 Content-Type: text/html -3
Questions or feedback? Send us an email at [email protected].