Gardening Regions API

The Gardening Region

The ET Unity service considers a Gardening Region any single area to which it associates a single set of landscape parameters, such as the plant type, soil type, shade percentage, etc. A Gardening Region can be for a single plant or for an area of the same plants. The Gardening Region is defined as a geometric figure that is related to some location. In most cases Gardening Regions are created to describe your vegetation, but it could also be a shade structure (building, fence) or a water feature (pond, pool. etc.). The Gardening Regions API provides a capability to manage your regions, group them into a zone, and manage their vegetation types and irrigation methods. As a result, regions are the foundation for a full variety of insights into your landscape provided via the Unity API.

How to create a region

On the Unity platform, regions cannot be created before first creating a project. Any region that you create should be assigned a project ID. This ID is received when creating a project using the Gardening Projects API. Let’s assume that we have a project with ID: 57ee6a8c0e8e3d000155557b

Creating a region is a fairly simple process. First of all, the gardening region is a GeoJSON object. You can read more about GeoJSON at http://geojson.org/ or play with it at http://geojson.io/. To start with something, let’s use the http://geojson.io/ tool and map our first region.

Region 1

Let’s use the rectangle tool and map the above blue rectangle as our shape. On the right there is a text area with the GeoJSON for our region:

{
	"type": "Feature",
	"properties": {
		"stroke": "#00ffff",
		"stroke-width": 2,
		"stroke-opacity": 1,
		"fill": "#00ffff",
		"fill-opacity": 0.2
	},
	"geometry": {
		"type": "Polygon",
		"coordinates": [
			[
				[
					-118.0868911743164,
					33.94105467688279
				],
				[
					-118.0868911743164,
					33.9423586305379
				],
				[
					-118.08632791042328,
					33.9423586305379
				],
				[
					-118.08632791042328,
					33.94105467688279
				],
				[
					-118.0868911743164,
					33.94105467688279
				]
			]
		]
	}
}

Of the above GeoJSON object, we’re only interested in the geometry field, because it contains the geometry for the region that we’re going to create. To create a region we need to make an HTTP call using the POST method to https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions, where {projectId} is an id of a project we’d like to assign our region to. Also, as we’re going to send data to the server, we need to specify what kind of data we’re sending using the Content-Type HTTP header. In our case content type should be application/json. Of course, the string $ACCESS_TOKEN should be replaced with your access token. Here is the JSON entity to be sent to the Unity API:

Entity to be sent

{
	"type": "Feature",
	 "geometry": {
		"type": "Polygon",
		"coordinates": [
			[
 				[
					-118.0868911743164,
					33.94105467688279
				],
				[
					-118.0868911743164,
					33.9423586305379
				],
				[
					-118.08632791042328,
					33.9423586305379
				],
				[
					-118.08632791042328,
					33.94105467688279
				],
				[
					-118.0868911743164,
					33.94105467688279
				]
			]
		]
	},
	"properties": {
		"region_name": "Front yard",
		"vegetation_type": 0,
		"sprinkler_type": 0
	}
}

The geometry in the above JSON is copied from the figure we’ve mapped on geojson.io. In this example we have taken a minimal set of properties consisting of:

Property Description
region_name Name of a region
vegetation_type Type of vegetation mapped
sprinkler_type Type of irrigation equipment


In the above example we specified the region to be of vegetation type turf and irrigation method type spray.

Note: List of all available irrigation method and vegetation types is available through corresponding APIs.

cURL request example

Here is how you’d send that JSON object using cURL:

curl -XPOST -H'Authorization: Bearer $ACCESS_TOKEN' -H'Content-Type: application/json' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ee6a8c0e8e3d000155557b/regions' -d'{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-118.0868911743164,33.94105467688279],[-118.0868911743164,33.9423586305379],[-118.08632791042328,33.9423586305379],[-118.08632791042328,33.94105467688279],[-118.0868911743164,33.94105467688279]]]},"properties":{"region_name":"Front yard","vegetation_type":0,"sprinkler_type":0}}'

Response example

And here is what you’d get back from the Unity API:

{
	"geometry": {
		"type": "Polygon",
		"coordinates": [
			[
				[
					-118.08689117432,
					33.941054676883
				],
				[
					-118.08689117432,
					33.942358630538
				],
				[
					-118.08632791042,
					33.942358630538
				],
				[
					-118.08632791042,
					33.941054676883
				],
				[
					-118.08689117432,
					33.941054676883
				]
			]
		]
	},
	"type": "Feature",
	"properties": {
		"plant_center_coordinates": [
			-118.08660070579,
			33.941704113947
		],
		"newly_planted": false,
		"vegetation_type": 0,
		"plantFactor": [
			0.61,
			0.64,
			0.75,
			1.04,
			0.95,
			0.88,
			0.94,
			0.86,
			0.74,
			0.75,
			0.69,
			0.6
		],
		"shade_level": 0,
		"project_id": "57ee6a8c0e8e3d000155557b",
		"remote_region_id": "57ee6caa0e8e3d0001555584",
		"plant_area": 7550.7323856495,
		"emitter_count": 1,
		"sprinkler_type": 0,
		"region_name":"Front yard"
		"onlyVegetation": true,
		"status": "ACTIVE",
		"version": 5,
		"extendAreaRegionType": true,
		"created_at": 1475243178934,
		"updated_at": 1475243178934,
	}
}

As you can see, a full region entity is returned. The platform will automatically calculate some of the values for newly created regions, such as the region’s center coordinates, its area, etc.

POSTMAN request and response example

If you’re using Postman, here is what that would look like:

How to create multiple regions in a batch

To make a batch call you need to perform an HTTP call to https://developer-api.etwater.com/api/v1/gardening/projects/57ee6a8c0e8e3d000155557b/regions using the PATCH HTTP method. A list of regions should be passed along with the call. Regions that already exist will get updated, regions that don’t exist yet will get created. Regions are matched by their remote_region_id.

cURL request example

curl -XPATCH -H'Authorization: Bearer $ACCESS_TOKEN' -H'Content-Type: application/json' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ee6a8c0e8e3d000155557b/regions' -d'[{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-118.0868911743164,33.94105467688279],[-118.0868911743164,33.9423586305379],[-118.08632791042328,33.9423586305379],[-118.08632791042328,33.94105467688279],[-118.0868911743164,33.94105467688279]]]},"properties":{"region_name":"Front yard","vegetation_type":1,"sprinkler_type":1}}, {"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-118.0868911743164,33.94105467688279],[-118.0868911743164,33.9423586305379],[-118.08632791042328,33.9423586305379],[-118.08632791042328,33.94105467688279],[-118.0868911743164,33.94105467688279]]]},"properties":{"region_name":"Backyard","vegetation_type":1,"sprinkler_type":1}}]'

Response example

[
	{
		"geometry": {
			"type": "Polygon",
			"coordinates": [
				[
					[
						-118.08689117432,
						33.941054676883
					],
					[
						-118.08689117432,
						33.942358630538
					],
					[
						-118.08632791042,
						33.942358630538
					],
					[
						-118.08632791042,
						33.941054676883
					],
					[
						-118.08689117432,
						33.941054676883
					]
				]
			]
		},
		"type": "Feature",
		"properties": {
			"status": "ACTIVE",
			"plant_center_coordinates": [
				-118.08660070579,
				33.941704113947
			],
			"newly_planted": false,
			"vegetation_type": 1,
			"region_name": "Front yard",
			"extendAreaRegionType": true,
			"plantFactor": [
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6
			],
			"created_at": 1475246386153,
			"shade_level": 0,
			"updated_at": 1475246386153,
			"project_id": "57ee6a8c0e8e3d000155557b",
			"remote_region_id": "57ee79320e8e3d0001555586",
			"version": 6,
			"plant_area": 7550.7323856495,
			"onlyVegetation": true,
			"emitter_count": 1,
			"sprinkler_type": 1
		}
	},
	{
		"geometry": {
			"type": "Polygon",
			"coordinates": [
				[
					[
						-118.08689117432,
						33.941054676883
					],
					[
						-118.08689117432,
						33.942358630538
					],
					[
						-118.08632791042,
						33.942358630538
					],
					[
						-118.08632791042,
						33.941054676883
					],
					[
						-118.08689117432,
						33.941054676883
					]
				]
			]
		},
		"type": "Feature",
		"properties": {
			"status": "ACTIVE",
			"plant_center_coordinates": [
				-118.08660070579,
				33.941704113947
			],
			"newly_planted": false,
			"vegetation_type": 1,
			"region_name": "Backyard",
			"extendAreaRegionType": true,
			"plantFactor": [
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6
			],
			"created_at": 1475246386156,
			"shade_level": 0,
			"updated_at": 1475246386156,
			"project_id": "57ee6a8c0e8e3d000155557b",
			"remote_region_id": "57ee79320e8e3d0001555588",
			"version": 6,
			"plant_area": 7550.7323856495,
			"onlyVegetation": true,
			"emitter_count": 1,
			"sprinkler_type": 1
		}
	}
]

The response contains a list of regions that were created or updated.

POSTMAN request and response example

How to get all regions in a project

To get all the regions in a particular project we should perform an HTTP call to https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions using the GET HTTP method.

cURL request example

curl -H'Authorization: Bearer $ACCESS_TOKEN' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ee6a8c0e8e3d000155557b/regions'

Response example

[
	{
		"geometry": {
			"type": "Polygon",
			"coordinates": [
				[
					[
						-118.08689117432,
						33.941054676883
					],
					[
						-118.08689117432,
						33.942358630538
					],
					[
						-118.08632791042,
						33.942358630538
					],
					[
						-118.08632791042,
						33.941054676883
					],
					[
						-118.08689117432,
						33.941054676883
					]
				]
			]
		},
		"type": "Feature",
		"properties": {
			"status": "ACTIVE",
			"plant_center_coordinates": [
				-118.08660070579,
				33.941704113947
			],
			"newly_planted": false,
			"vegetation_type": 1,
			"version": 5,
			"extendAreaRegionType": true,
			"plantFactor": [
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6,
				0.6
			],
			"created_at": 1475242681653,
			"shade_level": 0,
			"updated_at": 1475242681653,
			"project_id": "57ee6a8c0e8e3d000155557b",
			"remote_region_id": "57ee6ab90e8e3d000155557e",
			"plant_area": 7550.7323856495,
			"onlyVegetation": true,
			"emitter_count": 1,
			"sprinkler_type": 1
		}
	},
====================== REDUCED ====================
	{
		"geometry": {
			"type": "Polygon",
			"coordinates": [
				[
					[
						-118.08689117432,
						33.941054676883
					],
					[
						-118.08689117432,
						33.942358630538
					],
					[
						-118.08632791042,
						33.942358630538
					],
					[
						-118.08632791042,
						33.941054676883
					],
					[
						-118.08689117432,
						33.941054676883
					]
				]
			]
		},
		"type": "Feature",
		"properties": {
			"status": "ACTIVE",
			"plant_center_coordinates": [
				-118.08660070579,
				33.941704113947
			],
			"newly_planted": false,
			"vegetation_type": 0,
			"version": 5,
			"extendAreaRegionType": true,
			"plantFactor": [
				0.61,
				0.64,
				0.75,
				1.04,
				0.95,
				0.88,
				0.94,
				0.86,
				0.74,
				0.75,
				0.69,
				0.6
			],
			"created_at": 1475243178934,
			"shade_level": 0,
			"updated_at": 1475243178934,
			"project_id": "57ee6a8c0e8e3d000155557b",
			"remote_region_id": "57ee6caa0e8e3d0001555584",
			"plant_area": 7550.7323856495,
			"onlyVegetation": true,
			"emitter_count": 1,
			"sprinkler_type": 0
		}
	}
]

The response contains a list of all regions belonging to the project.

POSTMAN request and response example

How to get one specific region

To get one particular region by its id we need to perform an HTTP call to https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions/{regionId} using the GET HTTP method. The value for regionId can be taken from the remote_region_id field in a region’s property.

cURL request example

curl -H'Authorization: Bearer $ACCESS_TOKEN' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ee6a8c0e8e3d000155557b/regions/57ee6caa0e8e3d0001555584'

Response example

{
	"geometry": {
		"type": "Polygon",
		"coordinates": [
			[
				[
					-118.08689117432,
					33.941054676883
				],
				[
					-118.08689117432,
					33.942358630538
				],
				[
					-118.08632791042,
					33.942358630538
				],
				[
					-118.08632791042,
					33.941054676883
				],
				[
					-118.08689117432,
					33.941054676883
				]
			]
		]
	},
	"type": "Feature",
	"properties": {
		"status": "ACTIVE",
		"plant_center_coordinates": [
			-118.08660070579,
			33.941704113947
		],
		"newly_planted": false,
		"vegetation_type": 0,
		"version": 5,
		"extendAreaRegionType": true,
		"plantFactor": [
			0.61,
			0.64,
			0.75,
			1.04,
			0.95,
			0.88,
			0.94,
			0.86,
			0.74,
			0.75,
			0.69,
			0.6
		],
		"created_at": 1475243178934,
		"shade_level": 0,
		"updated_at": 1475243178934,
		"project_id": "57ee6a8c0e8e3d000155557b",
		"remote_region_id": "57ee6caa0e8e3d0001555584",
		"plant_area": 7550.7323856495,
		"onlyVegetation": true,
		"emitter_count": 1,
		"sprinkler_type": 0
	}
}

The response contains everything for the one specific region we asked for.

POSTMAN request and response example

How to update a region

To update a region we’ll need to perform an HTTP call to https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions/{regionId} using the  PUT  HTTP method. The projectId is an ID of the project our region belongs to, and regionId is an ID of the region we want to update. As we’re going to send data to the server, we need to specify what kind of data we’re sending using the Content-Type HTTP header. In our case the content type should be application/json. Make sure to replace $ACCESS_TOKEN with your API access token.

cURL request example

curl -XPUT -H'Authorization: Bearer $ACCESS_TOKEN' -H'Content-Type: application/json' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ee6a8c0e8e3d000155557b/regions/57ee6caa0e8e3d0001555584' -d'{"properties":{"region_name":"Lawn on front yard"}}'

Response example

{
	"geometry": {
		"type": "Polygon",
		"coordinates": [
			[
				[
					-118.08689117432,
					33.941054676883
				],
				[
					-118.08689117432,
					33.942358630538
				],
				[
					-118.08632791042,
					33.942358630538
				],
				[
					-118.08632791042,
					33.941054676883
				],
				[
					-118.08689117432,
					33.941054676883
				]
			]
		]
	},
	"type": "Feature",
	"properties": {
		"status": "ACTIVE",
		"plant_center_coordinates": [
			-118.08660070579,
			33.941704113947
		],
		"areaId": "57f257b2cddc1a54c13bde46",
		"newly_planted": false,
		"vegetation_type": 0,
		"region_name": "Lawn on front yard",
		"parcelExists": true,
		"extendAreaRegionType": true,
		"plantFactor": [
			0.61,
			0.64,
			0.75,
			1.04,
			0.95,
			0.88,
			0.94,
			0.86,
			0.74,
			0.75,
			0.69,
			0.6
		],
		"created_at": 1475243178934,
		"shade_level": 0,
		"parcel_id": "57f257b08b87bc0001f680ae",
		"updated_at": 1475500072048,
		"project_id": "57ee6a8c0e8e3d000155557b",
		"remote_region_id": "57ee6caa0e8e3d0001555584",
		"version": 10,
		"plant_area": 7550.7323856495,
		"onlyVegetation": true,
		"emitter_count": 1,
		"sprinkler_type": 0
	}
}

In this example we updated the name for the region.

POSTMAN request and response example

How to delete a region

To delete a region you need to make an HTTP call to https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions/{regionId}, where projectId is the ID of the project our region belongs to, and regionId is the ID of the region we want to delete. The call should be done using the DELETE HTTP method.

cURL request example

curl -XDELETE -H'Authorization: Bearer ZTA0ZjkzOGJjN2YzMGFkNjIzOWM4YzQ0NjZiMGJiMjM5MDFlZTNjZWQwMjk1YWJhZGNjMTQ1MjNlYTIwMzk4NQ' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ee6a8c0e8e3d000155557b/regions/57ee6caa0e8e3d0001555584'

Response

The response to such a call will be empty but with the HTTP status code 204 (No Content).

POSTMAN request and response example

How to delete all regions in a project

To delete all region in a project you need to make an HTTP call to https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions, where projectId is the ID of the project our regions belongs to; and regionId is the ID of the region we want to delete. The call should be done using the DELETE HTTP method.

cURL request example

curl -XDELETE -H'Authorization: Bearer ZTA0ZjkzOGJjN2YzMGFkNjIzOWM4YzQ0NjZiMGJiMjM5MDFlZTNjZWQwMjk1YWJhZGNjMTQ1MjNlYTIwMzk4NQ' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ee6a8c0e8e3d000155557b/regions'

Response

The response to such a call will be empty but with the HTTP status code 204 (No Content).

POSTMAN request and response example

And just to confirm that everything was deleted we can perform a Get all regions call:

cURL request example

curl -H'Authorization: Bearer $ACCESS_TOKEN' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ee6a8c0e8e3d000155557b/regions'

Response example

[]

POSTMAN request and response example

As you can see all regions were successfully deleted.

For getting started with other APIs see all example code or see the API Specification for details on all available API calls.