Profile

Profile task

The Profile task is used to create profiles along input lines from which a profile graph can be created.

In synchronous mode, the maximum number of input line features that can be accepted by the task for each request is 100.

Request URL

http://elevation.arcgis.com/arcgis/rest/services/Tools/ElevationSync/GPServer/Profile/execute

Description

The output from this task are polyline features with elevation values extracted along the input line features. The elevation values are stored as Z values in the shape geometry. The distance values are stored as M values in the shape geometry.

This task currently works worldwide based on the GEBCO data at 30 arc-second (approximately 1000 meter) resolution, and worldwide between 60 degrees north and 56 degrees south based on the 3 arc-second (approximately 90 meter) resolution SRTM dataset. In North America (Canada, United States, and Mexico), the task uses 1 arc-second (approximately 30 meter) resolution data from the USGS National Elevation Dataset (NED). In the continental United States, the task is also available based on the 1/3 arc-second (approximately 10 meter) resolution USGS National Elevation Dataset (NED). In Australia, the task is available based on the 1 arc-second (approximately 30 meter) resolution SRTM DEM-S dataset from Geoscience Australia. In the remaining parts of the world (Africa, South America, most of Europe and continental Asia, the East Indies, New Zealand, and islands of the western Pacific), the task is available based on the 1 arc-second (approximately 30 meter) resolution SRTM data between 60 degrees north and 56 degrees south.

Please refer to the locator map to see the areas covered and to learn more about the data sources currently available.

Usage

  • The task will return an error message if the specified DEM resolution is not available at any of the input feature locations.

  • The maximum number of input lines is 100 for the synchronous profile task. If additional input lines are provided, the task will return an error and will not execute.

  • When the SamplingDistance parameter is empty or not supplied, a default sampling distance is calculated based on how many vertices are available on the input line feature. If the input line feature contains less than 50 vertices, the default sampling distance is the length of the input line feature divided by 49. If the input has 50 or more, but less than 200 vertices, the default sampling distance is the length of the input line feature divided by 199. If the number of vertices is from 200 to the maximum of 1024, the input line feature will not be densified if the Sampling Distance parameter is empty or not specified.

  • The returned line features are in the same coordinate system as the input line features. The Z and M values of the vertices are in meters.

  • The maximum number of elevation values returned from the task is 2000 for each input line. The task will return an error message and will not execute if a request results in more than this maximum number of elevation values. If this occurs, you should either specify a larger sampling distance, or input a line feature with less vertices, or both.

  • The output field Length Meters holds the planimetric length of the profile line calculated as a geodesic distance and is the correct length regardless of the coordinate system of the data. This length will be different from the shape_length attribute due to the effects of map projection distortion.

  • When submitting the execute request for the synchronous Profile task, returnZ and returnM must be specified as true and included in the request parameters in order to get the Z (elevation) and M (distance) values.

    An example of an execute string with the Z and M enabled is provided in a subsequent section.

Request Parameters

ParameterDescription

InputLineFeatures

(Required)

The line features that will be profiled over the surface.

  • Type: Feature Set

  • Syntax:

    {
    "geometryType":"geometryType",
    "spatialReference":<spatialReference>,
    "fields":<fields>,
    "features":<features>,
    }

ProfileIDField

A unique identifier to tie profiles to their corresponding input line features.

  • Type: String

DEMResolution

The approximate spatial resolution (cell size) of the source elevation data used for the calculation. The default is 90m.

The resolution keyword is an approximation of the spatial resolution of the digital elevation model. While many elevation sources are distributed in units of arc seconds, the keyword is an approximation of those resolutions in meters for easier understanding.

  • Type: String

  • Values: FINEST | 10m | 30m | 90m | 1000m

MaximumSampleDistance

The maximum sampling distance along the line to sample elevation values.

  • Type: Double

MaximumSampleDistanceUnits

The units for the MaximumSampleDistance.

  • Type: String

  • Values: Meters | Kilometers | Feet | Yards | Miles

  • Default: Meters

Complete request example

The profile elevation and distance values are stored as the Z and M values in the result feature set. When submitting the request to execute the synchronous Profile task, returnZ and returnM must be set to true and included in the request parameters.

The following is an example of the complete form of an execute request:

http://elevation.arcgis.com/arcgis/rest/services/Tools/ElevationSync/GPServer/Profile/execute?f=json&InputLineFeatures=<line feature>&ProfileIDField=OID&DEMResolution=FINEST&MaximumSampleDistance=13&MaximumSampleDistanceUnits=Meters&returnZ=true&returnM=true

Response

If the request is successful, the response from the Profile task is a polyline FeatureSet. The number of returned line features is the same as the number of line features in the input. The following example illustrates the returned JSON structure for a successful request:

JSON response syntax for successful request
{
 "results": [{
  "paramName": "OutputProfile",
  "dataType": "GPFeatureRecordSetLayer",
  "value": {
   "displayFieldName": "",
   "geometryType": "esriGeometryPolyline",
   "spatialReference": {
    "wkid": <value>,
    "latestWkid": <value>
   },
   "fields": [
    {
     <field1>
    },
    {
     <field2>
    },
    {
     <additional fields>
    }    
   ],
   "features": [{
    "attributes": {
     "OBJECTID": 1,
     "DEMResolution": <value>,
     "ProfileLength": <value>,
     "Shape_Length": <value>
    },
    "geometry": {"paths": [[
     [
      x,
      y, 
      z,
      m
     ],
     [
      x,
      y,
      z,
      m
     ],
     [
      <additional points>
     ]],
     [
      <additional polylines>
     ]]}
     }],
   "exceededTransferLimit": false
	 }
 }],
 "messages": []
}