Polygons API

It is an initial API to set up your polygon and get it's ID. Then use the polygon ID in all APIs to satellite imagery, weather, historical NDVI and others and get data for the specific polygon (see API Documentation). We store your polygons in our system, and you can edit it, add new one, get a list of your polygons with Polygons API.

There are several methods of working with 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 2 simple tools that can help form the right GeoJSON for your field.

1. Very simple coordinate generator VISUAL TOOL. Draw a field with a square or polygon tool and get coordinates in a pop-up window. Copy them into a POST request. (As a background layer, we use the map formed from the freshest and better pictures of Sentinel-2).

2. QUERY BUILDER editor with tools for editing images. You can also draw a field in it and get coordinates by clicking on the Get button. Copy the line with the coordinates in the POST request.


Only for the FREE tariff: 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.

When calling methods PUT and POST it's necessary to specify the header
Content-Type: application/json

Use your API key in each API call.

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 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

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"
}
Parameters of 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


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