farmshots-imagery-api.md

FarmShots Imagery API

Table of contents

• API
  • /imagery/tile
  • /imagery/tile/<x>/<y>/<z>
  • /assets/imagery
• Color Map
• RasterLang
  • expressions

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.
mask	GeoJson	Cut tile to a geometry.
palette	JSONArray	Color map for one layer images.

The following tile is near McCotter. Example request for color imagery:

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

Example request for ndvi

	http://farmshots-imagery.elasticbeanstalk.com/imagery/tile?asset_id=b9efb958-9ccf-402b-bab3-57f28bd86f70&min_map=-1&max_map=.85&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&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1dWlkIjoiM2UxZmJhYTgtNzc0Mi00Njg1LTgzNGUtZTYxM2NiYjBlOGI4IiwiaWF0IjoxNDQ4MTQ1MzU2fQ.lmlXIRtIXeshZIb6ZuLrq7a6hnGgEgnbcELA21zIg5StzXj9dmg802Uls67hpT9FTPPpM1GJfpwczGDhZN2L0EXu9Tc-UiN0MYgMhV0wry_lSZgZdZZbWH68mWQAYL1FtajDaGDdk-CQHzRiAzXZIESvfazqLu92qqFL5URINr8

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

PNG

Returns a 256x256 tile PNG image. this follows the widely-used Google grid where x 0 and y 0 are in the top left of the tile.

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.
mask	GeoJson	Cut tile to a geometry.
palette	JSONArray	Color map for one layer images.
x	int	Upper left index.
y	int	Upper left index.
z	int	Zoom level in the map.

Example

http://jsfiddle.net/ouwen/khqdc3cx/6/

Color Map

Users can specify a color map to map specific values to specific colors. This color map is then provided in the query in the palette parameter. These colors are specified in the form of a JSONArray, with each element in the array being an object that contains 3 values: start, end and color. These parameters define a specific range of values and the color of which that range should be. And example would be:

[{
	start: -1,
  	end: -0.5,
  	color: '#FF0000'
}, {
	start: -0.5,
  	end: 0.2,
  	color: '#0000FF'
}, {
	start: 0.2,
  	end: 0.85,
  	color: '#00FF00'
}]

Note that the max and min values of the colormap need to correspond to the min_map and max_map values provided in the query parameters. Also note that there must be continuity in the definition of color ranges e.g. the start value of the second range in the example is the end value of the first range.

Example Query with color map defined:

http://jsfiddle.net/53anwrgz/3/

'RasterLang'

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

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

There are two main ways that RasterLang works in the API.

Firstly, to manipulate map tiles according to a single formula, the JSONArray should have 1-2 arguments, with the first argument expressing the formula and an optional second argument representing the alpha value. For example, the following expression will calculate ndvi for a landsat8 tile.

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

Secondly, we can designate values to represent Red, Green and Blue channels. To do this, place 3 arguments in the JSONArray and each argument will represent the channel corresponding to the tile's RGB values. For RGB we can add three bands like so

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

An optional 4th argument is also accepted representing the alpha value of the tile.

POST: /assets/imagery

You can issue a POST request with the following fields to get the asset_id of a tile. All parameters are required.

The request must be a valid JSON object with the Content-Type set to application/json. The following fields are required:

Field	Description
source	The source constellation. Either blackbridge or landsat8.
geojson	GeoJSON of AOI. All tiles which intersect will be returned.
start	The start date to return images from.
end	The end date to return images from.

A JSON array is returned with a number of JSON objects that contain the following fields.

Field	Description
asset_id	Catalog ID of the tile.
status	Set to 1 if retrieval is pending, 2 if complete.
cloud_cover	Float in [0, 100] representing cloud cover %.
bounds	geoJSON polygon representing bounds of the image.
acquisition_date	ISO format date on which the image was taken.
source	Constellation from which the image was taken.
download_url	Link to download image if status is 2.

Example

http://jsfiddle.net/y7bzr1pL/5/