Locate Features Along Routes (Linear Referencing Tools)

Summary

Computes the intersection of input features (point, line, or polygon) and route features and writes the route and measure information to a new event table.

Learn more about event tables

Usage

When the Input Features parameter value is points, the Event Type value must be set to Point. When the Input Features parameter value is lines or polygons, the Event Type value must be set to Line.
The best results will be achieved when the input features and the target routes closely overlay.

Caution:

Using a large search radius or cluster tolerance to overcome discrepancies between the input features and target routes can produce unexpected results.
To reduce the number of input features that will be processed by this tool, you can input layers that have selections.
The output table can be displayed in a map using the Make Route Event Layer tool.

Label	Explanation	Data type
Input Features	The input point, line, or polygon features.	Feature Layer
Input Route Features	The routes with which the Input Features parameter value will intersect.	Feature Layer
Route Identifier Field	The field containing values that uniquely identify each route. The field can be a numeric, text, or GUID field.	Field
Search Radius	If the Input Features parameter value is points, the search radius will be a numeric value defining how far around each point a search will be done to find a target route. If the Input Features parameter value is lines, the search tolerance will be a cluster tolerance, which is a numeric value representing the maximum tolerated distance between the input lines and the target routes. If the Input Features parameter value is polygons, this parameter is ignored and no search radius will be used.	Linear Unit
Output Event Table	The table that will be created. The output table can be a dBase (`.dbf` file) or a geodatabase table.	Table
Output Event Table Properties	The route location fields and the type of events that will be written to the output event table. Route Identifier Field—The field that will contain values that indicate the route on which each event is located. The field can be a numeric, text, or GUID field. Event Type—The type of events the output event table will contain (Point or Line). Point—Point events occur at a precise location along a route. Only a single measure field must be specified. Line—Line events define a portion of a route. Both from- and to-measure fields must be specified. From-Measure Field—A field that will contain measure values. This field is required when the event type is Point or Line. When the Event Type value is Point, the label for this parameter becomes Measure Field. To-Measure Field—A field that will contain measure values. This field is required when the event type is Line.	Route Measure Event Properties
Keep only the closest route location (Optional)	Specifies whether the closest route location or every route location within the search radius will be written to the Output Event Table parameter value. When locating points along routes, more than one route may be within the search radius of any given point. This parameter is ignored when locating lines or polygons along routes. Checked—Only the closest route location will be written to the Output Event Table parameter value. This is the default. Unchecked—Every route location within the search radius will be written to the Output Event Table parameter value.	Boolean
Include distance field on output table (Optional)	Specifies whether a `DISTANCE` field will be added to the Output Event Table parameter value. The values in this field are in the units of the specified search radius. This parameter is ignored when locating lines or polygons along routes. Checked—A field containing the point-to-route distance will be added to the Output Event Table parameter value. This is the default. Unchecked—A field containing the point-to-route distance will not be added to the Output Event Table parameter value.	Boolean
Keep zero length line events (Optional)	Specifies whether zero-length line events will be written to the output. When locating polygons along routes, events may be created where the from-measure is equal to the to-measure. This parameter is ignored when locating points or lines along routes. Checked—Zero-length line events will be written to the Output Event Table parameter value. This is the default. Unchecked—Zero-length line events will not be written to the Output Event Table parameter value.	Boolean
Include all fields from input (Optional)	Specifies whether the Output Event Table parameter value will contain route location fields and all the attributes from the Input Features parameter value. Checked—The Output Event Table parameter value will contain route location fields and all the attributes from the Input Features parameter value. This is the default. Unchecked—The Output Event Table parameter value will only contain route location fields and the `ObjectID` field from the Input Features parameter value.	Boolean
Use M direction offsetting (Optional)	Specifies whether the offset distance calculated will be based on the m-direction or the digitized direction. Distances are included in the Output Event Table parameter value if the Include distance field on output table parameter is checked. Checked—The distance values in the Output Event Table parameter value will be calculated based on the m-direction of the route. Input features to the left of the m-direction of the route will be assigned a positive (+) offset, and features to the right of the m-direction will be assigned a negative (-) offset. This is the default. Unchecked—The distance values in the Output Event Table parameter value will be calculated based on the digitized direction of the route. Input features to the left of the digitized direction of the route will be assigned a negative (-) offset, and features to the right of the digitized direction will be assigned a positive (+) offset.	Boolean

arcpy.lr.LocateFeaturesAlongRoutes(in_features, in_routes, route_id_field, radius_or_tolerance, out_table, out_event_properties, {route_locations}, {distance_field}, {zero_length_events}, {in_fields}, {m_direction_offsetting})

Name	Explanation	Data type
in_features	The input point, line, or polygon features.	Feature Layer
in_routes	The routes with which the `in_features` parameter value will intersect.	Feature Layer
route_id_field	The field containing values that uniquely identify each route. The field can be a numeric, text, or GUID field.	Field
radius_or_tolerance	If the `in_features` parameter value is points, the search radius will be a numeric value defining how far around each point a search will be done to find a target route. If the `in_features` parameter value is lines, the search tolerance will be a cluster tolerance, which is a numeric value representing the maximum tolerated distance between the input lines and the target routes. If the `in_features` parameter value is polygons, this parameter is ignored and no search radius will be used.	Linear Unit
out_table	The table that will be created. The output table can be a dBase (`.dbf` file) or a geodatabase table.	Table
out_event_properties	The route location fields and the type of events that will be written to the output event table. Route identifier field—The field that will contain values that indicate the route on which each event is located. The field can be a numeric, text, or GUID field. Event type—The type of events the output event table will contain (`POINT` or `LINE`). `POINT`—Point events occur at a precise location along a route. Only a single measure field must be specified. `LINE`—Line events define a portion of a route. Both from- and to-measure fields must be specified. From-measure field—A field that will contain measure values. This field is required when the event type is `POINT` or `LINE`. To-measure field—A field that will contain measure values. This field is required when the event type is `LINE`.	Route Measure Event Properties
route_locations (Optional)	Specifies whether the closest route location or every route location within the search radius will be written to the `out_table` parameter value. When locating points along routes, more than one route may be within the search radius of any given point. This parameter is ignored when locating lines or polygons along routes. `FIRST`—Only the closest route location will be written to the `out_table` parameter value. This is the default. `ALL`—Every route location within the search radius will be written to the `out_table` parameter value.	Boolean
distance_field (Optional)	Specifies whether a `DISTANCE` field will be added to the `out_table` parameter value. The values in this field are in the units of the specified search radius. This parameter is ignored when locating lines or polygons along routes. `DISTANCE`—A field containing the point-to-route distance will be added to the `out_table` parameter value. This is the default. `NO_DISTANCE`—A field containing the point-to-route distance will not be added to the `out_table` parameter value.	Boolean
zero_length_events (Optional)	Specifies whether zero-length line events will be written to the output. When locating polygons along routes, events may be created where the from-measure is equal to the to-measure. This parameter is ignored when locating points or lines along routes. `ZERO`—Zero-length line events will be written to the `out_table` parameter value. This is the default. `NO_ZERO`—Zero-length line events will not be written to the `out_table` parameter value.	Boolean
in_fields (Optional)	Specifies whether the `out_table` parameter value will contain route location fields and all the attributes from the `in_features` parameter value. `FIELDS`—The `out_table` parameter value will contain route location fields and all the attributes from the `in_features` parameter value. This is the default. `NO_FIELDS`—The `out_table` parameter value will only contain route location fields and the `ObjectID` field from the `in_features` parameter value.	Boolean
m_direction_offsetting (Optional)	Specifies whether the offset distance calculated will be based on the m-direction or the digitized direction. Distances are included in the `out_table` parameter value if the `distance_field` parameter is set to `DISTANCE`. `M_DIRECTON`—The distance values in the `out_table` parameter value will be calculated based on the m-direction of the route. Input features to the left of the m-direction of the route will be assigned a positive (+) offset, and features to the right of the m-direction will be assigned a negative (-) offset. This is the default. `NO_M_DIRECTION`—The distance values in the `out_table` parameter value will be calculated based on the digitized direction of the route. Input features to the left of the digitized direction of the route will be assigned a negative (-) offset, and features to the right of the digitized direction will be assigned a positive (+) offset.	Boolean

Code sample

LocateFeaturesAlongRoutes example 1 (Python window)

The following Python script demonstrates how to use the LocateFeaturesAlongRoutes function in the Python window

import arcpy
arcpy.env.workspace = "C:/Data"
arcpy.lr.LocateFeaturesAlongRoutes("rail_segments.shp", "rail_routes.shp",
                                   "rkey", "0.5 Feet", "locate_lines",
                                   "rkey LINE fmp tmp")

LocateFeaturesAlongRoutes example 2 (stand-alone script)

The following Python script demonstrates how to use the LocateFeaturesAlongRoutes function in a stand-alone Python script.

# Name: LocateFeaturesAlongRoutes_Example2.py
# Description: Locate shapefile lines along shapefile routes.

# Import system modules
import arcpy

# Set workspace
arcpy.env.workspace = "C:/Data"

# Set local variables
feats = "rail_segments.shp"
rts = "rail_routes.shp"
rid = "rkey"
tol = "0.5 Feet"
tbl = "locate_lines"
props = "rkey LINE fmp tmp"

# Run LocateFeaturesAlongRoutes
arcpy.lr.LocateFeaturesAlongRoutes(feats, rts, rid, tol, tbl, props)

LocateFeaturesAlongRoutes example 3 (stand-alone script)

The following Python script demonstrates how to use the LocateFeaturesAlongRoutes function in a stand-alone Python script using file geodatabase data.

# Name: LocateFeaturesAlongRoutes_Example3.py
# Description: Locate file geodatabase points along file geodatabase routes.

# Import system modules
import arcpy

# Set workspace
arcpy.env.workspace = "C:/Data/Pitt.gdb"

# Set local variables
feats = "rail/crossings"  # Crossings is in the rail feature dataset
rts = "rail/routes"  # Routes is in the rail feature dataset
rid = "rkey"
rad = "10 Feet"
tbl = "locate_points"
props = "rkey POINT mp"

# Run LocateFeaturesAlongRoutes
arcpy.lr.LocateFeaturesAlongRoutes(feats, rts, rid, rad, tbl, props)

LocateFeaturesAlongRoutes example 4 (stand-alone script)

The following Python script demonstrates how to use the LocateFeaturesAlongRoutes function in a stand-alone Python script using enterprise geodatabase data.

# Name: LocateFeaturesAlongRoutes_Example4.py
# Description: Locate enterprise geodatabase polygons along enterprise geodatabase routes.

# Import system modules
import arcpy

# Set workspace
arcpy.env.workspace = "C:/MyProject/myConn.sde"

# Set local variables
feats = arcpy.ValidateTableName("counties", wkspc)  # Stand-alone feature class
rts = arcpy.ValidateTableName("rail_routes", wkspc)  # Stand-alone feature class
rid = "rkey"
tbl = "locate_polys"
props = "rkey LINE fmp tmp"

# Run LocateFeaturesAlongRoutes
arcpy.lr.LocateFeaturesAlongRoutes(feats, rts, rid, "#", tbl, props, "#", "#",
                                   "NO_ZERO", "M_DIRECTON")

Environments

Current Workspace, Output CONFIG Keyword, Extent, Scratch Workspace

Licensing information

Basic: Yes
Standard: Yes
Advanced: Yes