Farmshots Imagery API.md

FarmShots Imagery API

Table of contents

• [API] (#api)
  • /imagery/tile
  • /imagery/tile/<x>/<y>/<z>
• RasterLang
  • expressions

API

All POST and PUT requests expect a JSONObject with the Content-Type header set to application/json.

Authenticated routes expect the Authorization header to be set to Bearer <token>.

Failure

All routes return a JSONObject with the following fields if an error is encountered.

Field	Type	Description
error	string	A useful diagnostic message.

Example error:

{
	"error": "This is why your request failed."
}

/imagery/tile

PNG

Returns a PNG image depending on the following query params.

Field	Type	Description
asset_id	string	UUID of the resource.
min_map	number	Min pixel map for interpolation.
max_map	number	Max pixele map for interpolation.
ul_lat	number	Upper left corner tile latitude in ESPG:4326.
ul_lon	number	Lower left corner tile longitude in ESPG:4326.
x_dim	number	Image x dimension.
y_dim	number	Image y dimension.
exprs	JSONArray	RasterLang expression to calculate.
lossless	boolean	Image compression.
palette	JSONArray	Array of hex colors for one layer images.

The following tile is near McCotter and has been named b9efb958-9ccf-402b-bab3-57f28bd86f70.tif in the imagery service. Example request for color imagery:

	http://farmshots-imagery.elasticbeanstalk.com/imagery/tile?asset_id=b9efb958-9ccf-402b-bab3-57f28bd86f70&min_map=20&max_map=80&ul_lat=35.52396808079804&ul_lon=-77.29892778906252&lr_lat=35.2597616851088&lr_lon=-77.00891314062502&x_dim=256&y_dim=256&exprs=["b4", "b3", "b2"]&lossless=true

Example request for ndvi

	http://farmshots-imagery.elasticbeanstalk.com/imagery/tile?asset_id=b9efb958-9ccf-402b-bab3-57f28bd86f70&min_map=-1&max_map=1&ul_lat=35.52396808079804&ul_lon=-77.29892778906252&lr_lat=35.2597616851088&lr_lon=-77.00891314062502&x_dim=256&y_dim=256&exprs=["(b4-b5)/(b4%2Bb5)"]&lossless=true

/imagery/tile/<x>/<y>/<z>

PNG

Returns a 256x256 tile PNG image with the top left corner in latitude x and longitutde y in ESPG:4326 projected units.

Field	Type	Description
asset_id	string	UUID of the resource.
min_map	number	Min pixel map for interpolation.
max_map	number	Max pixel map for interpolation.
exprs	JSONArray	RasterLang expression to calculate.
lossless	boolean	Image compression.
palette	JSONArray	Array of hex colors for one layer images.
x	number	Upper left latitude in ESPG:4326.
y	number	Upper left longitude in ESPG:4326.
z	number	Zoom level in the map.

RasterLang

RasterLang is the language to manipulate map tiles. RasterLang JSONArray expressions take a max length of 4.

Map bands are denoted b1, b2, ... , b(n). Depending on the type of imagery there will be more or less bands.

If there is only one element in the array, a one channel image will be returned which can be color mapped.

Example: The following expression will calculate ndvi for a landsat8 tile.

	["(b4-b5)/(b4+b5)"]

If there are three elements in the array, an RGB image will be returned where the first channel is red, second is green, and thrid is blue.

Example: The following expression will calculate rgb for a landsat8 tile.

	["b4", "b3", "b2"]