Select Layer By Date And Time (Crime Analysis and Safety)—ArcGIS Pro

Summary

Selects records based on date and time ranges or date properties, for example, single date, time range, time period, days of the week, month, or year.

Usage

The input must be a feature layer or table view.
The input must contain a date field. If your input does not contain a date field, use the Convert Time Field tool to generate a date field derived from dates formatted as text in a text field.
This tool performs a selection using all the selection criteria, if any part of the input date does not match the selection criteria, the feature will not be selected.
To use this tool in a model or script, use the Make Table View or Make Feature Layer tool to convert an input feature class to a table view or feature layer, respectively, prior to executing this tool.

Syntax

arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view, selection_type, time_type, {date_field}, {start_date_field}, {end_date_field}, {selection_options}, {date_selection_type}, {single_date}, {start_date}, {end_date}, {use_system_time}, {time_slice}, {start_time}, {end_time}, {days_of_week}, {months}, {years})

Parameter	Explanation	Data Type
in_layer_or_view	The data containing a date field to which the selection will be applied.	Table View
selection_type	Specifies how the selection will be applied and what will occur if a selection already exists. NEW_SELECTION — The resulting selection will replace the current selection. This is the default. ADD_TO_SELECTION — The resulting selection will be added to the current selection if one exists. If no selection exists, this is the same as the new selection option. REMOVE_FROM_SELECTION — The resulting selection will be removed from the current selection. If no selection exists, this option has no effect. SUBSET_SELECTION — The resulting selection will be combined with the current selection. Only records that are common to both remain selected.	String
time_type	Specifies how date and time fields will be used to select records. SINGLE_TIME_FIELD —Records will be selected based on a single time field on the input feature. TIME_RANGE_FIELDS —Records will be selected based on start and end time fields on the input feature.	String
date_field (Optional)	The date field from the input layer on which the selection will be based. This parameter is only active if the Time Type parameter is set to Single Time Field.	Field
start_date_field (Optional)	The start date field from the time range on which the selection will be based. This parameter is only active if the Time Type parameter is set to Time Range Fields .	Field
end_date_field (Optional)	The end date field from the time range on which the selection will be based. This parameter is only active if the Time Type parameter is set to Time Range Fields.	Field
selection_options [selection_options,...] (Optional)	Specifies how date and time selections will be made. DATE —The selection will be by date. TIME —The selection will be by time of day. DAY_OF_WEEK —The selection will be by day of the week. MONTH —The selection will be by month. YEAR —The selection will be by year.	String
date_selection_type (Optional)	Specifies whether records will be selected based on a date range, singular date, recency period, or comparative time period. This parameter is only active when the Selection Options parameter is set to Date. DATE_RANGE —Records will be selected based on a start and end date range. SINGLE_DATE —Records will be selected based on the date specified. RECENCY —Records will be selected based on a time period in relation to the current date (system date and time), for example, within the last 14 days. COMPARATIVE —Records will be selected based on the time period immediately preceding a recent time period in relation to the current date (system date and time). For example, if the current date is January 29 and the time slice is 14 days, records occurring between January 1 and January 14 will be selected. This option can be used in combination with a subsequent By Recency selection to compare record counts between two adjacent time periods (for example, the two 14-day time periods of January 1–14 and January 15–28).	String
single_date (Optional)	The single date and time to be selected. This parameter is only active when the Date Selection Type parameter is set to By Single Date.	Date
start_date (Optional)	The start date of the date range. This parameter is only active when the Date Selection Type parameter is set to By Date Range.	Date
end_date (Optional)	The end date of the date range. This parameter is only active when the Date Selection Type parameter is set to By Date Range.	Date
use_system_time (Optional)	Specifies whether records from the current day (local system time) will be included in the selection if they exist in the recent time period. SYSTEM_TIME —Records from the current day will be included in the selection. NO_SYSTEM_TIME —Records from the current day will not be included in the selection. This is the default. For example, the time slice specified is 14 days, the local system time is 5:00 p.m. on January 15 when the tool executes, the recency time period includes all records between 5:00 p.m. on the date 14 days ago and 5:00 p.m. on the day the tool is executed, and SYSTEM_TIME is selected. In this example, the selection will be January 1, 2017 5:00:00 PM to January 15, 2017 5:00:00 PM. Using this same example with NO_SYSTEM_TIME selected, the recent period uses the beginning of the current day as the end time (based on local system time). In this case, the selection will be January 1, 2017 12:00:00 AM to January 15, 12:00:00 AM for the 14-day time slice.	Boolean
time_slice (Optional)	The number of time units (minutes, hours, days, weeks, months, or years) defining the recent time period on which the selection will be based, for example, events within the last 14 days. This parameter is only active when the Date Selection Type parameter is set to By Comparative Time Period or By Regency.	Time Unit
start_time (Optional)	The start time of the time range. This parameter is only active when the Selection Options parameter is set to Time.	Date
end_time (Optional)	The end time of the time range. This parameter is only active when the Selection Options parameter is set to Time.	Date
days_of_week [days_of_week,...] (Optional)	Specifies the days of the week used to select records. MONDAY —Records occurring on Monday will be selected. TUESDAY —Records occurring on Tuesday will be selected. WEDNESDAY —Records occurring on Wednesday will be selected. THURSDAY —Records occurring on Thursday will be selected. FRIDAY —Records occurring on Friday will be selected. SATURDAY —Records occurring on Saturday will be selected. SUNDAY —Records occurring on Sunday will be selected. This parameter is only active when the Selection Options parameter is set to Day of week.	String
months [months,...] (Optional)	Specifies the months used to select records. JANUARY —Records occurring in January will be selected. FEBRUARY —Records occurring in February will be selected. MARCH —Records occurring in March will be selected. APRIL —Records occurring in April will be selected. MAY —Records occurring in May will be selected. JUNE —Records occurring in June will be selected. JULY —Records occurring in July will be selected. AUGUST —Records occurring in August will be selected. SEPTEMBER —Records occurring in September will be selected. OCTOBER —Records occurring in October will be selected. NOVEMBER —Records occurring in November will be selected. DECEMBER —Records occurring in December will be selected. This parameter is only active when the Selection Options parameter is set to Month.	String
years [years,...] (Optional)	Specifies the years used to select records. This parameter is only active when the Selection Options parameter is set to Years.	Long

Derived Output

Name	Explanation	Data Type
out_layer_or_view	The updated inputs with selections applied.	Table View
count	The number of selected records.	Long

Code sample

SelectLayerByDateAndTime example 1 (Python window)

The following script demonstrates how to use the SelectLayerByDateAndTime function in immediate mode.

import arcpy
arcpy.env.workspace = r"C:/data/city_pd.gdb"

arcpy.ca.SelectLayerByDateAndTime("Crimes",
                                "NEW_SELECTION",
                                "SINGLE_TIME_FIELD",
                                "offendate",
                                None,
                                None,
                                "DATE",
                                "DATE_RANGE",
                                None,
                                "8/1/2018",
                                "8/31/2018")

SelectLayerByDateAndTime example 2 (stand-alone window)

The stand-alone script below is an example of how to use the SelectLayerByDateAndTime function in a script:

# Name: SelectLayerByDateAndTime.py
# Description: Select crimes that occurred in the past 28 days, from 9 PM to 1 PM, on the weekend, from the month of October to December,
#              in the year 2018, and show the selection count. Finally, make a selection based on all the queries above.

# Import script modules
import arcpy

# Set the workspace
arcpy.env.workspace = r"C:\data\city_pd.gdb"

# Convert Feature class to table view
arcpy.management.MakeTableView("Crimes", "Crimes_View")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="DATE",
                                                date_selection_type="RECENCY",
                                                time_slice="28 Days")

arcpy.AddMessage("Crimes that occurred in past 28 days: {}".format(str(count)))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="TIME",
                                                start_time="9:00 PM",
                                                end_time="1:00 AM")

arcpy.AddMessage("All crimes that occurred between 9PM and 1AM: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="DAY_OF_WEEK",
                                                days_of_week=["SATURDAY", "SUNDAY"])

arcpy.AddMessage("All crimes that occurred on the weekend: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="MONTH",
                                                months=["OCTOBER", "NOVEMBER", "DECEMBER"])

arcpy.AddMessage("All crimes that occurred October through December: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")


lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="YEAR",
                                                years=[2018])

arcpy.AddMessage("All crimes that occurred in the year 2018: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")


# Combine selection options for more detailed time queries
lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options=["TIME", "DAY_OF_WEEK", "MONTH","YEAR"],
                                                start_time="9:00 PM",
                                                end_time="1:00 AM",
                                                days_of_week=["SATURDAY", "SUNDAY"],
                                                months=["OCTOBER", "NOVEMBER", "DECEMBER"],
                                                years=[2018])

message = """All crimes that occurred in the year 2018 during the months
of October through November on the weekends from 9PM to 1AM: {}
""".format(count)

arcpy.AddMessage(message)
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")

Environments

This tool does not use any geoprocessing environments.

Licensing information

Basic: Yes
Standard: Yes
Advanced: Yes