Set up polygons


large grey blob in background

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."
}



2012 - 2022 AgroMonitoring © All rights reserved