-
Notifications
You must be signed in to change notification settings - Fork 64
Web Services REST API
The REST endpoints documented here are shown with their relative paths. In many cases, the MrGeo REST services will be deployed to a web server with the "/mrgeo" context, so the context URL for accessing REST endpoints would start with something like the following:
http://myserver:8080/mrgeo
If you run the stand-alone web server included in MrGeo from the command line, the URL will be:
http://localhost:8080/mrgeo
Append the relative endpoint for the request you wish to make (documented below) to the appropriate context URL above. Keep in mind that the port and context are specific to how MrGeo is deployed to your web server. If you are using the stand-alone web server from the MrGeo command line, you can control the port number on which it listens, and the default is 8080. To start the stand-alone web server, go to a command prompt and execute the following:
export MRGEO_HOME=<absolute path to MrGeo install directory>
cd $MRGEO_HOME
bin/mrgeo webserver
Quick Links
- Raster Endpoints
- Job Endpoints
- Web Map Service Endpoints
- Tile Map Service Endpoints
- Miscellaneous Endpoints
Consumes text/plain
Produces application/json
| Parameter Name | Required | Description |
|---|---|---|
| {image-name} | Yes | The name to assign to the MrGeo image being created. Use alphanumeric, dash, underscore only. |
| Parameter Name | Required | Description |
|---|---|---|
| protectionLevel | No | Sets the protection level of the output image. |
Use this endpoint to create a new MrGeo image by executing map algebra script. The request content should be set to the map algebra script to execute. After this job completes successfully, you can refer to the output image in future map algebra scripts by including the name you assigned to it in square brackets. For example, if your URL looks like "http://localhost:8080/mrgeo/raster/My-Raster/mapalgebra", then after this map algebra completes successfully, you can refer to that output image in a future map algebra script by using "[My-Raster]".
This endpoint submits a job to the server to execute the map algebra and returns JSON containing information about that job. The caller can then use the job endpoints to monitor progress and determine when the job completes or fails. If a protectionLevel parameter is provided, that value will be assigned to the output image's protection level.
{
"type":null,
"jobId":1,
"statusUrl":"http://localhost:8080/mrgeo/job/1",
"jobState":
{
"percent":0.0,
"message":null,
"jobFinished":false,
"startTime":1431948964068,
"duration":0,"state":"Pending"
},
"name":"MapAlgebra job My-Raster",
"buildPyramid":
{
"percent":0.0,
"message":null,
"startTime":null,
"taskFinished":false,
"duration":0,
"state":null
}
}
The most important pieces of information in the returned JSON are the jobId and statusUrl which can be used to get the ongoing progress of the job itself. Refer to the job REST endpoints for more information. The other fields contain information that is returned from the job endpoints.
Produces image/*
| Parameter Name | Required | Description |
|---|---|---|
| {image-name} | Yes | The name of the MrGeo image being requested. |
| Parameter Name | Required | Description |
|---|---|---|
| format | no | Specify png, jpg, tif, geotif, or kml. Defaults to png |
| bbox | no | Provide the bounding box in the requested SRS using comma-separated values minX,minY,maxX,maxY. Default value is the entire world. |
| width | no | The width of the image to return in pixels. Default is 600. |
| height | no | The height of the image to return in pixels. Default is 400 |
| color-scale-name | no | The name of the color scale to apply to the image. This can be set to any of the style names returned from the WMS GetCapabilities request. |
| min | no | The minimum value of the color scale range. Defaults to 0.0. Applies when the specified color scale uses Min/Max scaling. |
| max | no | The maximum value of the color scale range. Defaults to 10.0. Applies when the specified color scale uses Min/Max scaling. |
| srs | no | The SRS to use for the output image. The image will be resampled when the SRS parameter is used if the SRS is not EPSG:4326. By default it is EPSG:4326. |
| zoom-level | no | The zoom level of the MrGeo image from which to generate the output image. If not specified, it uses the max zoom level for that image. This is only used for the kml output image type. |
The HTTP response contains the requested MrGeo image in the specified format based on the query parameters in the HTTP request. When tif/tiff or geotif/geotiff formats are requested, the resulting image contains the raw pixel values from the MrGeo image rather than color scaled pixel values.
Produces application/json
| Parameter Name | Required | Description |
|---|---|---|
| pagesize | no | Defines the number of jobs to return for each page. Default value is 20. |
| start | no | Specifies the index of the first job to display. Defaults to 1 to show the first page. |
Returns JSON containing job status information for one page of jobs. The caller controls the page size using the "pagesize" request parameter.
The response JSON looks like:
{
"nextURL": "http://localhost:8080/mrgeo/job?pagesize=1&start=3",
"jobInfo": [
{
"type": null,
"jobId": 1,
"statusUrl": "http://localhost:8080/mrgeo/job/1",
"jobState": {
"jobFinished": true,
"startTime": 1431965590281,
"percent": 100,
"message": null,
"duration": 16225,
"state": "Complete"
},
"name": "MapAlgebra job My-Raster",
"buildPyramid": {
"taskFinished": true,
"startTime": 1431965606506,
"percent": 100,
"message": null,
"duration": 18164,
"state": "Complete"
}
},
{
"type": null,
"jobId": 2,
"statusUrl": "http://localhost:8080/mrgeo/job/2",
"jobState": {
"jobFinished": true,
"startTime": 1431965614082,
"percent": 100,
"message": null,
"duration": 14251,
"state": "Complete"
},
"name": "MapAlgebra job My-Raster",
"buildPyramid": {
"taskFinished": true,
"startTime": 1431965628333,
"percent": 100,
"message": null,
"duration": 16126,
"state": "Complete"
}
}
],
"prevURL": null
}
Note that the response includes the nextURL property whose value is the URL for the next page of job results. If there are no more pages, the nextURL property will be null. The jobInfo property is an array of job detail objects. The format of each job detail object is described under the endpoint for requesting job details for a single job.
Produces application/json
| Parameter Name | Required | Description |
|---|---|---|
| {job-id} | Yes | The integer job id for which status is being requested. |
None
Returns JSON containing job status information for the {job-id} specified in the endpoint path.
The response JSON looks like:
{
"name": "MapAlgebra job My-Raster",
"type": null,
"jobId": 1,
"statusUrl": "http://localhost:8080/mrgeo/job/1",
"jobState": {
"message": null,
"jobFinished": false,
"startTime": 1432030425082,
"percent": 40.634922,
"state": "Running",
"duration": 0
},
"buildPyramid": {
"message": null,
"startTime": null,
"taskFinished": false,
"percent": 0,
"state": null,
"duration": 0
}
}
- The "name" property is a human readable job name.
- The "type" property is currently not used
- The "jobId" is the id of the job
- The "statusURL" is the URL to use for getting the job's status. In this case, it is the same as the URL used for the request. This JSON output format is also used by the endpoint that lists all of the jobs, so it is more useful in that case.
- the "jobState" property is an object containing properties describing the state of the actual map algebra processing.
- the "message" property will show any error messages returned while executing the map algebra or null if there are no messages.
- the "jobFinished" property will be true or false. When true, you must also check the "state" field to determine if it was successful for failed.
- the "startTime" property contains the Unix time at which the map algebra began execution. This is the number of seconds since Jan 1, 1970.
- the "percent" property contains the completion percentage of the map algebra.
- the "state" property contains one of "Complete", "Failed", "Pending", "Running" or "Cancelled".
- the "duration" property contains the number of seconds that the map algebra has been executing so far or the total execution time in seconds if jobFinished is true.
- the "buildPyramid" property is an object containing properties describing the state of the build pyramid action. When map algebra is submitted for execution via the "/raster" endpoint, it consists of two actions - first, running the actual map algebra, and then building a pyramid for the resulting image so that it can accessed and visualized at different zoom levels. The full job is not done until both the map algebra and build pyramid are finished.
- the "message" property will show any error messages returned while executing the build pyramid or null if there are no messages.
- the "taskFinished" property will be true or false. When true, you must also check the "state" field to determine if it was successful for failed.
- the "startTime" property contains the Unix time at which the build pyramid began execution. This is the number of seconds since Jan 1, 1970.
- the "percent" property contains the completion percentage of the build pyramid.
- the "state" property contains one of "Complete", "Failed", "Pending", "Running" or "Cancelled".
- the "duration" property contains the number of seconds that the build pyramid has been executing so far or the total execution time in seconds if taskFinished is true.
MrGeo implements a portion of the standard OGC Web Map Service (WMS) plus a couple of extensions useful for MrGeo. This section will describe the portions of the WMS implemented within MrGeo. Refer to the OGC documentation at http://www.opengeospatial.org/standards/wms.
There is a single endpoint for WMS requests, however the REQUEST query parameter supports multiple options that produce different types of responses, so those are documented individually in the following sub-sections. For all requests, the SERVICE query parameter must be set to "SERVICE" as shown in each of the endpoint URL's.
Produces application/xml
| Parameter Name | Required | Description |
|---|---|---|
| version | no | The OGC WMS version to use for GetCapabilities. Defaults to 1.1.0 |
This endpoint returns the capabilities of the WMS, including all of the layers available (each MrGeo image is a WMS layer), and the styles available. The returned styles are the color scale names available in the HDFS path /mrgeo/color-scales.
The FORMAT parameter that is part of the standard WMS GetCapabilities request is ignored. MrGeo always returns XML format.
Produces image/* (depends on the FORMAT query parameter)
| Parameter Name | Required | Description |
|---|---|---|
| layers | yes | The name of the MrGeo image being requested. Typically in a WMS, this parameter allows multiple layer names separated by commas, but MrGeo only supports one. |
| styles | no | The name of the style to use when rendering the image. The available styles are returned from the GetCapabilities WMS request. |
| srs or crs | no | The SRS/CRS to apply to the specified BBOX. The returned image is projected to this srs/crs. Defaults to EPSG:4326 (WGS-84). |
| BBOX | yes | The bounds of the source image to use for creating the output image. Must be specified in the same srs/crs as the srs/crs query parameter. |
| FORMAT | yes | The image format to be returned (one of jpeg, png, tiff or geotiff). The Content-Type header of the response is set to the corresponding value (e.g. image/png, image/jpeg, etc...) |
| WIDTH | yes | The width in pixels of the returned image. If the value is too large, an error may result. |
| HEIGHT | yes | The height in pixels of the returned image. If the value is too large, an error may result. |
Returns an image scaled based on the srs/crs, bbox and width/height parameter values passed in. The image coloring is determined by the style request parameter. If the requested format is tiff or geotiff, no style is applied - the raw pixels values are returned in the image.
The image bytes are stored in the response content.
Produces application/xml
Only applicable to version 1.4.0 requests. Returns tiling information about all available MrGeo images. It does not yet support the "layers" query parameter that is part of the spec for describing tiles for specific images. Refer to the OGC documentation for WMS 1.4.0 for information about the response from this request.
Produces image/* (depends on the FORMAT query parameter)
| Parameter Name | Required | Description |
|---|---|---|
| LAYER | yes | The name of the MrGeo image being requested. |
| STYLE | no | The name of the style to use when rendering the image. The default style is a grayscale gradient. |
| FORMAT | yes | The image format to be returned (one of jpeg, png, tiff or geotiff). The Content-Type header of the response is set to the corresponding value (e.g. image/png, image/jpeg, etc...) |
| SCALE | yes | The resolution of each pixel in the output image. |
| TILEROW | yes | The row number of the tile being requested. This value must be within the range returned for this image from the DescribeTiles request. |
| TILECOL | yes | The column number of the tile being requested. This value must be within the range returned for this image from the DescribeTiles request. |
Returns the requested tile for the requested image. If the requested format is tiff or geotiff, the returned image pixels will contain the raw pixel values. For other formats, the returned image will be colorized based on the style request parameter. The CRS request parameter that is part of the OGC standard is ignored. Output images are always CRS-84.
The tile image bytes are stored in the response content.
Returns XML describing basic information about the MrGeo TMS.
Produces text/xml response content that looks like:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Services>
<TileMapService href="http://localhost:8080/mrgeo/tms/1.0.0" title="MrGeo Tile Map Service" version="1.0.0"/>
</Services>
Produces image/*
| Parameter Name | Required | Description |
|---|---|---|
| image-name | yes | The name of the MrGeo image for which to return a tile. |
| z | yes | The zoom level of the tile to be returned. If the zoom level does not exist for the image, and error is returned. |
| x | yes | The desired tile's x coordinate within the specified zoom level. Tile x coordinates are numbered beginning with 0 from left to right. |
| y | yes | The desired tile's y coordinate within the specified zoom level. Tile y coordinates are numbered beginning with 0 from bottom to top. |
| FORMAT | yes | The image format to be returned (one of jpeg, png, tiff or geotiff). The Content-Type header of the response is set to the corresponding value (e.g. image/png, image/jpeg, etc...) |
| Parameter Name | Required | Description |
|---|---|---|
| color-scale-name | no | The name of the color scale to apply to the output image. This is not used if the format is tiff or geotiff or if the MrGeo image has either 3 bands or 4 bands. This can be set to any of the style names returned from the WMS GetCapabilities request. |
| min | no | The minimum value to use for the MinMax range of the color scale. |
| max | no | The maximum value to use for the MinMax range of the color scale. |
| maskMax | no | The maximum pixel value from the mask image for which to allow source pixel data to be copied. |
| mask | no | The name of a MrGeo image to use as a mask. |
Returns an image of the specific tile requested. The image is colorized based on the color-scale parameter unless the format is tiff or geotiff in which case raw pixel data is copied to the output image. When a mask image is used, for each band in the mask, if the mask pixel value is NoData or the mask pixel value > maskMax, then the source pixel data for each source band will be set to the source NoData value for that band. Otherwise, it will copy the source pixel to the output (subject to colorizing with the color-scale afterward).
Writes the image bytes to the response content in the requested format.
Produces application/xml
None
Returns XML with information about the MrGeo system.
The returned XML contains elements for the MrGeo configuration settings from mrgeo.conf (which resides in $MRGEO_HOME/conf). The response also contains XML elements for each of the map algebra functions available in the system.
A sample response looks like:
<About name="mrgeo-services" version="" imagebase="/mrgeo/images" user="*unknown*">
<Properties>
<Property name="use.kryo.serialization" value="false" />
<Property name="kml.base" value="/mrgeo/kml" />
<Property name="db.path" value="/tmp/mrgeo-services-db" />
<Property name="org.mrgeo.resources.WmsGenerator.permits" value="9999" />
<Property name="legion.processortype.preference" value="GPU" />
<Property name="distributed.base" value="/mrgeo/jars" />
<Property name="base.url" value="http://localhost:8080/mrgeo/" />
<Property name="mrsimage.tilesize" value="512" />
<Property name="cluster" value="yarn" />
<Property name="image.base" value="/mrgeo/images" />
<Property name="colorscale.base" value="/mrgeo/color-scales" />
<Property name="tsv.base" value="/mrgeo/tsv" />
<Property name="vector.base" value="/mrgeo/vectors" />
</Properties>
<MapAlgebra>
<Operation name="!" />
<Operation name="!=" />
<Operation name="&" />
<Operation name="&&" />
<Operation name="*" />
<Operation name="+" />
<Operation name="-" />
<Operation name="/" />
<Operation name="<" />
<Operation name="<=" />
<Operation name="<>" />
<Operation name="==" />
<Operation name=">" />
<Operation name=">=" />
<Operation name="BuildPyramid" />
<Operation name="CostDistance" />
<Operation name="FilterByColumn" />
<Operation name="InlineCsv" />
<Operation name="LeastCostPath" />
<Operation name="RandomSample" />
<Operation name="RandomizeVector" />
<Operation name="RasterizeVector" />
<Operation name="RenderedImage" />
<Operation name="Resource" />
<Operation name="SplitVector" />
<Operation name="UMinus" />
<Operation name="VectorBuffer" />
<Operation name="VectorReader" />
<Operation name="VectorizeRaster" />
<Operation name="^=" />
<Operation name="abs" />
<Operation name="and" />
<Operation name="aspect" />
<Operation name="boundary" />
<Operation name="changeClassification" />
<Operation name="con" />
<Operation name="convexhull" />
<Operation name="cos" />
<Operation name="crop" />
<Operation name="eq" />
<Operation name="fill" />
<Operation name="ge" />
<Operation name="gt" />
<Operation name="gte" />
<Operation name="isNull" />
<Operation name="le" />
<Operation name="log" />
<Operation name="lt" />
<Operation name="lte" />
<Operation name="mosaic" />
<Operation name="ne" />
<Operation name="or" />
<Operation name="pgQuery" />
<Operation name="pow" />
<Operation name="sin" />
<Operation name="slope" />
<Operation name="tan" />
<Operation name="xor" />
<Operation name="|" />
<Operation name="||" />
</MapAlgebra>
</About>
Produces application/json
None
Returns JSON with MrGeo version information.
A sample response looks like:
{
"name": "mrgeo-services",
"version": "0.5.0-cdh4.7.0-mr1-SNAPSHOT",
"revision": "",
"build": "",
"buildTime": "20150519-0547",
"packaging": "No packaging information"
}