Trace Proximity Events

Entity

A moving object with position periodically recorded.

An animal, person, or vehicle. An entity may be stationary or moving.

Entities of interest

The specific entities used to start a trace.

A person infected with COVID-19.

Proximity event

When two entities are near each other within a period of time.

Two people that come within 3 meters of each other and within a 1-minute window of each other.

Depth

The degree of separation between an entity of interest and an entity further down the trace (downstream).

A proximity event between the entity of interest and someone else is depth 1.

Trace event

The first contact for a specified entity downstream from the entities of interest.

inputPoints (Required)

The time-enabled point features that will be traced.

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
5
//REST web example
{"url": "https://myportal.domain.com/server/rest/services/Hosted/fish_tracks/FeatureServer/0", "filter": "Month = 'September'"}

//REST scripting example
"inputPoints": {"url": "https://myportal.domain.com/server/rest/services/Hosted/fish_tracks/FeatureServer/0", "filter": "Month = 'September'"}

entityIdField (Required)

The field used to identify distinct entities.

REST examples

1
2
3
4
5
//REST web example
BoatName

//REST scripting Example
"trackFields": "BoatName"

entitiesOfInterestIds (Optional)

JSON used to specify one or more entities that you are interested in tracing from. You can optionally include a time to start tracing from. If you do not specify a time, January 1, 1970, at 12:00 a.m. will be used.

entitiesOfInterestIds is required if entitiesOfInterestLayer is not specified.

REST examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
//REST web example
[{
"entityId": "user1",
"epochTimeStamp": 1598390663000
}, {
"entityId": "user2",
"epochTimeStamp": null
}, {
"entityId": "user3",
"epochTimeStamp": 1598390663000
}]

//REST scripting example
"extentOutput": [{
"entityId": "user1",
"epochTimeStamp": 1598390663000
}, {
"entityId": "user2",
"epochTimeStamp": null
}, {
"entityId": "user3",
"epochTimeStamp": 1598390663000
}]

entitiesOfInterestLayer (Optional)

A feature class used to specify one or more entities that you are interested in tracing from.

entitiesOfInterestLayer is required if entitiesOfInterestIds is not specified.

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
5
//REST web example
{"url": "https://myportal.domain.com/server/rest/services/Hosted/fish_tracks/FeatureServer/0", "filter": "Month = 'September'"}

//REST scripting example
"inputLayer": {"url": "https://myportal.domain.com/server/rest/services/Hosted/fish_tracks/FeatureServer/0",

distanceMethod (Required)

The distance type that will be used for the spatialSearchDistance. The default is Geodesic.

Values: Geodesic | Planar

REST examples

1
2
3
4
5
//REST web example
Planar

//REST scripting example
"distanceMethod": "Planar"

spatialSearchDistance (Required)

The maximum distance between two points to be considered in proximity. Features closer together in space and that also meet temporalSearchDistance criteria are considered in proximity of each other.

REST examples

1
2
3
4
5
//REST web example
6

//REST scripting example
"spatialSearchDistance": 6

spatialSearchDistanceUnit (Required)

The unit of spatialSearchDistance .

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

REST examples

1
2
3
4
5
//REST web example
Feet

//REST scripting example
"spatialSearchDistanceUnit": "Feet"

temporalSearchDistance (Required)

The maximum duration between two points that are considered in proximity. Features closer together in time and that also meet the spatialSearchDistance criteria are considered in proximity of each other.

REST examples

1
2
3
4
5
//REST web example
2

//REST scripting example
"temporalSearchDistance": 2

temporalSearchDistanceUnit (Required)

The unit of temporalSearchDistance. Required if temporalSearchDistance is specified.

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

REST examples

1
2
3
4
5
//REST web example
Meters

//REST scripting example
"temporalSearchDistanceUnit": "Meters"

includeTracksLayer (Required)

Determines whether or not an additional layer will be created containing the first trace event in tracks and all subsequent features. The default is false.

REST examples

1
2
3
4
5
//REST web example
true

//REST scripting example
"includeTracksLayer": true

maxTraceDepth (Optional)

The maximum degrees of separation between an entity of interest and an entity further down the trace.

REST examples

1
2
3
4
5
//REST web example
5

//REST scripting example
"maxTraceDepth":10

attributeMatchCriteria (Optional)

One or more attributes used to constrain the proximity events. Entities will only be considered near when the spatialSearchDistance and temporalSearchDistance criteria are met and the two entities have equal values of the attributes specified.

REST examples

1
2
3
4
5
//REST web example
building_level,building_name

//REST scripting example
"inputLayer": "building_level,building_name"

outputName (Required)

The name of the result feature layer that will be created.

REST examples:

1
2
3
4
5
//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:

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 point layer of proximity events. Only the first proximity event for each entity in the trace will be included.

1
{"url": "https://<analysis-url>/TraceProximityEvents/jobs/<jobId>/results/output"}

tracksLayer

An optional point layer containing the first observation of each entity in the trace and every observation after that time. tracksLayer will be created if includeTracksLayer is set to true. This result is useful for showing the path of travel of entities after they've come into proximity with entities in the trace.

1
{"url": "https://<analysis-url>/TraceProximityEvents/jobs/<jobId>/results/tracksLayer"}