Cropper API

Define an area of interest (AOI) within which the data shall be displayed - any image data that does not fall into the AOI shall be made transparent (to use with Image tile).

Create a cropper resource

To create a new cropper resource, send a POST request to the service. The request body must contain the geometry representing AOI in GeoJSON format.

POST /api/render/cropper/
Query Parameters:
 
  • api_key – (required) user’s API key
Response JSON Object:
 
  • cropper_ref (array) – cropper resource to use with Image tile

Example request

http

POST /api/render/cropper/?api_key=XXX HTTP/1.1
Host: gate.eos.com
Content-Type: application/json

{
    "type": "Feature",
    "properties": {},
    "geometry": {
            "type": "Polygon",
            "coordinates": [
                    [
                            [-120.533237, 36.574732],
                            [-120.532808, 36.567357],
                            [-120.524139, 36.567426],
                            [-120.524225, 36.560118],
                            [-120.515385, 36.560187],
                            [-120.51487, 36.553224],
                            [-120.506287, 36.55281],
                            [-120.5056, 36.574595],
                            [-120.533237, 36.574732]
                    ]
            ]
    }
}

curl

curl -i -X POST 'https://gate.eos.com/api/render/cropper/?api_key=XXX' -H 'Content-Type: application/json' --data-raw '{"geometry": {"coordinates": [[[-120.533237, 36.574732], [-120.532808, 36.567357], [-120.524139, 36.567426], [-120.524225, 36.560118], [-120.515385, 36.560187], [-120.51487, 36.553224], [-120.506287, 36.55281], [-120.5056, 36.574595], [-120.533237, 36.574732]]], "type": "Polygon"}, "properties": {}, "type": "Feature"}'

If a resource has been created successfully, the server responds with 200 OK:

HTTP/1.1 200 OK
X-Request-Id: 51b3e178-d328-491b-9559-bc8ccf61846e
Content-Length: 51
Timings: finished-at:10:49:14|finish:0.003
Server: TornadoServer/4.3
Date: Fri, 29 Sep 2017 07:49:14 GMT
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8

{"cropper_ref": "3eb51ea04776e6ae6bb665504e3c5ffb"}

View a geometry behind a cropper

To view a geometry behind a cropper resource, send a GET request to the service containing cropper_ref. The response shall contain the geometry representing AOI in GeoJSON format.

GET /api/render/cropper/(cropper_ref)
Parameters:
  • cropper_ref – cropper resource
Query Parameters:
 
  • api_key – (required) user’s API key

Example request

http

GET /api/render/cropper/3eb51ea04776e6ae6bb665504e3c5ffb?api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/cropper/3eb51ea04776e6ae6bb665504e3c5ffb?api_key=XXX'

If a resource has been found, the server responds with 200 OK:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "type": "Feature",
    "properties": {},
    "geometry": {
            "type": "Polygon",
            "coordinates": [
                    [
                            [-120.533237, 36.574732],
                            [-120.532808, 36.567357],
                            [-120.524139, 36.567426],
                            [-120.524225, 36.560118],
                            [-120.515385, 36.560187],
                            [-120.51487, 36.553224],
                            [-120.506287, 36.55281],
                            [-120.5056, 36.574595],
                            [-120.533237, 36.574732]
                    ]
            ]
    }
}

Example request - Requested cropper_ref does not exist

If a resource was not found, the server responds with 404 Not Found:

http

GET /api/render/cropper/xxxx1111xxxx1111?api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/cropper/xxxx1111xxxx1111?api_key=XXX'
HTTP/1.1 404 Not Found

Usage examples

Rendering raster tiles within an AOI

Assume we have found a raster tile that covers the AOI described in the example above:

http

GET /api/render/S2/10/S/GF/2018/11/8/0/B04,B03,B02/12/676/1600?api_key=XXX HTTP/1.1
Host: gate.eos.com

curl

curl -i 'https://gate.eos.com/api/render/S2/10/S/GF/2018/11/8/0/B04,B03,B02/12/676/1600?api_key=XXX'

Copy the cropper_ref and provide it as a query paramater into a tile request:

http

GET /api/render/S2/10/S/GF/2018/11/8/0/B04,B03,B02/12/676/1600?cropper_ref=3eb51ea04776e6ae6bb665504e3c5ffb&api_key=XXX HTTP/1.1
Host: gate.eos.com
Content-Type: image/png

curl

curl -i 'https://gate.eos.com/api/render/S2/10/S/GF/2018/11/8/0/B04,B03,B02/12/676/1600?cropper_ref=3eb51ea04776e6ae6bb665504e3c5ffb&api_key=XXX' -H 'Content-Type: image/png'

Now image is displayed only within the AOI - rest of the image is transparent.

Tile Tile + cropper
_images/s2_cropper_no_cropper.jpeg _images/s2_cropper.png