Agromonitoring - Polygons API

About Polygons API

This is an initial API to set up your polygon and get its ID. Use the polygon ID in all API calls to get satellite imagery, weather, historical NDVI and others to get data for the specific polygon (see API Documentation).

There are several methods of working with the Polygons API service: polygon creation, adding data, removing a polygon, listing info about one or several polygons. You can also find a list of your polygons on your account page.

We have a simple visual tool that can help to generate GeoJSON for your field. Draw a field with a square or polygon tool and get coordinates in a pop-up window. Copy them into a POST request.

Create a polygon

Request

Example of API Call:

http://api.agromonitoring.com/agro/1.0/polygons?appid=test

Method:

POST

Headers:

Content-Type: application/json

Parameters of API request:

appid

Personal API key

name

The name of your polygon

geo_json

Coordinates specify only in GeoJSON format - [lon, lat].

Coordinates MUST follow the right-hand or left-hand rule with respect to the area it bounds.

You can create the polygon with or without a hole. See the example how to create the polygon with a hole.

There are several limitations:

The type of geometry should be "Polygon"

The polygon can not has self-intersections

Limits of 1 - 3000 ha for the area of your polygon

duplicated

The Polygon API checks and blocks attempt to create polygons duplicates. If you need to create the same polygon, please pass the flag 'duplicated=true' to the query. See the example.

GeoJSON format is used to specify the geometry of the polygon. Please note that the coordinates of the points have the following order - longitude, latitude. You can learn more about this format in the RFC specification.

Body of API Request:

{
   "name":"Polygon Sample",
   "geo_json":{
      "type":"Feature",
      "properties":{

      },
      "geometry":{
         "type":"Polygon",
         "coordinates":[
            [
               [-121.1958,37.6683],
               [-121.1779,37.6687],
               [-121.1773,37.6792],
               [-121.1958,37.6792],
               [-121.1958,37.6683]
            ]
         ]
      }
   }
}

Response

Response Code:

201

Example of API Response:

{
   "id":"5abb9fb82c8897000bde3e87",
   "geo_json":{
      "type":"Feature",
      "properties":{

      },
      "geometry":{
         "type":"Polygon",
         "coordinates":[
            [
               [-121.1958,37.6683],
               [-121.1779,37.6687],
               [-121.1773,37.6792],
               [-121.1958,37.6792],
               [-121.1958,37.6683]
            ]
         ]
      }
   },
   "name":"Polygon Sample",
   "center":[121.1867,37.6739],
   "area":190.6343,
   "user_id":"557066d0ff7a7e3897531d94"
}

Fields in the API response:

id

The internal ID of the polygon you get during creation (string), e.g. id=583d7bbbebb3ff000123f1ce

geo_json

Coordinates your polygon in GeoJSON format.

name

The name of your polygon

center

The central point of the polygon, the average of [lat, lon] over all points (array), e.g. center=[-121.1867,37.6739]

area

Area in hectares (float), e.g. area=190.6343

For the Free plan users: If you created your polygon on a territory that is not marked on the map of the price page, then please wait a few days before the data from the satellite is downloaded for your polygon.

Example of creating duplicate polygons

The Polygon API checks and blocks attempt to create polygons duplicates. If you need to create the same polygon, please pass the flag 'duplicated=true' to the query. See the example below.

API Call:

http://api.agromonitoring.com/agro/1.0/polygons?appid=test&duplicated=true

Method:

POST

Headers:

Content-Type: application/json

Body of API Request:

{
   "name":"Polygon Sample",
   "geo_json":{
      "type":"Feature",
      "properties":{

      },
      "geometry":{
         "type":"Polygon",
         "coordinates":[
            [
               [-121.1958,37.6683],
               [-121.1779,37.6687],
               [-121.1773,37.6792],
               [-121.1958,37.6792],
               [-121.1958,37.6683]
            ]
         ]
      }
   }
}

Example of creating the polygon with a hole

You can create a poligon with a hole. The first element in the array represents the exterior ring. Any subsequent elements represent interior holes.

API Call:

http://api.agromonitoring.com/agro/1.0/polygons?appid=test

Method:

POST

Headers:

Content-Type: application/json

Body of API request with a hole:

{
   "name":"Polygon Sample",
   "geo_json":{
      "type":"Feature",
      "properties":{
      },
      "geometry":{
         "type":"Polygon",
         "coordinates":[
             [
                 [100.0, 0.0],
                 [101.0, 0.0],
                 [101.0, 1.0],
                 [100.0, 1.0],
                 [100.0, 0.0]
             ],
             [
                 [100.8, 0.8],
                 [100.8, 0.2],
                 [100.2, 0.2],
                 [100.2, 0.8],
                 [100.8, 0.8]
             ]
         ]
      }
   }
}

Example of an incorrect API call

The mistake was made in the section "coordinates" of request body. When creating a polygon, the first and last positions are equivalent, and they MUST contain identical values; their representation SHOULD also be identical.

API Call:

http://api.agromonitoring.com/agro/1.0/polygons?appid=test

Method:

POST

Headers:

Content-Type: application/json

Body of an incorrect API request:

{
   "name":"Polygon Sample",
   "geo_json":{
      "type":"Feature",
      "properties":{
      },
      "geometry":{
         "type":"Polygon",
         "coordinates":[
            [
               [-121.1958,37.6683],
               [-121.1779,37.6687],
               [-121.1773,37.6792],
               [-121.1958,37.6792],
               [-121.1958,37.668]
            ]
         ]
      }
   }
}

Response error code:

422

API response:

{
    "message": "Validation of Polygon failed. Summary:
    The following errors were found: Geo json is invalid.
    Invalid coordinates resolution:  Try persisting the 
    document with valid data or remove the validations."
}

Get info for one polygon

Request

API Call:

http://api.agromonitoring.com/agro/1.0/polygons/5abb9fb82c8897000bde3e87?appid=test

Method:

POST

Response

Response Code:

200

Example of API response:

{
   "id":"5abb9fb82c8897000bde3e87",
   "geo_json":{
      "type":"Feature",
      "properties":{

      },
      "geometry":{
         "type":"Polygon",
         "coordinates":[
            [
               [-121.1958,37.6683],
               [-121.1779,37.6687],
               [-121.1773,37.6792],
               [-121.1958,37.6792],
               [-121.1958,37.6683]
            ]
         ]
      }
   },
   "name":"Polygon Sample",
   "center":[-121.1867,37.6739],
   "area":190.6343,
   "user_id":"557066d0ee7b3e3897531d94"
}

Example of an incorrect API call

Wrong id is passed.

Example of incorrect API call:

http://api.agromonitoring.com/agro/1.0/polygons/incorrect?appid=test

Method:

GET

Example of API response:

{
   "message":"\nmessage:\n  Document(s) not found for class 
   Polygon with id(s) incorrect.\nsummary:\n  When calling 
   Polygon.find with an id or array of ids, each parameter 
   must match a document in the database or this error will 
   be raised. The search was for the id(s): incorrect ... 
   (1 total) and the following ids were not found: incorrect.
   \nresolution:\n  Search for an id that is in the database 
   or set the Mongoid.raise_not_found_error configuration option
   to false, which will cause a nil to be returned instead of 
   raising this error when searching for a single id, or only 
   the matched documents when searching for multiples."
}

Get list of polygons

Request

API Call:

http://api.agromonitoring.com/agro/1.0/polygons?appid=test

Method:

GET

Response

Response Code:

200

Example of API response:

[
   {
      "id":"5abb9fb82c8897000bde3e87",
      "geo_json":{
         "type":"Feature",
         "properties":{

         },
         "geometry":{
            "type":"Polygon",
            "coordinates":[
               [
                  [-121.1958,37.6683],
                  [-121.1779,37.6687],
                  [-121.1773, 37.6792],
                  [-121.1958,37.6792],
                  [-121.1958,37.6683]
               ]
            ]
         }
      },
      "name":"Polygon Sample",
      "center":[-121.1867,37.6739],
      "area":190.6343,
      "user_id":"557066d0ee7b3e3897531d94"
   }
]

Update info for polygon

In order to update info for a polygon the id parameter should be used. Currently there is only available to update name parameter, without changing polygon's area.

The geo_json parameter is ignored in the API response.

Request

API Call:

http://api.agromonitoring.com/agro/1.0/polygons/5abb9fb82c8897000bde3e87?appid=test

Method:

PUT

Headers:

Content-Type: application/json

Body of API Request:

{
   "geo_json":{
      "something":"something"
   },
   "name":"Polygon New Name",
}

Response

Response Code:

200

Example of API Response:

{
   "id":"5abb9fb82c8897000bde3e87",
   "geo_json":{
      "type":"Feature",
      "properties":{

      },
      "geometry":{
         "type":"Polygon",
         "coordinates":[
            [
               [-121.1958,37.6683],
               [-121.1779,37.6687],
               [-121.1773,37.6792],
               [-121.1958,37.6792],
               [-121.1958,37.6683]
            ]
         ]
      }
   },
   "name":"Polygon New Name",
   "center":[121.1867, 37.6739],
   "area":190.6343,
   "user_id":"557066d0ff7a7e3897531d94"
}

In case of an incorrect API call:

Wrong id is passed or it is incorrectly typed.

API Call:

http://api.agromonitoring.com/agro/1.0/polygons/incorrect?appid=test

Method:

PUT

Headers:

Content-Type: application/json

Response Code:

404

Example of API Response:

{
   "message":"\nmessage:\n  Document(s) not found for class
   Polygon with id(s) incorrect.\nsummary:\n  When calling 
   Polygon.find with an id or array of ids, each parameter 
   must match a document in the database or this error will 
   be raised. The search was for the id(s): incorrect ... 
   (1 total) and the following ids were not found: incorrect.
   \nresolution:\n  Search for an id that is in the database 
   or set the Mongoid.raise_not_found_error configuration option
   to false, which will cause a nil to be returned instead of 
   raising this error when searching for a single id, or only 
   the matched documents when searching for multiples."
}

Remove a polygon

In order to remove a polygon the id parameter is used.

Request

API Call:

http://api.agromonitoring.com/agro/1.0/polygons/5abb9fb82c8897000bde3e87?appid=test

Method:

DELETE

Response

Response Code:

204 — (means the API call is completed successfully)

In case of an incorrect API call:

Wrong id is passed or it is incorrectly typed.

API Call:

http://api.agromonitoring.com/agro/1.0/polygons/incorrect?appid=test

Method:

DELETE

Response Code:

404

Example of API Response:

{
   "message":"\nmessage:\n  Document(s) not found for class
   Polygon with id(s) incorrect.\nsummary:\n  When calling
   Polygon.find with an id or array of ids, each parameter 
   must match a document in the database or this error will
   be raised. The search was for the id(s): incorrect ... 
   (1 total) and the following ids were not found: incorrect.
   \nresolution:\n  Search for an id that is in the database 
   or set the Mongoid.raise_not_found_error configuration option
   to false, which will cause a nil to be returned instead of 
   raising this error when searching for a single id, or only 
   the matched documents when searching for multiples."
}

`appid`	Personal API key
`name`	The name of your polygon
`geo_json`	Coordinates specify only in GeoJSON format - [lon, lat].

	Coordinates MUST follow the right-hand or left-hand rule with respect to the area it bounds.
	You can create the polygon with or without a hole. See the example how to create the polygon with a hole.
	There are several limitations:

	The type of geometry should be "Polygon"
	The polygon can not has self-intersections
	Limits of 1 - 3000 ha for the area of your polygon

`id`	The internal ID of the polygon you get during creation (string), e.g. id=583d7bbbebb3ff000123f1ce
`geo_json`	Coordinates your polygon in GeoJSON format.
`name`	The name of your polygon
`center`	The central point of the polygon, the average of [lat, lon] over all points (array), e.g. center=[-121.1867,37.6739]
`area`	Area in hectares (float), e.g. area=190.6343

Set up polygons

About Polygons API

This is an initial API to set up your polygon and get its ID. Use the polygon ID in all API calls to get satellite imagery, weather, historical NDVI and others to get data for the specific polygon (see API Documentation).

Create a polygon

Request

Example of API Call:

Method:

Headers:

Parameters of API request:

Body of API Request:

Response

Response Code:

Example of API Response:

Fields in the API response:

Example of creating duplicate polygons

API Call:

Method:

Headers:

Body of API Request:

Example of creating the polygon with a hole

API Call:

Method:

Headers:

Body of API request with a hole:

Example of an incorrect API call

API Call:

Method:

Headers:

Body of an incorrect API request:

Response error code:

API response:

Get info for one polygon

Request

API Call:

Method:

Response

Response Code:

Example of API response:

Example of an incorrect API call

Example of incorrect API call:

Method:

Example of API response:

Get list of polygons

Request

API Call:

Method:

Response

Response Code:

Example of API response:

Update info for polygon

Request

API Call:

Method:

Headers:

Body of API Request:

Response

Response Code:

Example of API Response:

In case of an incorrect API call:

API Call:

Method:

Headers:

Response Code:

Example of API Response:

Remove a polygon

Request

API Call:

Method:

Response

Response Code:

In case of an incorrect API call:

API Call:

Method:

Response Code:

Example of API Response:

Direct links to API Docs

Polygon API

Satellite imagery API

NDVI history for a polygon

Weather data