Snap Tracks

Track

A sequence of features that are time-enabled with time type instant. Features are determined to be in sequence using a track identifier field and their order in time. For example, a city could have a fleet of snow plow trucks that record their location every 30 seconds. The vehicle ID could represent the distinct tracks.

Observation

A point in a track.

Node

The end vertices of polyline features used to indicate the direction of the polyline. The start of the polyline is the from node and the end of the polyline is the to node.

Direction

The direction of a polyline. Direction refers to how a polyline can be travelled between the from node and to node.

Connectivity

Connectivity describes how polylines are connected to represent a traversable network. Polylines are connected based on their from node and to node values. Polylines that cannot be reached by a point, based on connectivity, will not be considered a match.

Traversable

Polylines are traversable if they are connected by common nodes. For example, if the from node of polyline A is the same as the to node for polyline B, they are traversable.

pointLayer (Required)

The track point features that will be matched to polylines.

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

1
2
3
4
//REST web example
pointLayer={"url": "https://myportal.domain.com/server/rest/services/Hosted/DeliveryTracks/FeatureServer/0", "filter": "Month = 'September'"}
//REST scripting example
"pointLayer": {"url": "https://myportal.domain.com/server/rest/services/Hosted/DeliveryTracks/FeatureServer/0", "filter": "Month = 'September'"}

polylineLayer (Required)

The polyline features to which track points will be matched.

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

1
2
3
4
//REST web example
polylineLayer={"url": "https://myportal.domain.com/server/rest/services/Hosted/Roads/FeatureServer/0", "filter": "Month = 'September'"}
//REST scripting example
"polylineLayer": {"url": "https://myportal.domain.com/server/rest/services/Hosted/Roads/FeatureServer/0", "filter": "Month = 'September'"}

trackFields (Required)

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

REST examples

1
2
3
4
//REST web example
trackFields=Truck Name
//REST scripting Example
"trackFields": "VehicleID, DriverID"

polylineFieldsToInclude (Optional)

One or more fields from the polyineLayer that will be included in the output result.

REST examples

1
2
3
4
//REST web example
polylineFieldsToInclude=Speed, Street Name
//REST scripting Example
"polylineFieldsToInclude": "Speed, Street Name"

connectivityFieldMatching (Required)

The polyline layer fields that will be used to define the connectivity of the input polyline features. The following values are required:

• polylineID—The unique identifier for the line
• fromNodeID—The node where the travel along a line is moving away from
• toNodeID—The node where the travel along a line is moving to

REST examples

1
2
3
4
5
6
7
8
9
10
11
12
//REST web example
connectivityFieldMatching={
"polylineId":"streetname",
"fromNode":"fromnodeid",
"toNode":"tonodeid"
}
//REST scripting Example
"polylineFieldsToInclude": {
"polylineId":"streetname",
"fromNode":"fromnodeid",
"toNode":"tonodeid"
}

directionFieldMatching (Optional)

The polyline layer field and attribute values that will be used to define the direction of the input polyline features. For example, a polyline layer has a field named direction with values T (backward), F (forward), B (both), and "" (none). If not specified, it is assumed the polyline is bidirectional.

REST examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
//REST web example
directionFieldMatching={
"directionField":"dirtravel",
"forwardValue":"F",
"backwardValue":"T",
"noneValue":"",
"bothValue":"B"
}
//REST scripting Example
"directionFieldMatching": {
"directionField":"dirtravel",
"forwardValue":"F",
"backwardValue":"T",
"noneValue":"",
"bothValue":"B"
}

searchDistance (Required)

The maximum distance allowed between a point and any polyline to be considered a match. It is recommended that you use values less than or equal to 50 meters. Larger distances will result in a longer process time and less accurate results.

REST examples

1
2
3
4
//REST web example
searchDistance=12
//REST scripting example
"searchDistance": 10

searchDistanceUnit (Required)

The searchDistance unit.

REST examples

1
2
3
4
//REST web example
searchDistanceUnit=Kilometers
//REST scripting example
"searchDistanceUnit": "Meters"

distanceMethod (Required)

The method used to calculate search distances between points and lines. There are two methods: Geodesic and Planar. The Geodesic method calculates distances geodesically and will allow tracks to cross the antimeridian. This method is appropriate for large areas and any geographic coordinate system. This is the default. The Planar method calculates distances using a plane method and will not cross the antimeridian.

REST examples

1
2
3
4
//REST web example
distanceMethod=Geodesic
//REST scripting example
"distanceMethod": "Planar"

outputMode (Required)

Specifies whether all input features are returned or only the input features that were matched to a line feature.

REST examples

1
2
3
4
//REST web example
outputMode=MatchedFeatures
//REST scripting example
"outputMode": "AllFeatures"

timeSplit (Optional)

A time duration used to split tracks. Any features in the pointLayer that are in the same track and are farther apart than this time will be split into a new track. The units of the distance values are supplied by the timeSplitUnit parameter. If both distanceSplit and timeSplit are used, a track is split when at least one condition is met.

REST examples

1
2
3
4
//REST web example
53
//REST scripting example
"timeSplit": 53

timeSplitUnit (Required if timeSplit is specified)

The temporal unit to be used with the temporal distance value specified in timeSplit.

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

REST examples

1
2
3
4
//REST web example
Hours
//REST scripting example
"timeSplitUnit": "Minutes"

distanceSplit (Optional)

A distance used to split tracks. Any features in the pointLayer that are in the same track and are farther apart than this distance will be split into a new track. The units of the distance values are supplied by the distanceSplitUnit parameter. If both distanceSplit and timeSplit are used, the track is split when at least one condition is met.

REST examples

1
2
3
4
//REST web example
53.8
//REST scripting example
"distanceSplit": 1001

distanceSplitUnit (Required if distanceSplit is specified)

The distance unit to be used with the distance value specified in distanceSplit.

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

REST examples

1
2
3
4
//REST web example
Meters
//REST scripting example
"distanceSplitUnit": "Miles"

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.

REST examples

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

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

1
2
3
4
//REST web example
9466835800000
//REST scripting example
"timeBoundaryReference": 946684800000

outputName (Required)

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

REST examples

1
2
3
4
//REST web example
outputName=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:

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

output

The output contains points snapped to the nearest location along the polyline it matched. The polyline features are not returned. The unique identifier of the polyline dataset will be available for matched results. The unique identifier field is specified using the connectivityFieldMatching parameter. You can identify which polylines were matched to by referencing this field. In addition to any polyLineFieldsToInclude, and the fields from the inputPoints, the following fields will be returned:

• MatchStatus—Indicates whether the observation was matched to a line. Values are M for matched features and U for unmatched features.
• OrigX—The x-coordinate of the input observation. Coordinates are stored in the units of the output spatial reference.
• OrigY—The y-coordinate of the input observation. Coordinates are stored in the units of the output spatial reference.
• MatchX—The x-coordinate of the matched result on the line. Coordinates are stored in the units of the output spatial reference.
• MatchY—The y-coordinate of the matched result on the line. Coordinates are stored in the units of the output spatial reference.
• MatchDist—The distance between the origin location and the matched location for an observation. Distances are calculated based on the distance method selected (geodesic or planar). Values are recorded in meters.
• MatchStatus—The time stamp of the observation. If ouputMode is AllFeatures, both matched and unmatched points will be returned. For unmatched points, output result fields will be appended with null values for numeric fields and empty strings for string fields. The fields that will be appended with null values are line fields specified using polyLineFieldsToInclude, MatchX, MatchY, and MatchDist.

1
{"url": "https://<analysis-url>/SnapTracks/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.

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.