Profile

Profile task

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

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

Request URL

http://elevation.arcgis.com/arcgis/rest/services/Tools/Elevation/GPServer/Profile/submitJob

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 1000 for the asynchronous 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 accessing the result of the asynchronous Profile task, to get the Z (elevation) and M (distance) values in the result, returnZ and returnM must be specified as true and included in the request parameters.

  • Using this task consumes credits. The rate of use is 1 credit per 1000 input features.

    For more information, see the Service Credits Overview.

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

Response

When you submit a request, the task assigns a unique job ID for the transaction.

Syntax:

{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}

After the initial request is submitted you can use the jobId to periodically check the status of the job and messages as described in the topic Checking job status for Elevation services. Once the job has successfully completed, use the jobId to retrieve the results. To track the status, you can make a request of the following form:

http://elevation.arcgis.com/arcgis/rest/services/Tools/Elevation/GPServer/Profile/jobs/<jobId>

Accessing results

When the status of the job request is esriJobSucceeded, you can access the results of the analysis by making a request of the following form:

http://elevation.arcgis.com/arcgis/rest/services/Tools/Elevation/GPServer/Profile/jobs/<jobId>/results/OutputProfile?token=<your token>&returnZ=true&returnM=true&f=json

The elevation values and distance values are stored as Z and M values in the result feature set. To get the Z and M values back, returnZ and returnM must be set to true and included in the request parameters.

ParameterDescription

OutputProfile

(Derived)

The output profile polyline features, which is a derived output.

  • Type: Feature set