What is the when2water API?

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.


Overview

The API endpoint is at http://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.

Sending Parameters

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 "http://api.when2water.org/?zip=90210&json=true"

Response

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 "api.when2water.org/?zip=99801"
-1

Example: Getting a JSON Formatted Response

$ curl "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 "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 api@when2water.org.