Trace Proximity Events

Description

The Trace Proximity Events task analyzes time-enabled point features representing moving entities. The task will follow entities of interest in space (location) and time to see which other entities the entities of interest have interacted with. The trace will continue from entity to entity to a configurable maximum degrees of separation from the original entity of interest.

For example, suppose an organization monitors company-issued devices carried by workers. The company is interested in determining which employees were near an individual known to have COVID-19. Using the point layer representing device locations and time, they can identify devices that have been within 6 meters and 5 minutes of the contagious person and other possibly contagious employees.

As another example, an NGO is monitoring salmon populations using GPS and is interested in tracking the spread of salmon lice between escaped farmed salmon and wild populations. Some GPS-tagged farmed salmon were tracked to see if they come in close proximity with tagged wild populations, and how those wild populations may further spread the disease. The measurements also include a depth field, and the NGO uses the attributeMatchCriteria parameter to only find fish at a similar depth.

The Trace Proximity Events task uses the following terminology:

TermDefinitionExample

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.

The diagrams below demonstrate how the Trace Proximity Events task processes your data. In these diagrams, time is on the x-axis.

In each diagram there are four entities: A, B, C, and D. The highlighted text describes the trace events that occur between two entities (the from and to entities) and the depth of the proximity event. In this example, entity C is the entity of interest that you are tracing downstream from.

Entity C is your chosen entity of interest. The depth is 0.

A proximity event occurs between entities C and B. The depth of the trace is 1. When multiple features are subsequent proximity events, this is a sustained proximity event.

A proximity event occurs between B and A. The depth of the trace is 2.

A proximity event occurs between C and D. The depth of the trace is 1.

Entities are considered near each other when they meet both the distance and time requirements. The images below show two features (red and blue). In Figure A, the two features are within a spatial search distance of each other. In Figure B, the two features are within the temporal search distance of each other.

Trace Proximity Events was introduced in ArcGIS Enterprise 10.9.

Request parameters

ParameterDetails
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

``````//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

``````//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

``````//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

``````//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

``````//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

``````//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

``````//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

``````//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

``````//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

``````//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

``````//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

``````//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:

``````//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:
``````{
"extent" : {extent},
"processSR" : {spatial reference},
"outSR" : {spatial reference},
"dataStore":{data store}
}``````

f

The response format. The default response format is html.

Values: html | json

Example usage

Below is a sample request URL for TraceProximityEvents:

``https://hostname.domain.com/webadaptor/rest/services/System/GeoAnalyticsTools/GPServer/TraceProximityEvents/submitJob?inputLayer={"url":"https://hostname.domain.com/webadaptor/rest/services//employee_tracks/0"}&entityIdField=450&entitiesOfInterestRecordSet={"url":"https://hostname.domain.com/webadaptor/rest/services/eoi_subset/0"}&spatialSearchDistance=5&spatialSearchDistanceUnit=Meters&temporalSearchDistance=30&temporalSearchDistanceUnit=Seconds&maxTraceDepth=10&outputName=trace_events&f=json``

Response

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

``````{
"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:

``https://<analysis url>/TraceProximityEvents/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:

``https://<analysis-url>/TraceProximityEvents/jobs/<jobId>/results/output?token=<your token>&f=json``

ResponseDescription
output

The point layer of proximity events. Only the first proximity event for each entity in the trace will be included.

``{"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.

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