Summary
This ArcGIS Online service determines network service areas around facilities. 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. For instance, the 10-minute service area for a facility includes all the streets that can be reached within 10 minutes from that facility.
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.
Illustration
Usage
The tool creates drive-time areas if the value for the Break Units parameter is set to a time unit. Similarly, the tool creates drive-distance areas if the Break Units are distance units. The tool can generate up to 300-minute or 300-mile (482.80-kilometer) service areas. When generating detailed polygons, the maximum service-area size is limited to 15 minutes and 15 miles (24.14 kilometers).
You need to specify at least one facility to successfully execute the tool. You can load up to 1,000 facilities.
You can add up to 250 point barriers. You can add any number of line or polygon barriers, but line barriers cannot intersect more than 500 street features, and polygon barriers can't intersect more than 2,000 features.
You can choose to use the road hierarchy when solving so that results are generated faster, but the solution may be somewhat less accurate.
Regardless of whether the Use Hierarchy parameter is checked (True), hierarchy is always used when the largest break value exceeds 240 minutes or 240 miles (386.24 kilometers). When the output service areas aren't overlapping and generalized, this limit is reduced to 15 minutes and 15 miles (24.14 kilometers).
If the distance between an input point and its nearest traversable street is greater than 12.42 miles (20 kilometers), the point is excluded from the analysis.
This tool is designed to run in ArcGIS Pro, ArcMap, ArcGlobe, and ArcScene, but not in ArcCatalog.
Syntax
GenerateServiceAreas_naagol (Facilities, Break_Values, Break_Units, {Analysis_Region}, Travel_Direction, Time_of_Day, Use_Hierarchy, UTurn_at_Junctions, Polygons_for_Multiple_Facilities, Polygon_Overlap_Type, {Detailed_Polygons}, Polygon_Trim_Distance, Polygon_Simplification_Tolerance, Point_Barriers, {Line_Barriers}, Polygon_Barriers, Restrictions, {Attribute_Parameter_Values}, {Time_Zone_for_Time_of_Day}, {Travel_Mode}, {Impedance}, {Service_Areas})| Parameter | Explanation | Data Type |
Facilities | The facilities around which service areas are generated. You can load up to 1,000 facilities. The facilities feature set has an associated attribute table. The fields in the attribute table are listed below and described. ObjectID: The system-managed ID field. Name: The name of the facility. If the name is not specified, a name is automatically generated at solve time. All fields from the input facilities are included in the output polygons when the Polygons for Multiple Facilities parameter is set to Overlapping or Not Overlapping. The ObjectID field on the input facilities is transferred to the FacilityOID field on the output polygons. | 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. 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, type 2 3 5, separating the values with a space, and set Break Units to Miles. There is no limit to the number of break values you specify. The size of the maximum break value can't exceed the equivalent of 300 minutes or 300 miles (482.80 kilometers). When generating detailed polygons, the maximum service-area size is limited to 15 minutes and 15 miles (24.14 kilometers). | String |
Break_Units | The unit for the Break Values parameter. The units you choose for this parameter determine whether the tool will create service areas by measuring driving distance or driving time. Choose a time unit to measure driving time. To measure driving distance, choose a distance unit. Your choice also determines in which units the tool will report total driving time or distance in the results. The choices are:
| String |
Analysis_Region (Optional) | Specify the region in which to perform the analysis. If a value is not specified for this parameter, the tool will automatically calculate the region name based on the location of the input points. Setting the name of the region is recommended to speed up the tool execution. To specify a region, use one of the following values:
| String |
Travel_Direction | Specifies 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 streets may differ or one-way restrictions may exist, such as one-way streets. 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. | String |
Time_of_Day | 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.
You can use the Time Zone for Time of Day parameter to specify whether this time and date refers to UTC or the time zone in which the facility is located. 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 |
Use_Hierarchy | Specify whether hierarchy should be used when finding the best route between the facility and the incident.
Regardless of whether the Use Hierarchy parameter is checked (True), hierarchy is always used when the largest break value exceeds 240 minutes or 240 miles (386.24 kilometers). | Boolean |
UTurn_at_Junctions |
Use this parameter to restrict or permit the service area to make U-turns at junctions. In order to understand the parameter values, consider for a moment the following terminology: a junction is a point where a street segment ends and potentially connects to one or more other segments; a pseudo-junction is a point where exactly two streets connect to one another; an intersection is a point where three or more streets connect; and a dead-end is where one street segment ends without connecting to another. Given this information, the parameter can have the following values:
| String |
Polygons_for_Multiple_Facilities | Choose how service area polygons are generated when multiple facilities are present in the analysis.
When using Overlapping or Not Overlapping, all fields from the input facilities are included in the output polygons, with the exception that values from the input ObjectID field are transferred to the FacilityOID field of the output polygons. The FacilityOID field is null when merging by break value, and the input fields are not included in the output. | String |
Polygon_Overlap_Type | 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.
If your facilities are in an urban area with a grid-like street network, the difference between generalized and detailed service areas would be minimal. However, if your facilities are in a region containing mountain and rural roads, the detailed service areas may present significantly more accurate results than generalized service areas. The tool supports generating detailed polygons only if the largest value specified in the Break Values parameter is less than or equal to 15minutes or 15 miles (24.14 kilometers). | Boolean |
Polygon_Trim_Distance | Specifies the distance within which the service area polygons are trimmed. This is useful when finding service areas in places that have a sparse street network and you don't want the service area to cover large areas where there are no street features. The default value is 100 meters. No value or a value of 0 for this parameter specifies that the service area polygons should not be trimmed. This parameter value is ignored when using hierarchy. | Linear unit |
Polygon_Simplification_Tolerance | Specify by how much you want to simplify the polygon geometry. Simplification maintains critical vertices of a polygon to define its essential shape and removes other vertices. The simplification distance you specify is the maximum offset the simplified polygon boundaries can deviate from the original polygon boundaries. Simplifying a polygon reduces the number of vertices and tends to reduce drawing times. | Linear unit |
Point_Barriers | Specify one or more points to act as temporary restrictions or represent additional time or distance that may be required to travel on the underlying streets. For example, a point barrier can be used to represent a fallen tree along a street or time delay spent at a railroad crossing. The tool imposes a limit of 250 points that can be added as barriers. When specifying the point barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The point barriers can be specified with the following attributes: Name: The name of the barrier. BarrierType: Specifies whether the point barrier restricts travel completely or adds time or distance when it is crossed. The value for this attribute is specified as one of the following integers (use the numeric code, not the name in parentheses):
Additional_Time: Indicates how much travel time is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the Break Units value is time based. This field value must be greater than or equal to zero, and its units are the same as those specified in the Break Units parameter. Additional_Distance: Indicates how much distance is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the Break Units value is distance based. The field value must be greater than or equal to zero, and its units are the same as those specified in the Break Units parameter. | Feature Set |
Line_Barriers (Optional) | Specify one or more lines that prohibit travel anywhere the lines intersect the streets. For example, a parade or protest that blocks traffic across several street segments can be modeled with a line barrier. A line barrier can also quickly fence off several roads from being traversed, thereby channeling possible routes away from undesirable parts of the street network. The tool imposes a limit on the number of streets you can restrict using the Line Barriers parameter. While there is no limit on the number of lines you can specify as line barriers, the combined number of streets intersected by all the lines cannot exceed 500. When specifying the line barriers, you can set a name property for each one by using the following attribute: Name: The name of the barrier. | Feature Set |
Polygon_Barriers | Specify polygons that either completely restrict travel or proportionately scale the time or distance required to travel on the streets intersected by the polygons. The service imposes a limit on the number of streets you can restrict using the Polygon Barriers parameter. While there is no limit on the number of polygons you can specify as the polygon barriers, the combined number of streets intersected by all the polygons should not exceed 2,000. When specifying the polygon barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The polygon barriers can be specified with the following attributes: Name: The name of the barrier. BarrierType: Specifies whether the barrier restricts travel completely or scales the time or distance for traveling through it. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):
ScaledTimeFactor: This is the factor by which the travel time of the streets intersected by the barrier is multiplied. This field is applicable only for scaled-cost barriers and only if the Break Units value is time based. The field value must be greater than zero and its units are the same as those specified in the Break Units parameter. ScaledDistanceFactor: This is the factor by which the distance of the streets intersected by the barrier is multiplied. This attribute is applicable only for scaled-cost barriers and only if the Break Units value is distance based. The attribute value must be greater than zero. | Feature Set |
Restrictions | Specify which travel restrictions should be honored by the tool when determining the service areas. A restriction represents a driving preference or requirement. In most cases, restrictions cause roads to be prohibited. For instance, using an Avoid Toll Roads restriction will result in a route that will include toll roads only when it is absolutely required to travel on toll roads in order to visit an incident or a facility. Height Restriction makes it possible to route around any clearances that are lower than the height of your vehicle. If you are carrying corrosive materials on your vehicle, using the Any Hazmat Prohibited restriction prevents hauling the materials along roads where it is marked as illegal to do so. When generating detailed polygons, prohibited roads aren't covered by service area polygons may result in polygons with untraversable holes; however, when generating general or hierarchical service areas, restricted roads that are completely surrounded by traversable roads will be covered by the simplified service area polygon. Below is a list of available restrictions and a short description. The tool supports the following restrictions:
| String |
Attribute_Parameter_Values (Optional) | Specify additional values required by some restrictions, such as the weight of a vehicle for Weight Restriction. You can also use the attribute parameter to specify whether any restriction prohibits, avoids, or prefers travel on roads that use the restriction. If the restriction is meant to avoid or prefer roads, you can further specify the degree to which they are avoided or preferred using this parameter. For example, you can choose to never use toll roads, avoid them as much as possible, or even highly prefer them. If you specify the Attribute Parameter Values parameter from a feature class, the field names on the feature class must match the fields as described below: AttributeName: Lists the name of the restriction. ParameterName: Lists the name of the parameter associated with the restriction. A restriction can have one or more ParameterName field values based on its intended use. ParameterValue: The value for ParameterName used by the tool when evaluating the restriction. Attribute Parameter Values is dependent on the Restrictions parameter. The ParameterValue field is applicable only if the restriction name is specified as the value for the Restrictions parameter. In Attribute Parameter Values, each restriction (listed as AttributeName) has a ParameterName field value, Restriction Usage, that specifies whether the restriction prohibits, avoids, or prefers travel on the roads associated with the restriction and the degree to which the roads are avoided or preferred. The Restriction Usage ParameterName can be assigned any of the following string values or their equivalent numeric values listed within the parentheses:
In most cases, you can use the default value, PROHIBITED, for the Restriction Usage if the restriction is dependent on a vehicle-characteristic such as vehicle height. However, in some cases, the value for Restriction Usage depends on your routing preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage parameter. This means that when the restriction is used, the tool will try to route around toll roads when it can. AVOID_MEDIUM also indicates how important it is to avoid toll roads when finding the best route; it has a medium priority. Choosing AVOID_LOW would put lower importance on avoiding tolls; choosing AVOID_HIGH instead would give it a higher importance and thus make it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED would entirely disallow travel on toll roads, making it impossible for a route to travel on any portion of a toll road. Keep in mind that avoiding or prohibiting toll roads, and thus avoiding toll payments, is the objective for some; in contrast, others prefer to drive on toll roads because avoiding traffic is more valuable to them than the money spent on tolls. In the latter case, you would choose PREFER_LOW, PREFER_MEDIUM, or PREFER_HIGH as the value for Restriction Usage. The higher the preference, the farther the tool will go out of its way to travel on the roads associated with the restriction. | Record Set |
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 to model in the analysis.
For modeling a custom truck mode, you would follow the steps listed below.
For modeling a pedestrian with specific routing requirements, you would follow the same procedure as setting up a custom truck mode, but with the following differences:
| String |
Impedance (Optional) | Specify the impedance, which is a value that represents the effort or cost of traveling along road segments or on other parts of the transportation network. Travel distance is an impedance; the length of a road in kilometers can be thought of as impedance. Travel distance in this sense is the same for all modes—a kilometer for a pedestrian is also a kilometer for a car. (What may change is the pathways on which the different modes are allowed to travel, which affects distance between points, and this is modeled by travel mode settings.) Travel time can also be an impedance; a car may take one minute to travel a mile along an empty road. Travel times can vary by travel mode—a pedestrian may take more than 20 minutes to walk the same mile, so it is important to choose the right impedance for the travel mode you are modeling. Choose from the following impedance values:
The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. If you choose Drive Time, Truck Time, or Walk Time, the Measurement Units parameter must be set to a time-based value; if you choose Travel Distance for Impedance, Measurement Units must be distance-based. | String |
Service_Areas (Optional) | Please ignore this parameter—it is for internal use only. | Feature Class |
Code sample
GenerateServiceAreas example
The following Python script demonstrates how to use the GenerateServiceAreas tool in a script.
import arcpy
import time
import sys
username = "<your user name>"
password = "<your password>"
sa_service = "http://logistics.arcgis.com/arcgis/services;World/ServiceAreas;{0};{1}".format(username, password)
#Add the geoprocessing service as a toolbox. Use an alias when importing
arcpy.ImportToolbox(sa_service, "agol")
#Set the variables to call the tool
facilities = r"C:/data/Inputs.gdb/Stores"
output_service_areas = "C:/data/Results.gdb/StoreServiceAreas"
#Call the tool
result = arcpy.agol.GenerateServiceAreas(facilities, "5 10 15", "Minutes")
#Check the status of the result object every 0.5 seconds
#until it has a value of 4(succeeded) or greater
while result.status < 4:
time.sleep(0.5)
#print any warning or error messages returned from the tool
result_severity = result.maxSeverity
if result_severity == 2:
print "An error occured when running the tool"
print result.getMessages(2)
sys.exit(2)
elif result_severity == 1:
print "Warnings were returned when running the tool"
print result.getMessages(1)
#Get the output routes and save to a local geodatabase
result.getOutput(0).save(output_service_areas)
Environments
This tool does not use any geoprocessing environments