About Polygons API

It is an initial API to set up your polygon and get it's ID. Then use the polygon ID in all API calls to satellite imagery, weather, historical NDVI and others and 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 the 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

API call:

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

Method: POST

Headers: Content-Type: application/json

Parameters of the 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 below

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 the 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]
            ]
         ]
      }
   }
}

API response

Response code: 201

Example of the 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 the 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 the 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: GET


Response

Response code: 200

Example of the 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


Response code: 404

Example of the 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 the 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 the API request:
{
   "geo_json":{
      "something":"something"
   },
   "name":"Polygon New Name",
}

Response

Response code: 200

Example of the 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 successful


In case of 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 the 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."
}