Calculate Motion Statistics

URL:
https://<geoanalytics-url>/CalculateMotionStatistics
Methods:
GET
Version Introduced:
10.9

Description

Calculate Motion Statistics

The Calculate Motion Statistics task calculates motion statistics and descriptors for time-enabled points that represent one or more moving entities. Points are grouped together into tracks representing each entity using a unique identifier. Motion statistics are calculated at each point using one or more points in the track history. Calculations include summaries of distance traveled, duration, elevation, speed, acceleration, bearing, and idle status. The result is a new point layer enriched with the requested statistics.

For example, a city is monitoring snowplow operations and wants to better understand vehicle movement. The Calculate Motion Statistics tool can be used to determine idle locations and time spent idling, average and maximum speeds over time, total distance covered, and other statistics.

Request parameters

ParameterDetails

inputLayer (Required)

The time-enabled point features that will be grouped into tracks and analyzed. The input layer must be of time type instant.

Syntax: As described in Feature input, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A URL to a big data catalog service layer with an optional filter to select specific features
  • A feature collection

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
{"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}
//REST scripting example
"inputLayer": {"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

trackFields (Required)

The fields used to identify distinct tracks. There can be multiple trackFields.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
BoatName,ConvoyID
//REST scripting example
"trackFields": "BoatName,ConvoyID"

trackHistoryWindow (Optional)

The number of observations (including the current observation) that will be used when calculating summary statistics that are not instantaneous. This includes minimum, maximum, average, and total statistics. The default track history window is 3, which means that at each point in a track summary, statistics will be calculated using the current observation and the previous two observations. This parameter does not affect instantaneous statistics or idle classification.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
5
//REST scripting example
"trackHistoryWindow": 3

motionStatistics (Optional)

Specifies the statistic groups that will be calculated. See the table below for a description of the statistics included with each group. By default, all statistic groups will be calculated. Optionally, specify one or more groups of statistics to be calculated. The group options are as follows:

  • Distance
  • Speed
  • Acceleration
  • Duration
  • Elevation
  • Slope
  • Idle
  • Bearing

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
Speed,Elevation,Slope
//REST scripting example
"motionStatistics": "Duration,Distance"

idleDistanceTolerance (Required if Idle is specified)

Used along with idleTimeTolerance to decide if an entity is idling. An entity is idling when it hasn't moved more than this distance in at least the amount of time specified by idleTimeTolerance. The units of the time values are supplied by the idleDistanceToleranceUnit parameter. This value is only used for statistics in the Idle group.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
5.5
//REST scripting example
"idleDistanceTolerance": 5.5

idleDistanceToleranceUnit (Required if idleDistanceTolerance is specified)

The unit of the idleDistanceTolerance.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
Kilometers
//REST scripting example
"idleDistanceToleranceUnit": "Kilometers"

idleTimeTolerance (Required if Idle is specified)

Used along with idleDistanceTolerance to decide if an entity is idling. An entity is idling when it hasn't moved more than the idleDistanceTolerance in at least the amount of time specified. The units of the time values are supplied by the idleTimeToleranceUnit parameter. This value is only used for statistics in the Idle group.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
7
//REST scripting example
"idleTimeTolerance": 12

idleTimeToleranceUnit (Required if idleTimeTolerance is specified)

The unit of the idleTimeTolerance.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
Days
//REST scripting example
"idleTimeToleranceUnit": "Hours"

timeBoundarySplit (Optional)

A time boundary allows you to analyze values within a defined time span. For example, if you use a time boundary of 1 day, starting on January 1, 1980, tracks will be analyzed one day at a time.

The timeBoundarySplit parameter defines the scale of the time boundary. In the case above, this would be 1. See the portal documentation for this tool to learn more.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
1
//REST scripting example
"timeBoundarySplit": 2

timeBoundarySplitUnit (Required if timeBoundarySplit is specified)

The unit applied to the time boundary. timeBoundarySplitUnit is required if a timeBoundarySplit is provided.

Values: Milliseconds | Seconds | Minutes | Hours | Days | Weeks | Months | Years

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
Weeks
//REST scripting example
"timeBoundarySplitUnit": "Days"

timeBoundaryReference (Optional)

A date that specifies the reference time to align the time boundary to, represented in milliseconds from epoch. The default is January 1, 1970, at 12:00 a.m. (epoch time stamp 0). This option is only available if the timeBoundarySplit and timeBoundarySplitUnit are set.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
9466835800000
//REST scripting example
"timeBoundaryReference": 946684800000

distanceMethod (Optional)

The method used to calculate distances between track observations. There are two methods to choose from: Planar and Geodesic. The Planar method measures distances using a Euclidean plane and will not calculate statistics across the date line. When the Geodesic method is used to calculate distance and the spatial reference can be panned, calculations will cross the date line when appropriate. If the spatial reference cannot be panned, calculations will be limited to the coordinate system extent and may not wrap. Geodesic is the default.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
Geodesic
//REST scripting example
"distanceMethod": "Planar"

distanceUnit (Optional)

The units for all results in the Distance motion statistics group.

Values: Meters | Kilometers | Feet | FeetInt | FeetUS | Miles |MilesInt | MilesUS | NauticalMiles | NauticalMilesInt | NauticalMilesUS | Yards | YardsInt | YardsUS

The default is Meters .

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
Feet
//REST scripting example
"distanceUnit": "Kilometers"

durationUnit (Optional)

The units for all results in the Duration motion statistics group.

Values: Milliseconds | Seconds | Minutes | Hours | Days | Weeks | Months | Years

The default is Seconds.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
Feet
//REST scripting example
"durationUnit": "Kilometers"

speedUnit (Optional)

The units for all results in the Speed motion statistics group. Values: MetersPerSecond | KilometersPerHour | FeetPerSecond | MilesPerHour | NauticalMilesPerHour The default is MetersPerSecond.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
KilometersPerHour
//REST scripting example
"distanceUnit": "KilometersPerHour"

accelerationUnit (Optional)

The units for all results in the Acceleration motion statistics group. Values: MetersPerSecondSquared | FeetPerSecondSquared The default is MetersPerSecondSquared.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
Meters per second squared
//REST scripting example
"accelerationUnit": "MetersPerSecondSquared"

elevationUnit (Optional)

The units for all results in the Elevation motion statistics group. Values: Meters | Kilometers | Feet | FeetInt | FeetUS | Miles | MilesInt | MilesUS | Yards | YardsInt | YardsUS

The default is Meters .

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
Feet
//REST scripting example
"elevationUnit": "Kilometers"

outputName (Required)

The task will create a feature service of the results. You define the name of the service.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
//REST web example
myOutput
//REST scripting example
"outputName": "myOutput"

context (Optional)

The context parameter contains additional settings that affect task execution. For this task, there are four settings:

  • Extent (extent )—A bounding box that defines the analysis area. Only those features that intersect the bounding box will be analyzed.
  • Processing spatial reference (processSR )—The features will be projected into this coordinate system for analysis.
  • Output spatial reference (outSR )—The features will be projected into this coordinate system after the analysis to be saved. The output spatial reference for the spatiotemporal big data store is always WGS84.
  • Data store (dataStore )—Results will be saved to the specified data store. The default is the spatiotemporal big data store.

Syntax:

Use dark colors for code blocksCopy
1
2
3
4
5
6
{
  "extent": {extent},
  "processSR": {spatial reference},
  "outSR": {spatial reference},
  "dataStore": {data store}
}

f

The response format. The default response format is html .

Values: html | json | pjson

motionStatistics calculation groups

The tables below describe the statistics that will be calculated for each motion statistic group specified. Each statistic will be added as a new field to the point layer.

  • Distance
StatisticDescription

Distance

Distance traveled from the previous observation to the current observation.

TotDistance

Sum of distances traveled between observations in the track history window.

MinDistance

Minimum of distances traveled between observations in the track history window.

MaxDistance

Maximum of distances traveled between observations in the track history window.

AvgDistance

Average of distances traveled between observations in the track history window.

  • Speed
StatisticDescription

Speed

Speed of travel from the previous observation to the current observation.

MinSpeed

Minimum speed between observations in the track history window.

MaxSpeed

Maximum speed between observations in the track history window.

AvgSpeed

The sum of distances between observations in the track history window divided by the sum of durations between observations in the track history window.

  • Acceleration
StatisticDescription

Acceleration

The difference between the current speed and previous speed divided by the current duration.

MinAcceleration

Minimum acceleration calculated in the track history window.

MaxAcceleration

Maximum acceleration calculated in the track history window.

  • Duration
StatisticDescription

Duration

The elapsed time since the previous observation.

TotDuration

Sum of durations in the track history window.

MinDuration

Minimum duration in the track history window.

MaxDuration

Maximum duration in the track history window.

AvgDuration

Sum of durations in the track history window divided by the number of durations in the window.

  • Elevation
StatisticDescription

Elevation

Current elevation of the observation.

ElevChange

Difference between the current elevation and the previous elevation.

TotElevChange

Sum of elevation changes between points in the track history window. This can be a negative value.

MinElevation

Minimum elevation in the track history window.

MaxElevation

Maximum elevation in the track history window.

AvgElevation

Sum of elevations in the track history window divided by the size of the track history window.

  • Slope
StatisticDescription

Slope

Ratio of elevation change to distance between the current and previous observations.

MinSlope

Minimum slope in the track history window.

MaxSlope

Maximum slope in the track history window.

AvgSlope

Sum of slopes in the track history window divided by the number of slopes in the window.

  • Idle
StatisticDescription

Idling

True if the distance between the current observation and the previous is less than idleDistanceTolerance, and the duration between the current observation and the previous is greater than idleTimeTolerance. False if one or both of those conditions are not met.

TotIdleTime

Sum of durations in the track history window that meet idling criteria.

PctIdleTime

Percentage of time for which idling was detected.

  • Bearing
StatisticDescription

Bearing

Angle of travel from the previous observation to the current observation.

Example usage

Below is a sample request URL for CalculateMotionStatistics:

Use dark colors for code blocksCopy
1
https://webadaptor.domain.com/server/rest/services/System/GeoAnalyticsTools/GPServer/CalculateMotionStatistics/submitJob?inputLayer={"url":"https://webadaptor.domain.com/server/rest/services/Hurricane/hurricaneTrack/0"}&trackFields=Hurricane Name&trackHistoryWindow=10&motionStatistics=Duration,Slope&idleDistanceTolerance=10&idleDistanceToleranceUnit=Minutes&idleTimeTolerance=1&idleTimeToleranceUnit=Hours&timeBoundarySplit=6&timeBoundarySplitUnit=Hours&timeBoundaryReference=9466835800000&method=geodesic&outputName=myOutput&context={"extent":{"xmin":-122.68,"ymin":45.53,"xmax":-122.45,"ymax":45.6,"spatialReference":{"wkid":4326}}}&f=json

Response

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

Syntax:

Use dark colors for code blocksCopy
1
2
3
4
{
  "jobId": "<unique job identifier>",
  "jobStatus": "<job status>"
}

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

Use dark colors for code blocksCopy
1
https://<analysis url>/CalculateMotionStatistics/jobs/<jobId>

Access 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:

Use dark colors for code blocksCopy
1
https://<analysis-url>/CalculateMotionStatistics/jobs/<jobId>/results/output?token=<your token>&f=json
ResponseDescription

output

The output layer will contain input point features with additional fields for all statistics included with the motionStatistics groups specified.

Use dark colors for code blocksCopy
1
{"url": "https://<analysis-url>/CalculateMotionStatistics/jobs/<jobId>/results/output"}

The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter provided in the initial request. The value contains the URL of the feature service layer.

Use dark colors for code blocksCopy
1
2
3
4
5
{
  "paramName": "output",
  "dataType": "GPRecordSet",
  "value":{"url": "<hosted featureservice layer url>"}
}

See Feature output for more information about how the result layer is accessed.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.