SolveLocationAllocation (LocationAllocation)
Summary
The SolveLocationAllocation tool chooses the best location or locations from a set of input locations.
Input to this tool includes facilities, which provide goods or services, and demand points, which consume the goods and services. The objective is to find the facilities that supply the demand points most efficiently. The tool solves this problem by analyzing various ways the demand points can be assigned to the different facilities. The solution is the scenario that allocates the most demand to facilities and minimizes overall travel. The output includes the solution facilities, demand points associated with their assigned facilities, and lines connecting demand points to their facilities.
The location-allocation tool can be configured to solve specific problem types. Examples include the following:
A retail store wants to see which potential store locations would need to be developed to capture 10 percent of the retail market in the area.
A fire department wants to determine where it should locate fire stations to reach 90 percent of the community within a four-minute response time.
A police department wants to preposition personnel given past criminal activity at night.
After a storm, a disaster-response agency wants to find the best locations to set up triage facilities, with limited patient capacities, to tend to the affected population.
Illustration
Usage
-
The tool chooses the best facilities based on travel time if the value for the Measurement Units parameter is time based. It's based on travel distance if the measurement units are distance based.
You need to specify at least one facility and one demand point to successfully execute the tool. You can load up to 1,000 facilities and 10,000 demand points.
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 cannot intersect more than 2,000 features.
You can choose to use the road hierarchy when solving so results are generated faster, but the solution may be somewhat less than optimal.
Regardless of whether the Use Hierarchy parameter is checked (True), hierarchy is always used when the straight-line distance between any pair of features representing demand points or facilities is greater than 50 miles (80.46 kilometers).
The straight-line distance between any pair of features representing demand points or facilities cannot be greater than 50 miles (80.46 kilometers) when Travel Mode is set to Walking, or when it is set to Custom and the Walking restriction is used.
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.
Syntax
| Parameter | Explanation | Data Type |
Facilities |
Specify one or more facilities (up to 1,000). The tool chooses the best locations from the set of facilities you specify here. In a competitive analysis, in which you try to find the best locations in the face of competition, the facilities of the competitors are specified here too. When defining the facilities, you can set properties for each one, such as the facility name or type, by using attributes. Facilities can be specified with the following attributes: Name—The name of the facility. The name is included in the name of output allocation lines if the facility is part of the solution. FacilityType—Specifies whether the facility is a candidate, required, or competitor facility. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):
Weight—The relative weighting of the facility, which is used to rate the attractiveness, desirability, or bias of one facility compared to another. For example, a value of 2.0 could capture the preference of customers who prefer, at a ratio of 2 to 1, shopping in one facility over another facility. Factors that potentially affect facility weight include square footage, neighborhood, and age of the building. Weight values other than one are only honored by the Maximize Market Share and Target Market Share problem types; they are ignored in other problem types. Capacity—The Capacity field is specific to the Maximize Capacitated Coverage problem type; the other problem types ignore this field. Capacity specifies how much weighted demand the facility is capable of supplying. Excess demand won't be allocated to a facility even if that demand is within the facility's default measurement cutoff. Any value assigned to the Capacity field overrides the Default_Capacity parameter for the given facility. CurbApproach—Specifies the direction a vehicle may arrive at or depart from the facility. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):
The CurbApproach property is designed to work with both kinds of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider a facility on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach a facility from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, if you want to arrive at a facility and not have a lane of traffic between the vehicle and the incident, you would choose Right side of vehicle (1) in the United States but Left side of vehicle (2) in the United Kingdom. | Feature Set |
Demand_Points |
Specify one or more demand points (up to 10,000). The tool chooses the best facilities based in large part on how they serve the demand points specified here. When defining the demand points, you can set properties for each one, such as the demand-point name or weight, by using attributes. Demand points can be specified with the following attributes: Name—The name of the demand point. The name is included in the name of an output allocation line or lines if the demand point is part of the solution. GroupName—The name of the group the demand point is part of. This property is ignored for the maximize capacitated coverage, target market share, and maximize market share problem types. If demand points share a group name, the solver allocates all members of the group to the same facility. (If constraints, such as a cutoff distance, prevent any of the demand points in the group from reaching the same facility, none of the demand points are allocated.) Weight—The relative weighting of the demand point. A value of 2.0 means the demand point is twice as important as one with a weight of 1.0. If demand points represent households, weight could indicate the number of people in each household. Cutoff_Time—The demand point can't be allocated to a facility that is beyond the travel time indicated here. This field value overrides the value of the Default Measurement Cutoff parameter. The units for this attribute value are specified by the Measurement Units parameter. The attribute value is referenced during the analysis only when the measurement units are time based. The default value is null, which means there isn't an override cutoff. Cutoff_Distance—The demand point can't be allocated to a facility that is beyond the travel distance indicated here. This field value overrides the value of the Default Measurement Cutoff parameter. The units for this attribute value are specified by the Measurement Units parameter. The attribute value is referenced during the analysis only when the measurement units are distance based. The default value is null, which means there isn't an override cutoff. CurbApproach—Specifies the direction a vehicle may arrive at or depart from the demand point. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):
The CurbApproach property is designed to work with both kinds of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider a demand point on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach a demand point from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, if you want to arrive at a demand point and not have a lane of traffic between the vehicle and the demand point, you would choose Right side of vehicle (1) in the United States but Left side of vehicle (2) in the United Kingdom. | Feature Set |
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 |
Measurement_Units |
Specify the units that should be used to measure the travel times or travel distances between demand points and facilities. The tool chooses the best facilities based on which ones can reach, or be reached by, the most amount of weighted demand with the least amount travel. The output allocation lines report travel distance or travel time in different units, including the units you specify for this parameter. The choices are:
| String |
Problem_Type (Optional) |
Specifies the objective of the location-allocation analysis. The default objective is to minimize impedance.
| String |
Number_of_Facilities_to_Find (Optional) |
Specify the number of facilities the solver should choose. The default value is 1. The facilities with a FacilityType field value of 1 (Required) are always chosen first. Any excess facilities to choose are picked from candidate facilities, which have a FacilityType field value of 2. Any facilities that have a FacilityType value of 3 (Chosen) before solving are treated as candidate facilities at solve time. If the number of facilities to find is less than the number of required facilities, an error occurs. Number of Facilities to Find is disabled for the Minimize Facilities and Target Market Share problem types since the solver determines the minimum number of facilities needed to meet the objectives. | Long |
Default_Measurement_Cutoff (Optional) |
Specifies the maximum travel time or distance allowed between a demand point and the facility it is allocated to. If a demand point is outside the cutoff of a facility, it cannot be allocated to that facility. The default value is none, which means the cutoff limit doesn't apply. The units for this parameter are the same as those specified by the Measurement Units parameter. The travel time or distance is measured by the shortest path along roads. This property might be used to model the maximum distance that people are willing to travel to visit stores or the maximum time that is permitted for a fire department to reach anyone in the community. Note that demand points have Cutoff_Time and Cutoff_Distance fields, which, if set accordingly, overrides the Default Measurement Cutoff parameter. You might find that people in rural areas are willing to travel up to 10 miles to reach a facility while urbanites are only willing to travel up to two miles. Assuming Measurement Units is set to Miles, you can model this behavior by setting the default measurement cutoff to 10 and the Cutoff_Distance field value of the demand points in urban areas to 2. | Double |
Default_Capacity (Optional) |
This property is specific to the Maximize Capacitated Coverage problem type. It is the default capacity assigned to all facilities in the analysis. You can override the default capacity for a facility by specifying a value in the facility's Capacity field. The default value is 1. | Double |
Target_Market_Share (Optional) |
This parameter is specific to the Target Market Share problem type. It is the percentage of the total demand weight that you want the chosen and required facilities to capture. The solver chooses the minimum number of facilities needed to capture the target market share specified here. The default value is 10 percent. | Double |
Measurement_Transformation_Model (Optional) |
This sets the equation for transforming the network cost between facilities and demand points. This property, coupled with the Impedance Parameter, specifies how severely the network impedance between facilities and demand points influences the solver's choice of facilities. In the following list of transformation options, d refers to demand points and f, facilities. "Impedance" refers to the shortest travel distance or time between two locations. So impedancedf is the shortest-path (time or distance) between demand point d and facility f, and costdf is the transformed travel time or distance between the facility and demand point. Lambda (λ) denotes the impedance parameter. The Measurement Units setting determines whether travel time or distance is analyzed.
| String |
Measurement_Transformation_Factor (Optional) |
Provides a parameter value to the equations specified in the Impedance Transformation Model parameter. The parameter value is ignored when the impedance transformation is of type linear. For power and exponential impedance transformations, the value should be nonzero. | Double |
Travel_Direction (Optional) | Specify whether to measure travel times or distances from facilities to demand points or from demand points to facilities. The default value is to measure from facilities to demand points.
Travel times and distances may change based on direction of travel. If going from point A to point B, you may encounter less traffic or have a shorter path, due to one-way streets and turn restrictions, than if you were traveling in the opposite direction. For instance, going from point A to point B may only take 10 minutes, but going the other direction may take 15 minutes. These differing measurements may affect whether demand points can be assigned to certain facilities because of cutoffs or, in problem types where demand is apportioned, affect how much demand is captured. Fire departments commonly measure from facilities to demand points since they are concerned with the time it takes to travel from the fire station to the location of the emergency. A retail store is more concerned with the time it takes shoppers to reach the store; therefore, stores commonly measure from demand points to facilities. Travel Direction also determines the meaning of any start time that is provided. See the Time of Day parameter for more information. | String |
Time_of_Day (Optional) |
Specify the time at which travel begins. This property is ignored unless Measurement Units are time based. The default is no time or date. When Time of Day isn't specified, the solver uses generic speeds—typically those from posted speed limits. Traffic is constantly changing in reality, and as it changes, travel times between facilities and demand points also fluctuate. Therefore, indicating different time and date values over several analyses may affect how demand is allocated to facilities and which facilities are chosen in the results. The time of day always indicates a start time. However, travel may start from facilities or demand points; it depends on what you choose for the Travel Direction parameter. The Time Zone for Time of Day parameter specifies whether this time and date refer to UTC or the time zone in which the facility or demand point is located. | Date |
Time_Zone_for_Time_of_Day (Optional) | Specifies the time zone of the Time of Day parameter. The default is geographically local.
Irrespective of the Time Zone for Time of Day setting, the following rules are enforced by the tool if your facilities and demand points are in multiple time zones:
| String |
UTurn_at_Junctions (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, or streets, 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.
| String |
Point_Barriers (Optional) |
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 measurement units are time based. This field value must be greater than or equal to zero, and its units are the same as those specified in the Measurement 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 measurement units are distance based. The field value must be greater than or equal to zero, and its units are the same as those specified in the Measurement 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 (Optional) |
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 measurement units are time based. The field value must be greater than zero. 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 measurement units are distance based. The attribute value must be greater than zero. | Feature Set |
Use_Hierarchy (Optional) | Specify whether hierarchy should be used when finding the shortest path between the facilities and demand points.
The tool automatically reverts to using hierarchy if the straight-line distance between facilities and demand points is greater than 50 miles, even if you have set this parameter to not use hierarchy. | Boolean |
Restrictions (Optional) |
Specify which restrictions should be honored by the tool when finding the best routes between facilities and demand points. 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. Below is a list of available restrictions and a short description.  Note:Some restrictions require an additional value to be specified for their desired use. This value needs to be associated with the restriction name and a specific parameter intended to work with the restriction. You can identify such restrictions if their names appear under the AttributeName column in the Attribute Parameter Values parameter. The ParameterValue field should be specified in the Attribute Parameter Values parameter for the restriction to be correctly used when finding traversable roads. Note:Some restrictions are supported only in certain countries; their availability is stated by region in the list below. Of the restrictions that have limited availability within a region, you can check whether the restriction is available in a particular country by looking at the table in the Country List section of the Data coverage for network analysis services web page. If a country has a value of Yes in the Logistics Attribute column, the restriction with select availability in the region is supported in that country. If you specify restriction names that are not available in the country where your incidents are located, the service ignores the invalid restrictions. The service also ignores restrictions whose Restriction Usage parameter value is between 0 and 1 (see the Attribute Parameter Value parameter). It prohibits all restrictions whose Restriction Usage parameter value is greater than 0. 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. Note:The values you provide for this parameter are ignored unless Travel Mode is set to Custom. 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 |
Allocation_Line_Shape (Optional) |
The default is to output straight lines. Specify the type of line features that are output by the tool. The parameter accepts one of the following values:
No matter which value you choose for the Allocation Line Shape parameter, the shortest route is always determined by minimizing the travel time or the travel distance, never using the straight-line distance between incidents and facilities. That is, this parameter only changes the output line shapes; it doesn't change the measurement method. | 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. 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 |
Code Sample
The following Python script demonstrates how to use the SolveLocationAllocation tool in a script.
import arcpy
import time
import sys
username = "<your user name>"
password = "<your password>"
LA_service = "http://logistics.arcgis.com/arcgis/services;World/LocationAllocation;{0};{1}".format(username, password)
#Add the geoprocessing service as a toolbox. Use an alias when importing
arcpy.ImportToolbox(LA_service, "agol")
#Set the variables to call the tool
facilities = r'C:/data/Inputs.gdb/Stores'
demandPoints = r'C:/data/Inputs.gdb/Customers'
output_lines = r'C:/data/Results.gdb/Lines'
output_facilities = r'C:/data/Results.gdb/Facilities'
output_demandPoints = r'C:/data/Results.gdb/DemandPoints'
#Call the tool
result = arcpy.agol.SolveLocationAllocation(facilities, demandPoints, "Minutes",
Problem_Type="Maximize Attendance",
Number_of_Facilities_to_Find=2,
Default_Measurement_Cutoff=10.0)
#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(1).save(output_lines)
result.getOutput(2).save(output_facilities)
result.getOutput(3).save(output_demandPoints)