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 [html]ID: 57ee6a8c0e8e3d000155557b[/html]

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:

[json]
{
	"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
				]
			]
		]
	}
}
[/json]

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 [html]POST[/html] method to [html]https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions[/html], where [html]{projectId}[/html] is an [html]id[/html] of a [html]project[/html] 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 [html]Content-Type[/html] HTTP header. In our case content type should be [html]application/json[/html]. Of course, the string [html]$ACCESS_TOKEN[/html] should be replaced with your access token. Here is the JSON entity to be sent to the Unity API:

Entity to be sent

[json]{
	"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
	}
}
[/json]

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 [html]turf[/html] and irrigation method type [html]spray[/html].

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:

[json]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}}'
[/json]

Response example

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

[json]{
	"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,
	}
}
[/json]

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 [html]https://developer-api.etwater.com/api/v1/gardening/projects/57ee6a8c0e8e3d000155557b/regions[/html] using the [html]PATCH[/html] 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 [html]remote_region_id[/html].

cURL request example

[json]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}}]'
[/json]

Response example

[json]
[
	{
		"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
		}
	}
]
[/json]

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 [html]https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions[/html] using the [html]GET[/html] HTTP method.

cURL request example

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

Response example

[json]
[
	{
		"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
		}
	}
]
[/json]

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 [html]id[/html] we need to perform an HTTP call to [html]https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions/{regionId}[/html] using the [html]GET[/html] HTTP method. The value for [html]regionId[/html] can be taken from the [html]remote_region_id[/html] field in a region’s property.

cURL request example

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

Response example

[json]
{
	"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
	}
}
[/json]

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 [html]https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions/{regionId}[/html] using the  [html]PUT[/html]  HTTP method. The [html]projectId[/html] is an ID of the project our region belongs to, and [html]regionId[/html] 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 [html]Content-Type[/html] HTTP header. In our case the content type should be [html]application/json[/html]. Make sure to replace [html]$ACCESS_TOKEN[/html] with your API access token.

cURL request example

[json]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"}}'
[/json]

Response example

[json]
{
	"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
	}
}
[/json]

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 [html]https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions/{regionId}[/html], where [html]projectId[/html] is the ID of the project our region belongs to, and [html]regionId[/html] is the ID of the region we want to delete. The call should be done using the [html]DELETE[/html] HTTP method.

cURL request example

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

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 [html]https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}/regions[/html], where [html]projectId[/html] is the ID of the project our regions belongs to; and [html]regionId[/html] is the ID of the region we want to delete. The call should be done using the [html]DELETE[/html] HTTP method.

cURL request example

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

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 [html]Get all regions[/html] call:

cURL request example

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

Response example

[json]
[]
[/json]

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.

 
©2016 ETwater. All rights reserved. Privacy Information. SMART OUTDOORS® and WELCOME TO THE SMART OUTDOORS® are registered trademarks of ET Water Systems, Inc.