Summary
Creates a service area network analysis layer, sets the analysis properties, and solves the analysis. This tool is ideal for setting up a service area geoprocessing service on the web. A network service area is a region that encompasses all streets that can be accessed within a given distance or travel time from one or more facilities.
Service areas are commonly used to visualize and measure accessibility. For example, a 3-minute drive-time polygon around a grocery store can determine which residents are able to reach the store within 3 minutes and are thus more likely to shop there.
Usage
The tool dialog box groups the various optional parameters into the following six categories to make it easier for you to manage them:
- Advanced Analysis
- Barriers
- Custom Travel Mode
- Network Locations
- Polygon Generation
- Service Capabilities
Syntax
GenerateServiceAreas(Facilities, Break_Values, Break_Units, Network_Dataset, Service_Areas, {Travel_Direction}, {Time_of_Day}, {UTurn_Policy}, {Point_Barriers}, {Line_Barriers}, {Polygon_Barriers}, {Time_Attribute}, {Time_Attribute_Units}, {Distance_Attribute}, {Distance_Attribute_Units}, {Use_Hierarchy_in_Analysis}, {Restrictions}, {Attribute_Parameter_Values}, {Maximum_Snap_Tolerance}, {Exclude_Restricted_Portions_of_the_Network}, {Feature_Locator_WHERE_Clause}, {Polygons_for_Multiple_Facilities}, {Polygon_Overlap_Type}, {Detailed_Polygons}, {Polygon_Trim_Distance}, {Polygon_Simplification_Tolerance}, {Maximum_Facilities}, {Maximum_Number_of_Breaks}, {Maximum_Features_Affected_by_Point_Barriers}, {Maximum_Features_Affected_by_Line_Barriers}, {Maximum_Features_Affected_by_Polygon_Barriers}, {Maximum_Break_Time_Value}, {Maximum_Break_Distance_Value}, {Force_Hierarchy_beyond_Break_Time_Value}, {Force_Hierarchy_beyond_Break_Distance_Value}, {Save_Output_Network_Analysis_Layer}, {Time_Zone_for_Time_of_Day}, {Travel_Mode}, {Overrides})
Parameter | Explanation | Data Type |
Facilities | The facilities around which service areas are generated. The facilities feature set has three attributes: ObjectID: The system-managed ID field. Shape: The geometry field indicating the geographic location of the network analysis object. Name: The name of the facility. If the name is empty, blank, or null, a name is automatically generated at solve time. | Feature Set |
Break_Values | Specifies the size and number of service area polygons to generate for each facility. The units are determined by the Break Units value. When the Generate Service Areas tool runs, a noteworthy interaction occurs among the following parameters: Break Values, Break Units, and either Time Attribute or Distance Attribute. Together, Break Values and Break Units define how far or how long the service area should extend around the facility or facilities. The Time Attribute and Distance Attribute parameters each define one network cost attribute. Only one of these two cost attributes is used, however, and the one that the solver chooses to use corresponds with the Break Units value; that is, when you specify a time-based Break Units value, such as seconds or minutes, the tool solves using the cost attribute defined in the Time Attribute parameter. When you specify a distance-based Break Units value, such as kilometers or miles, it uses the cost attribute defined in the Distance Attribute parameter. Multiple polygon breaks can be set to create concentric service areas per facility. For instance, to find 2-, 3-, and 5-mile service areas for each facility, enter 2 3 5, separating the values with a space. Set Break Units to Miles and ensure that you have chosen a distance-based network attribute for the Distance Attribute parameter. | String |
Break_Units | The units for the Break Values parameter.
The Generate Service Areas tool chooses whether to use the network cost attribute specified in the Time Attribute or Distance Attribute parameter depending on whether the units you specify here are time or distance based. The tool performs the necessary units conversion when the Break Units value differs from the units of the corresponding time or distance cost attribute. | String |
Network_Dataset | The network dataset on which the analysis will be performed. Network datasets most often represent street networks but may represent other kinds of transportation networks as well. The network dataset needs at least one time-based and one distance-based cost attribute. | Network Dataset Layer |
Service_Areas | The output workspace and name of the output features. This workspace must already exist. The default output workspace is in_memory. | Feature Class |
Travel_Direction (Optional) | Choose whether the direction of travel used to generate the service area polygons is toward or away from the facilities.
The direction of travel may change the shape of the polygons because impedances on opposite sides of a street may differ, or one-way streets may exist. The direction you should choose depends on the nature of your service area analysis. The service area for a pizza delivery store, for example, should be created away from the facility, whereas the service area of a hospital should be created toward the facility since the critical travel time for a patient is traveling to the hospital. | String |
Time_of_Day (Optional) | The time to depart from or arrive at the facilities. The interpretation of this value depends on whether travel is toward or away from the facilities.
Your network dataset must include traffic data for this parameter to have any effect. Repeatedly solving the same analysis, but using different Time of Day values, allows you to see how a facility's reach changes over time. For instance, the 5-minute service area around a fire station may start out large in the early morning, diminish during the morning rush hour, grow in the late morning, and so on, throughout the day. | Date |
UTurn_Policy (Optional) | The U-Turn policy at junctions. Allowing U-turns implies the solver can turn around at a junction and double back on the same street. Given that junctions represent street intersections and dead ends, different vehicles may be able to turn around at some junctions but not at others—it depends on whether the junction represents an intersection or dead end. To accommodate this, the U-turn policy parameter is implicitly specified by how many edges connect to the junction, which is known as junction valency. The acceptable values for this parameter are listed below; each is followed by a description of its meaning in terms of junction valency.
The value of this parameter is overridden when Travel Mode (Travel_Mode in Python) is set to any value other than custom. | String |
Point_Barriers (Optional) | Specifies point barriers, which are split into two types: restriction and added cost point barriers. They temporarily restrict traversal across or add impedance to points on the network. The point barriers are defined by a feature set, and the attribute values you specify for the point features determine whether they are restriction or added cost barriers. The fields in the attribute table are listed and described below. ObjectID: The system-managed ID field. Shape: The geometry field indicating the geographic location of the network analysis object. Name: The name of the barrier. BarrierType: Specifies whether the barrier restricts travel completely or adds cost when traveling through it. There are two options:
Use the value 0 for Restriction and 2 for Added Cost. AdditionalCost: AdditionalCost indicates how much impedance is added when a service area passes through the barrier. The unit for this field value is the same as the units specified for Break Units. | Feature Set |
Line_Barriers (Optional) |
Specifies line barriers, which temporarily restrict traversal across them. The line barriers are defined by a feature set. The fields in the attribute table are listed and described below. ObjectID: The system-managed ID field. Shape: The geometry field indicating the geographic location of the network analysis object. Name: The name of the barrier. | Feature Set |
Polygon_Barriers (Optional) | Specifies polygon barriers, which are split into two types: restriction and scaled cost polygon barriers. They temporarily restrict traversal or scale impedance on the parts of the network they cover. The polygon barriers are defined by a feature set, and the attribute values you specify for the polygon features determine whether they are restriction or scaled cost barriers. The fields in the attribute table are listed and described below. ObjectID: The system-managed ID field. Shape: The geometry field indicating the geographic location of the network analysis object. Name: The name of the barrier. BarrierType: Specifies whether the barrier restricts travel completely or scales the cost of traveling through it. There are two options:
Use the value 0 for Restriction and 1 for Scaled Cost. ScaledCostFactor: ScaledCostFactor indicates how much the impedance is multiplied by when a service area passes through the barrier. | Feature Set |
Time_Attribute (Optional) | Defines the network cost attribute to use when the Break Units value is a time unit. The tool performs the necessary time-unit conversion when the Break Units value differs from the units of the cost attribute defined here. In other words, the time units of the breaks and the network cost attribute don't need to be the same. The value of this parameter is overridden when Travel Mode (Travel_Mode in Python) is set to any value other than custom. | String |
Time_Attribute_Units (Optional) | The units of the network cost attribute specified by the Time Attribute parameter. This is merely an informational parameter that cannot be changed without directly editing the network dataset. It is also unnecessary to change since the unit conversions between break value units and the cost attribute are handled for you. The value of this parameter is overridden when Travel Mode (Travel_Mode in Python) is set to any value other than custom. | String |
Distance_Attribute (Optional) | Defines the network cost attribute to use when the Break Units value is a distance unit. The tool performs the necessary distance-unit conversion when the Break Units value differs from the units of the cost attribute defined here. In other words, the distance units of the breaks and the network cost attribute don't need to be the same. The value of this parameter is overridden when Travel Mode (Travel_Mode in Python) is set to any value other than custom. | String |
Distance_Attribute_Units (Optional) | The units of the network cost attribute specified by the Distance Attribute parameter. This is merely an informational parameter that cannot be changed without directly editing the network dataset. It is also unnecessary to change since the unit conversions between break value units and the cost attribute are handled for you. The value of this parameter is overridden when Travel Mode (Travel_Mode in Python) is set to any value other than custom. | String |
Use_Hierarchy_in_Analysis (Optional) |
The parameter is disabled if a hierarchy attribute is not defined on the network dataset used to perform the analysis. You can use the Force Hierarchy Beyond Distance parameter to force the solver to use hierarchy even if Use Hierarchy in Analysis is set to false. This parameter is ignored unless Travel Mode is set to Custom. When modeling a custom walking mode, it is recommended to turn off hierarchy since the hierarchy is designed for motorized vehicles.
The parameter is not used if a hierarchy attribute is not defined on the network dataset used to perform the analysis. In such cases, use "#" as the parameter value. You can use the Force_Hierarchy_Beyond_Distance parameter to force the solve to use hierarchy even if Use_Hierarchy_in_Analysis is set to False. This parameter is ignored unless Travel_Mode is set to CUSTOM. When modeling a custom walking mode, it is recommended to turn off hierarchy since the hierarchy is designed for motorized vehicles. | Boolean |
Restrictions [restriction,...] (Optional) | Indicates which network restriction attributes are respected during solve time. The value of this parameter is overridden when Travel Mode (Travel_Mode in Python) is set to any value other than custom. | String |
Attribute_Parameter_Values (Optional) | Specifies the parameter values for network attributes that have parameters. The record set has two columns that work together to uniquely identify parameters and another column that specifies the parameter value. The value of this parameter is overridden when Travel Mode (Travel_Mode in Python) is set to any value other than custom. The attribute parameter values record set has associated attributes. The fields in the attribute table are listed below and described. ObjectID: The system-managed ID field. AttributeName: The name of the network attribute whose attribute parameter is set by the table row. ParameterName: The name of the attribute parameter whose value is set by the table row. (Object type parameters cannot be updated using this tool.) ParameterValue: The value you want for the attribute parameter. If a value is not specified, the attribute parameter is set to null. | Record Set |
Maximum_Snap_Tolerance (Optional) | The maximum snap tolerance is the furthest distance that Network Analyst searches when locating or relocating a point onto the network. The search looks for suitable edges or junctions and snaps the point to the nearest one. If a suitable location isn't found within the maximum snap tolerance, the object is marked as unlocated. | Linear Unit |
Exclude_Restricted_Portions_of_the_Network (Optional) |
| Boolean |
Feature_Locator_WHERE_Clause (Optional) | An SQL expression used to select a subset of source features that limits which network elements facilities can be located on. The syntax for this parameter consists of two parts: the first is the source feature class name (followed by a space), and the second is the SQL expression. To write an SQL expression for two or more source feature classes, separate them with a semicolon. To ensure facilities are not located on limited-access highways, for example, write an SQL expression like the following to exclude those source features: "Streets" "FUNC_CLASS not in('1', '2')". Note that barriers ignore the feature locator WHERE clause when loading. | String |
Polygons_for_Multiple_Facilities (Optional) | Choose how service area polygons are generated when multiple facilities are present in the analysis.
| String |
Polygon_Overlap_Type (Optional) | Specifies the option to create concentric service area polygons as disks or rings. This option is applicable only when multiple break values are specified for the facilities.
| String |
Detailed_Polygons (Optional) | Specifies the option to create detailed or generalized polygons.
| Boolean |
Polygon_Trim_Distance (Optional) | Specifies the distance within which the service area polygons are trimmed. This is useful when your data is very sparse and you don't want the service area to cover large areas where there are no features. No value or a value of 0 for this parameter specifies that the service area polygons should not be trimmed. The parameter value is ignored when using hierarchy. | Linear Unit |
Polygon_Simplification_Tolerance (Optional) |
Specify by how much you want to simplify the polygon geometry. Simplification maintains critical points of a polygon to define its essential shape and removes other points. The simplification distance you specify is the maximum allowable offset from the original polygon from which the simplified polygon can deviate. Simplifying a polygon reduces the number of vertices and tends to reduce drawing times. | Linear Unit |
Maximum_Facilities (Optional) | Limits how many facilities can be added to the service area analysis. This parameter helps you govern the amount of processing that occurs when solving. For example, you could assign a low value to this parameter for a free version of the service you are creating and use a higher value for a paid-subscription version of the service. A null value indicates there is no limit. | Long |
Maximum_Number_of_Breaks (Optional) | Limits how many breaks can be added to the service area analysis. This parameter helps you govern the amount of processing that occurs when solving. For example, you could assign a low value to this parameter for a free version of the service you are creating and use a higher value for a paid-subscription version of the service. A null value indicates there is no limit. | Long |
Maximum_Features_Affected_by_Point_Barriers (Optional) | Limits how many features can be affected by point barriers. This parameter helps you govern the amount of processing that occurs when solving. For example, you could assign a low value to this parameter for a free version of the service you are creating and use a higher value for a paid-subscription version of the service. A null value indicates there is no limit. | Long |
Maximum_Features_Affected_by_Line_Barriers (Optional) |
Limits how many features can be affected by line barriers. This parameter helps you govern the amount of processing that occurs when solving. For example, you could assign a low value to this parameter for a free version of the service you are creating and use a higher value for a paid-subscription version of the service. A null value indicates there is no limit. | Long |
Maximum_Features_Affected_by_Polygon_Barriers (Optional) |
Limits how many features can be affected by polygon barriers. This parameter helps you govern the amount of processing that occurs when solving. For example, you could assign a low value to this parameter for a free version of the service you are creating and use a higher value for a paid-subscription version of the service. A null value indicates there is no limit. | Long |
Maximum_Break_Time_Value (Optional) | Limits how large the value of the Break Value parameter can be when solving time-based service areas. This parameter helps you govern the amount of processing that occurs when solving. For example, you could assign a low value to this parameter for a free version of the service you are creating and use a higher value for a paid-subscription version of the service. A null value indicates there is no limit. | Double |
Maximum_Break_Distance_Value (Optional) | Limits how large the value of the Break Value parameter can be when solving distance-based service areas. This parameter helps you govern the amount of processing that occurs when solving. For example, you could assign a low value to this parameter for a free version of the service you are creating and use a higher value for a paid-subscription version of the service. A null value indicates there is no limit. | Double |
Force_Hierarchy_beyond_Break_Time_Value (Optional) | Specifies the break value after which the solver will force hierarchy even if hierarchy was not enabled when solving time-based service areas. Solving service areas for high break values while using the network's hierarchy tends to incur much less processing than solving the same service areas without using the hierarchy. This parameter helps you govern the amount of processing that occurs when solving. A null value indicates that the hierarchy will never be enforced and the value of the Use Hierarchy in Analysis parameter will always be honored. If the input network dataset does not support hierarchy, specifying a value for this parameter will result in an error. A null value should be used in this case. | Double |
Force_Hierarchy_beyond_Break_Distance_Value (Optional) | Specifies the break value after which the solver will force hierarchy even if hierarchy was not enabled when solving distance-based service areas. Solving service areas for high break values while using the network's hierarchy tends to incur much less processing than solving the same service areas without using the hierarchy. This parameter helps you govern the amount of processing that occurs when solving. A null value indicates that the hierarchy will never be enforced and the value of the Use Hierarchy in Analysis parameter will always be honored. If the input network dataset does not support hierarchy, specifying a value for this parameter will result in an error. A null value should be used in this case. | Double |
Save_Output_Network_Analysis_Layer (Optional) |
In either case, a feature class with service area polygons is returned. However, a server administrator may want to choose to output a network analysis layer as well so the setup and results of the tool can be debugged using the Network Analyst controls in the ArcGIS Desktop environment. This can make the debugging process much easier. In ArcGIS Desktop, the default output location for the network analysis layer is in the scratch folder. You can determine the location of the scratch folder by evaluating the value of the arcpy.env.scratchFolder geoprocessing environment. The output network analysis layer is stored as an LYR file whose name starts with _ags_gpna and is followed by an alphanumeric GUID. | Boolean |
Time_Zone_for_Time_of_Day (Optional) | Specifies the time zone or zones of the Time of Day parameter.
Irrespective of the Time Zone for Time of Day setting, all facilities must be in the same time zone when Time of Day has a nonnull value and Polygons for Multiple Facilities is set to create merged or nonoverlapping polygons. | String |
Travel_Mode (Optional) | Choose the mode of transportation for the analysis. CUSTOM is always a choice. For other travel mode names to appear, they must be present in the network dataset specified in the Network_Dataset parameter. (The arcpy.na.GetTravelModes function provides a dictionary of the travel mode objects configured on a network dataset, and the name property returns the name of a travel mode object.) A travel mode is defined on a network dataset and provides override values for parameters that, together, model car, truck, pedestrian, or other modes of travel. By choosing a travel mode here, you don't need to provide values for the following parameters, which are overridden by values specified in the network dataset:
| String |
Overrides (Optional) | Additional settings that can be used to influence the behavior of the solver. The value for this parameter is specified in JavaScript Object Notation (JSON) using the form {"overrideSetting1" : "value1", "overrideSetting2" : "value2"}. The override setting names are always enclosed in double quotation marks. The values can be a number, Boolean, or a string. | String |
Derived Output
Name | Explanation | Data Type |
Output_Service_Areas | The area that can be reached from the input location within a given travel time or travel distance. | Feature Set |
Solve_Succeeded | Determines whether solving the service area analysis succeeded. | Boolean |
Output_Network_Analysis_Layer | Network analysis layer with properties as configured in the tool parameters that can be used for further analysis or debugging in the map. | File |
Code sample
GenerateServiceAreas example 1 (Python window)
Execute the tool using the required parameters from the Python window.
import arcpy
facilities = arcpy.FeatureSet()
facilities.load("FireStations")
arcpy.na.GenerateServiceAreas(facilities, "1 2 3", "Minutes", "Streets_ND",
"in_memory\\FireStationServiceAreas")
GenerateServiceAreas example 2 (stand-alone script)
The following stand-alone Python script demonstrates how GenerateServiceAreas can be used to determine a store's reach over time. It shows how to generate a 5-minute service area around a store location at different times in a day. Such analyses can be useful—for example, for a pizza store—to see how the area that can be reached within 5 minutes from the store changes based on the current traffic conditions.
# Name: GenerateServiceAreas_Workflow.py
# Description: Generate a 5 minute service area around a store location at
# different times in a day. Such analysis can be useful, for example
# for a pizza store, to see how the area that can be reached within
# 5 minutes from the store changes based on the current traffic
# conditions.
# Requirements: Network Analyst Extension
#Import system modules
import arcpy
from arcpy import env
import datetime
try:
#Check out the Network Analyst extension license
arcpy.CheckOutExtension("Network")
#Set environment settings
env.workspace = "C:/data/SanFrancisco.gdb"
env.overwriteOutput = True
#Set local variables
inNetworkDataset = "Transportation/Streets_ND"
impedanceAttribute = "TravelTime"
breakValues = "5"
breakUnits = "Minutes"
inFacilities = "Analysis/ExistingStore"
outGeodatabase = "C:/data/output/ServiceAreaOutput.gdb"
serviceArea = "in_memory\\ServiceAreas"
dateFieldName = "StartTime"
nameField = "Name"
#use today at 8 AM as the start time and then increment it by one hour
startTime = datetime.datetime(1899,12,30,8,0,0)
#Create a new feature set with same schema as Facilities parameter in
#Generate Service Areas tool. Load the feature from the ExistingStore
#feature class in the feature set
facilities = arcpy.GetParameterValue("GenerateServiceAreas_na",0)
facilities.load(inFacilities)
#Create an empty feature class with same spatial reference as the
#network dataset and a Date field called StartTime and a text field called Name
outServiceAreas = arcpy.management.CreateFeatureclass(outGeodatabase, "ServiceAreas",
"POLYGON","","","",
inNetworkDataset).getOutput(0)
arcpy.management.AddField(outServiceAreas, dateFieldName, "DATE")
arcpy.management.AddField(outServiceAreas, nameField, "TEXT")
#Open an insert cursor on the feature class to add new polygons
cursor = arcpy.da.InsertCursor(outServiceAreas, ("SHAPE@", nameField,
dateFieldName))
#Geneate a 5 minute service area around the store at every one hour interval
#from 8 AM to 8 PM. Copy the output service area to a new feature class
for i in range(1,14):
timeFormat = startTime.time().strftime("%I %p")
print "Generating {0} {1} service area at {2}".format(breakValues,breakUnits,
timeFormat)
arcpy.na.GenerateServiceAreas(facilities,breakValues,breakUnits,
inNetworkDataset, serviceArea, "TRAVEL_FROM",
startTime, Time_Attribute=impedanceAttribute)
#Get the shape from the output service area so that it can be inserted
#in the feature class
with arcpy.da.SearchCursor(serviceArea,("SHAPE@", nameField)) as inputRows:
row = inputRows.next()
cursor.insertRow((row[0],row[1],startTime))
startTime = startTime + datetime.timedelta(seconds=3600)
del cursor
print "Script completed successfully"
except Exception as e:
# If an error occurred, print line number and error message
import traceback, sys
tb = sys.exc_info()[2]
print "An error occurred on line %i" % tb.tb_lineno
print str(e)
Environments
Licensing information
- Basic: Requires Network Analyst
- Standard: Requires Network Analyst
- Advanced: Requires Network Analyst