Generate Service Areas (Network Analyst)

License Level:BasicStandardAdvanced

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 three-minute drive-time polygon around a grocery store can determine which residents are able to reach the store within three minutes and are thus more likely to shop there.

NoteNote:

The Generate Service Areas and Make Service Area Layer tools are similar, but they are designed for different purposes. Use Generate Service Areas if you are setting up a geoprocessing service; it will simplify the setup process. Otherwise, use Make Service Area Layer. Also, use Make Service Area Layer if you need to generate service area lines; Generate Service Areas doesn't provide the option to generate lines.

To create a service-area geoprocessing service using Generate Service Areas, you only need to set up one tool, and you can publish the tool directly as a service. In contrast, you need to create a model with the Make Service Area Layer, properly connect it to various other tools, and publish the model to create a service-area geoprocessing service.

See Geoprocessing service example: Drive-time polygons to learn how to set up a drive-time polygons service using tutorial data.

Usage

Syntax

GenerateServiceAreas_na (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})
ParameterExplanationData 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 Unit value, like seconds or minutes, the tool solves using the cost attribute defined in the Time Attribute parameter. When you specify a distance-based Break Unit value, like 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.

  • Minutes
  • Hours
  • Days
  • Seconds
  • Miles
  • Kilometers
  • Meters
  • Feet
  • NauticalMiles
  • Yards

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 service area analysis will be performed. 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.

  • TRAVEL_FROMThe service area is generated in the direction away from the facilities.
  • TRAVEL_TOThe service area is created in the direction towards 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.

  • It represents the departure time if Travel Direction is set to TRAVEL_FROM.
  • It represents the arrival time if Travel Direction is set to TRAVEL_TO.

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 five-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, 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.

  • ALLOW_UTURNSU-turns are permitted at junctions with any number of connected edges. This is the default value.
  • NO_UTURNSU-turns are prohibited at all junctions, regardless of junction valency. Note, however, that U-turns are still permitted at network locations even when this setting is chosen; however, you can set the individual network locations' CurbApproach property to prohibit U-turns there as well.
  • ALLOW_DEAD_ENDS_ONLYU-turns are prohibited at all junctions, except those that have only one adjacent edge (a dead end).
  • ALLOW_DEAD_ENDS_AND_INTERSECTIONS_ONLYU-turns are prohibited at junctions where exactly two adjacent edges meet but are permitted at intersections (junctions with three or more adjacent edges) and dead ends (junctions with exactly one adjacent edge). Oftentimes, networks have extraneous junctions in the middle of road segments. This option prevents vehicles from making U-turns at these locations.
TipTip:

If you need a more precisely defined U-turn policy, consider adding a global turn delay evaluator to a network cost attribute, or adjusting its settings if one exists, and pay particular attention to the configuration of reverse turns. Also, look at setting the CurbApproach property of your network locations.

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:

  • Restriction (0)—Prohibits traversing through the barrier. This is the default value.
  • Added Cost (2)—Traversing through the barrier increases the network cost by the amount specified in the Additional_Time and AdditionalDistance fields.

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:

  • Restriction (0)—Prohibits traversing through any part of the barrier. This is the default value.
  • Scaled Cost (1)—Scales the impedance of underlying edges by multiplying them by the value of the ScaledCostFactor property. If edges are partially covered by the barrier, the impedance is apportioned and multiplied.

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.

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.

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.

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.

String
Use_Hierarchy_in_Analysis
(Optional)
  • USE_HIERARCHY Use the hierarchy attribute for the analysis. Using a hierarchy results in the solver preferring higher-order edges to lower-order edges. Hierarchical solves are faster, and they can be used to simulate the preference of a driver who chooses to travel on freeways over local roads when possible—even if that means a longer trip. This option is valid only if the input network dataset has a hierarchy attribute.
  • NO_HIERARCHYDo not use the hierarchy attribute for the analysis. Not using a hierarchy yields a service area measured along all edges of the network dataset regardless of hierarchy level.

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.

Boolean
Restrictions
(Optional)

Indicates which network restriction attributes are respected during solve time.

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 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)
  • EXCLUDEFacilities are only located on traversable portions of the network. This prevents locating them on elements that can't be reached during the solve process due to restrictions or barriers. Bear in mind that facilities may be located farther from their intended location than if this option were left unchecked.
  • INCLUDEFacilities can be located on any of the elements of the network; however, the facilities that are located on restricted elements cannot be used during the solve process.
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.

  • NO_MERGECreates individual polygons for each facility. The polygons can overlap each other.
  • NO_OVERLAP Creates individual polygons such that a polygon from one facility cannot overlap polygons from other facilities; furthermore, any portion of the network can only be covered by the service area of the nearest facility.
  • MERGE Creates and joins the polygons of different facilities that have the same break value.
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.

  • RINGSDoes not include the area of the smaller breaks. This creates polygons going between consecutive breaks. Use this option if you want to find the area from one break to another. For instance, If you create 5- and 10-minute service areas, then the 10-minute service area polygon will exclude the area under the 5-minute service area polygon.
  • DISKS Creates polygons going from the facility to the break. For instance, If you create 5- and 10-minute service areas, then the 10-minute service area polygon will include the area under the 5-minute service area polygon.
String
Detailed_Polygons
(Optional)

Specifies the option to create detailed or generalized polygons.

  • SIMPLE_POLYSCreates generalized polygons, which are generated quickly and are fairly accurate. This is the default.
  • DETAILED_POLYSCreates detailed polygons, which accurately model the service area lines and may contain islands of unreached areas. This option is much slower than generating generalized polygons. This option isn't supported when using hierarchy.
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 the simplified polygon can deviate from. 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

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 (workflow)

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 occured on line %i" % tb.tb_lineno
    print str(e)

Environments

Related Topics

Licensing Information

ArcGIS for Desktop Basic: Requires Network Analyst
ArcGIS for Desktop Standard: Requires Network Analyst
ArcGIS for Desktop Advanced: Requires Network Analyst
1/20/2015