Cell Phone Records To Feature Class (Crime Analysis and Safety)—ArcGIS Pro

Summary

Imports cell phone records from wireless network providers and associates those records with a cell site and sector feature classes as generated by the Cell Site Records To Feature Class tool based on identifier fields.

Usage

The Input Cell Site Points parameter values must be generated using the Cell Site Records To Feature Class tool.
The Output Phone Record Site Points and Output Phone Record Sectors parameters will only contain the phone records that were successfully linked to the input cell site and sectors based on matching ID fields. The Output Phone Record Site Points and Output Phone Record Sectors parameter values do not represent the actual location of the cell phone.
Wireless network providers provide cell phone records or call detail records (CDR) in a variety of formats and styles. It is common to receive data in a nontabular format or schema. The Input Phone Records Table parameter value must be a table with column names at the top.
The table provided by the wireless network provider may contain CDR and cell site information in one row. When the table is structured this way, it must be separated into two tables. Use the table containing the call information (identifiers, phone numbers, dates, time, call duration, and coordinates) as the input to this tool.
A feature is created in the output feature classes for each record (call or data event) of the Input Phone Records Table parameter.
The following fields will be added to the output feature classes:
- SUBSCRIBER—The subscriber phone number of the Input Phone Records Table parameter value. All nonnumeric characters are removed from the output.
- UNIQUEID—The unique identifier of the cell sector antennas.
The following fields will be added to the output when the specified parameter is used:
- DESTPHONE—The callee phone number of the Input Phone Records Table parameter value. This is added to the output when the Destination Phone Number Field parameter is used. All nonnumeric characters are removed from the output.
- STARTTIME—The start date and time field of the Input Phone Records Table parameter value. This is added to the output when the Start Date and Time Field parameter is used.
- DURATION—The duration of the phone call, in seconds, of the Input Phone Records Table parameter value. Duration values formatted as HH:MM:SS will be converted to total seconds. This is added to the output when the Duration Field parameter is used or when both the Start Date and Time Field and End Date and Time Field parameters are used.
- ENDTIME—The end date and time field of the Input Phone Records Table parameter value. This is added to the output when the End Date and Time Field parameter is used or when both the Start Date and Time Field and Duration parameters are used
The table provided by the wireless network provider may include a cell site information table with one unique ID field to define all unique records or a combination of identifier fields to define unique records in the table. For example, a table may contain site identifier and sector identifier fields to uniquely define some records, but other records in the table are uniquely defined with Location Area Code identifier and cell identifier fields.
- When one unique ID field is provided for the input table, set the ID Type option to Unique ID in the Cell Sector ID Fields or Additional Cell Sector ID Fields parameter. In the same parameter, populate the Field option with the field that represents that unique ID.
- When many ID fields are provided for the table to indicate uniqueness, all ID fields must be added to the output. For each ID field choose the ID Type value that defines the ID type in the Cell Sector ID Fields or Additional Cell Sector ID Fields parameter. In the same parameter, populate the Field option with the related field that contains the ID information. The tool will combine these ID fields and populate a single unique ID field in the output feature classes called UNIQUEID.
The following fields will be added to the output if they're specified in the Cell Sector ID Fields or Additional Cell Sector ID Fields parameter:
- SITEID—The unique identifier of a cell site
- SECTORID—The unique identifier of a cell sector
- SWITCHID—The unique identifier of a wireless network switch
- LACID—The unique identifier of a Location Area Code
- CASCADEID—The unique identifier of the sector within wireless network cascade
- CELLID—The unique identifier of the sector within a Location Area Code
When the input phone record table contains call records that span multiple cell sectors, both the Cell Sector ID Fields and Additional Cell Sector ID Fields parameters must be populated. The Cell Sector ID Fields parameter must contain the identifiers associated with the beginning sector, and the Additional Cell Sector ID Fields parameter must contain the end sector or any sector other than the beginning sector in the call record.
When the input phone record table contains data event records or only one sector is referenced in the call record, only the Cell Sector ID Fields parameter must be populated.
The following field and values are generated when the Additional Cell Sector ID Fields parameter is populated:
- IDTYPE—The field identifying whether a call record is a primary sector or an additional sector of a call record.
  - PRIMARY—The value assigned when a cell phone record is linked to a sector at the beginning of a call.
  - ADDITIONAL—The value assigned when a cell phone record is linked to a sector at the end of a call or any sector during the duration of the call when the sector is different than the sector at the beginning of the call.
- LOCTIME—The field containing a unique date and time value of a call record based on whether the IDTYPE field is PRIMARY or ADDITIONAL. The value of the STARTTIME field is assigned to the LOCTIME field when the IDTYPE field value is PRIMARY. The value of the ENDTIME field is assigned to the LOCTIME field when the IDTYPE field value is ADDITIONAL. The LOCTIME field allows the features to be visualized by a unique date time value and estimated location of calls.
If a cell phone record is linked to the same sector at the beginning and end of a call, no separate feature is created for the cell sector representing the end of a call.
The output estimated call points will contain all the associated fields of the Output Phone Records Site Points and Output Phone Records Site Sectors parameter values.
The following fields will be added to the Output Estimated Call Points parameter value:
- PHONEX—The estimated x-coordinate of the call location as provided by the wireless network provider
- PHONEY—The estimated y-coordinate of the call location as provided by the wireless network provider
If the SUBSCRIBER field record is null, it will be ignored and will not be imported into the output feature classes.
If the STARTTIME and DURATION fields have values and the ENDTIME field does not, the tool will generate an ENDTIME value in the output feature classes.
If the STARTTIME and ENDTIME fields have values and the DURATION field does not, the tool will generate a DURATION value in the output feature classes.
The Timing Advance Band Output Options parameters (Start Timing Advance Distance Field, End Timing Advance Distance Field, Timing Advance Distance Unit, Timing Advance Band Total Width, and Output Timing Advance Bands) are optional and not necessary for associating call detail records to cell tower and sector locations.
Some cell phone records include timing advance data that can be used to identify the distance of a phone from a cell tower at the time of a call. If timing advance data exists in the records, this tool can create a polygon feature class containing a band representing the distance of the phone from the cell site along the beamwidth arc of the sector in which a call occurred.
The output timing advance bands will contain all the associated fields of the Output Phone Records Site Points and Output Phone Records Site Sectors parameter values.
The following fields will be added to the Output Timing Advance Bands parameter:
- TASTART—The timing advance distance at the start of the call as provided by the wireless network provider. This field is added to the output when the Start Timing Advance Distance Field parameter is specified.
- TAEND—The timing advance distance at the end of the call as provided by the wireless network provider. This field is added to the output when the End Timing Advance Distance Field parameter is specified.
- TATYPE—The field identifying whether the timing advance band is located at the start or end timing distance from the cell site. This field is added to the output when the Start Timing Advance Distance Field and End Timing Advance Distance Field parameters are specified.
  - START—The value assigned when the band is located at the start timing distance
  - END—The value assigned when the band is located at the end timing distance

Parameters

Label	Explanation	Data Type
Input Phone Records Table	The input table containing call records or phone data event records provided by the wireless network provider.	Table View
Input Cell Site Points	The feature class containing cell site points generated by the Cell Site Records to Feature Class tool.	Feature Layer
Input Cell Site Sectors	The feature class containing cell site sectors generated by the Cell Site Records to Feature Class tool.	Feature Layer
Output Phone Record Site Points	The point feature class containing phone record site points. One point will be generated per phone record linked to cell site points.	Feature Class
Output Phone Record Sectors	The polygon feature class containing phone record sectors. One sector polygon will be generated per phone record linked to cell site sectors.	Feature Class
Cell Sector ID Fields	Specifies the unique ID field type and the fields that will be added to the output feature. Use the Unique ID type when the Input Phone Records Table parameter value has a unique identifier for all cell sector antennas. Use a combination of other ID Type values when the Input Phone Records Table parameter value does not contain a universal unique identifier for all cell sector antennas. ID Type—The field name to be included in the output feature classes. Field—The name of the fields that uniquely identify the cell sector antennas. These will be added to the output feature class. ID Type options are as follows: Unique ID—Uniquely identifies a cell sector antenna Site ID—Uniquely identifies a cell site Sector ID—Uniquely identifies a cell sector Switch ID—Uniquely identifies a wireless network switch LAC ID—Uniquely identifies the Location Area Code Cascade ID—Uniquely identifies the sector in the wireless network cascade Cell ID—Identifies the sector within an Location Area Code	Value Table
Subscriber ID Field	The field in the input table that contains the phone number or identifier of the subscriber.	Field
Destination Phone Number Field (Optional)	The field in the input table that contains the phone number or identifier of the callee.	Field
Additional Cell Sector ID Fields (Optional)	Specifies the additional unique ID field type and the fields that will be added to the output feature. Use the Unique ID type when the Input Phone Records Table parameter value has a unique identifier for all cell sector antennas. Use a combination of other ID Type values when the Input Phone Records Table parameter value does not contain a universal unique identifier for all cell sector antennas. ID Type—The field name to be included in the output feature classes. Field—The name of the fields that uniquely identify the cell sector antennas. These will be added to the output feature class. ID Type options are as follows: Unique ID—Uniquely identifies a cell sector antenna Site ID—Uniquely identifies a cell site Sector ID—Uniquely identifies a cell sector Switch ID—Uniquely identifies a wireless network switch LAC ID—Uniquely identifies the Location Area Code Cascade ID—Uniquely identifies the sector in the wireless network cascade Cell ID—Identifies the sector within an Location Area Code	Value Table
Start Date and Time Field (Optional)	The field in the input table that contains the start date and time field of the phone call or data event.	Field
Duration Field (Optional)	The field in the input table that contains the duration of the phone call in seconds.	Field
End Date and Time Field (Optional)	The field in the input table that contains the end date and time of the phone call or data event.	Field
Convert UTC Dates to Local Time Zone (Optional)	Specifies whether the start and end date and time of the input records will be converted to the time zone of the local system or will remain in coordinated universal time (UTC). Checked—The start and end date and time of the input records will be converted from UTC to the time zone of the local system. Unchecked—The start and end date and time will not be converted. This is the default.	Boolean
Estimated Phone Location X Field (Optional)	The field in the input table that contains the x-coordinate of the estimated phone location as provided by the wireless network provider.	Field
Estimated Phone Location Y Field (Optional)	The field in the input table that contains the y-coordinate of the estimated phone location as provided by the wireless network provider.	Field
Estimated Phone Location Coordinate System (Optional)	The estimated phone location coordinate system of the x,y-coordinates. The default coordinate system is WGS84.	Coordinate System
Output Estimated Call Points (Optional)	The point feature class containing the estimated call locations as provided by the wireless network provider.	Feature Class
Start Timing Advance Distance Field (Optional)	The field in the input table that contains the timing advance distance at the start of the call.	Field
End Timing Advance Distance Field (Optional)	The field in the input table that contains the timing advance distance at the end of the call.	Field
Timing Advance Distance Unit (Optional)	Specifies the linear unit of measurement that will be used for the Start Timing Advance Distance Field and End Timing Advance Distance Field parameter values. Kilometers—The unit will be kilometers. Meters—The unit will be meters. Statute Miles—The unit will be statute miles. International Yards—The unit will be international yards. International Feet—The unit will be international feet. US Survey Miles—The unit will be US Survey miles. This is the default. US Survey Yards—The unit will be US Survey yards. US Survey Feet—The unit will be US Survey feet.	String
Timing Advance Band Total Width (Optional)	The full width of the timing advance band. The default is 78.07 meters.	Linear Unit
Output Timing Advance Bands (Optional)	The polygon feature class that will contain the timing advance bands as provided by the wireless network provider.	Feature Class

arcpy.ca.CellPhoneRecordsToFeatureClass(in_table, in_site_features, in_sector_features, out_site_feature_class, out_sector_feature_class, id_fields, subscriber_field, {destination_field}, {additional_id_fields}, {start_time_field}, {duration_field}, {end_time_field}, {convert_utc}, {location_x_field}, {location_y_field}, {location_coordinate_system}, {out_call_points}, {start_timing_distance_field}, {end_timing_distance_field}, {timing_advance_unit}, {timing_band_width}, {out_timing_advance_bands})

Name	Explanation	Data Type
in_table	The input table containing call records or phone data event records provided by the wireless network provider.	Table View
in_site_features	The feature class containing cell site points generated by the Cell Site Records to Feature Class tool.	Feature Layer
in_sector_features	The feature class containing cell site sectors generated by the Cell Site Records to Feature Class tool.	Feature Layer
out_site_feature_class	The point feature class containing phone record site points. One point will be generated per phone record linked to cell site points.	Feature Class
out_sector_feature_class	The polygon feature class containing phone record sectors. One sector polygon will be generated per phone record linked to cell site sectors.	Feature Class
id_fields [id_fields,...]	Specifies the unique ID field type and the fields that will be added to the output feature. Use the Unique ID type when the Input Phone Records Table parameter value has a unique identifier for all cell sector antennas. Use a combination of other ID Type values when the Input Phone Records Table parameter value does not contain a universal unique identifier for all cell sector antennas. ID Type—The field name to be included in the output feature classes. Field—The name of the fields that uniquely identify the cell sector antennas. These will be added to the output feature class. ID Type options are as follows: Unique ID—Uniquely identifies a cell sector antenna Site ID—Uniquely identifies a cell site Sector ID—Uniquely identifies a cell sector Switch ID—Uniquely identifies a wireless network switch LAC ID—Uniquely identifies the Location Area Code Cascade ID—Uniquely identifies the sector in the wireless network cascade Cell ID—Identifies the sector within an Location Area Code	Value Table
subscriber_field	The field in the input table that contains the phone number or identifier of the subscriber.	Field
destination_field (Optional)	The field in the input table that contains the phone number or identifier of the callee.	Field
additional_id_fields [additional_id_fields,...] (Optional)	Specifies the additional unique ID field type and the fields that will be added to the output feature. Use the Unique ID type when the Input Phone Records Table parameter value has a unique identifier for all cell sector antennas. Use a combination of other ID Type values when the Input Phone Records Table parameter value does not contain a universal unique identifier for all cell sector antennas. ID Type—The field name to be included in the output feature classes. Field—The name of the fields that uniquely identify the cell sector antennas. These will be added to the output feature class. ID Type options are as follows: Unique ID—Uniquely identifies a cell sector antenna Site ID—Uniquely identifies a cell site Sector ID—Uniquely identifies a cell sector Switch ID—Uniquely identifies a wireless network switch LAC ID—Uniquely identifies the Location Area Code Cascade ID—Uniquely identifies the sector in the wireless network cascade Cell ID—Identifies the sector within an Location Area Code	Value Table
start_time_field (Optional)	The field in the input table that contains the start date and time field of the phone call or data event.	Field
duration_field (Optional)	The field in the input table that contains the duration of the phone call in seconds.	Field
end_time_field (Optional)	The field in the input table that contains the end date and time of the phone call or data event.	Field
convert_utc (Optional)	Specifies whether the start and end date and time of the input records will be converted to the time zone of the local system or will remain in coordinated universal time (UTC). CONVERT—The start and end date and time of the input records will be converted from UTC to the time zone of the local system. NO_CONVERT—The start and end date and time of the input records will not be converted. This is the default.	Boolean
location_x_field (Optional)	The field in the input table that contains the x-coordinate of the estimated phone location as provided by the wireless network provider.	Field
location_y_field (Optional)	The field in the input table that contains the y-coordinate of the estimated phone location as provided by the wireless network provider.	Field
location_coordinate_system (Optional)	The estimated phone location coordinate system of the x,y-coordinates. The default coordinate system is WGS84.	Coordinate System
out_call_points (Optional)	The point feature class containing the estimated call locations as provided by the wireless network provider.	Feature Class
start_timing_distance_field (Optional)	The field in the input table that contains the timing advance distance at the start of the call.	Field
end_timing_distance_field (Optional)	The field in the input table that contains the timing advance distance at the end of the call.	Field
timing_advance_unit (Optional)	Specifies the linear unit of measurement that will be used for the start_timing_distance_field and End Timing Advance Distance Field parameter values. KILOMETERS—The unit will be kilometers. METERS—The unit will be meters. MILESINT—The unit will be statute miles. YARDSINT—The unit will be international yards. FEETINT—The unit will be international feet. MILES—The unit will be US Survey miles. This is the default. YARDS—The unit will be US Survey yards. FEET—The unit will be US Survey feet.	String
timing_band_width (Optional)	The full width of the timing advance band. The default is 78.07 meters.	Linear Unit
out_timing_advance_bands (Optional)	The polygon feature class that will contain the timing advance bands as provided by the wireless network provider.	Feature Class

Code sample

CellPhoneRecordsToFeatureClass example 1 (Python window)

The following Python window script demonstrates how to use the CellPhoneRecordsToFeatureClass function in immediate mode:

import arcpy
arcpy.env.workspace = r"C:/data/city_pd.gdb"
arcpy.ca.CellPhoneRecordsToFeatureClass("CDR_Phone_1",
                                        "Phone_1_Sites",
                                        "Phone_1_Sectors",
                                        "CDR_Phone_1_Sites_out",
                                        "CDR_Phone_1_Sectors_out",
                                        "SWITCH_ID BEGSWITCH;SITE_ID BEGSITE;SECTOR_ID BEGSECTOR",
                                        "SUBSCRIBERID")

CellPhoneRecordsToFeatureClass example 2 (stand-alone window)

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

# Name: CellPhoneRecordsToFeatureClass.py
# Description: Imports cell phone records then associates those records with a 
#              cell site and sector feature classes based on identifier fields.

# Import system modules 
import arcpy

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

# Set local variables
in_table = "CDR_Phone_1"
in_sites = "Phone_1_Sites"
in_sectors = "Phone_1_Sectors"
out_cdr_sites = "CDR_Phone_1_Sites_out"
out_cdr_sectors = "CDR_Phone_1_Sectors_out"

# Set up Beginning of Phone IDs
# [ID Type, Field]
begin_switch_id = ["SWITCH_ID","BEGSWITCH"]
begin_site_id = ["SITE_ID","BEGSITE"]
begin_sector_id = ["SECTOR_ID","BEGSECTOR"]
begin_id_fields = [begin_switch_id, begin_site_id, begin_sector_id]
subscriber_field = "SUBSCRIBERID"
destination_field = "DESTNUM"

# Set up End of Phone Call IDs
# [ID Type, Field]
end_switch_id = ["SWITCH_ID","ENDSWITCH"]
end_site_id = ["SITE_ID","ENDSITE"]
end_sector_id = ["SECTOR_ID","ENDSECTOR"]
end_id_fields = [end_switch_id, end_site_id, end_sector_id]

# Input Table Contains information about the duration of the call
start_date_field = "DATETIME"
duration_field = "DURATION"

arcpy.ca.CellPhoneRecordsToFeatureClass(in_table,
                                        in_sites,
                                        in_sectors,
                                        out_cdr_sites,
                                        out_cdr_sectors,
                                        begin_id_fields,
                                        subscriber_field,
                                        destination_field,
                                        end_id_fields,
                                        start_date_field,
                                        duration_field)

Licensing information

Basic: Yes
Standard: Yes
Advanced: Yes

Summary

Usage

Parameters

Code sample

Environments

Licensing information

Related topics

In this topic