Solve Location Allocation (Ready To Use)

Summary

The Solve Location Allocation tool chooses the best location or locations from a set of input locations, by assigning demand points to input facilities in a way that allocates the most demand to facilities and minimizes overall travel.

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.

Caution:

For up-to-date information about this tool, see the most recent edition of this topic in the web help. ArcGIS Online makes regular functional updates to services such as this, so the installed help may become outdated.

Learn about the output from Solve Location Allocation

Illustration

Locating shelters for emergency management

Usage

  • Tools in the Ready To Use toolbox areArcGIS Online geoprocessing services that use ArcGIS Online's hosted data and analysis capabilities.

  • 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 use the road hierarchy when solving so results are generated quicker, but the solution may be 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 27 miles (43.45 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 more than 12.42 miles (20 kilometers), the point is excluded from the analysis.

  • Using this service consumes credits. For more information, see Service Credits Overview.

Syntax

SolveLocationAllocation(Facilities, Demand_Points, Measurement_Units, {Analysis_Region}, {Problem_Type}, {Number_of_Facilities_to_Find}, {Default_Measurement_Cutoff}, {Default_Capacity}, {Target_Market_Share}, {Measurement_Transformation_Model}, {Measurement_Transformation_Factor}, {Travel_Direction}, {Time_of_Day}, {Time_Zone_for_Time_of_Day}, {UTurn_at_Junctions}, Point_Barriers, Line_Barriers, Polygon_Barriers, {Use_Hierarchy}, Restrictions, {Attribute_Parameter_Values}, {Allocation_Line_Shape}, {Travel_Mode}, {Impedance}, {Save_Output_Network_Analysis_Layer}, {Overrides}, {Time_Impedance}, {Distance_Impedance}, {Output_Format})
ParameterExplanationData Type
Facilities

Specify one or more facilities that the solver will choose from during the analysis. The solver identifies the best facilities to allocate demand in the most efficient way according to the problem type and criteria you specify.

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 as well.

When defining the facilities, you can set properties for each—such as its name or type—using 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 a competitor facility. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Candidate)—A facility that may be part of the solution.
  • 1 (Required)—A facility that must be part of the solution.
  • 2 (Competitor)—A rival facility that potentially removes demand from your facilities. Competitor facilities are specific to the maximize market share and target market share problem types; they are ignored in other problem types.

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 may 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.

Cutoff

The impedance value at which to stop searching for demand points from a given facility. The demand point can't be allocated to a facility that is beyond the value indicated here.

This attribute allows you to specify a different cutoff value for each demand point. For example, you may 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 2 miles. You can model this behavior by setting the Cutoff value for all demand points that are in rural areas to 10 and setting the Cutoff value of the demand points in urban areas to 2.

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 (Default_Capacity in Python) 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):

  • 0 (Either side of vehicle)—The facility can be visited from either the right or left side of the vehicle.
  • 1 (Right side of vehicle)—Arrive at or depart the facility so it is on the right side of the vehicle. This is typically used for vehicles such as buses that must arrive with the bus stop on the right-hand side so passengers can disembark at the curb.
  • 2 (Left side of vehicle)—Arrive at or depart the facility so it is on the left side of the vehicle. When the vehicle approaches and departs the facility, the curb must be on the left side of the vehicle. This is typically used for vehicles such as buses that must arrive with the bus stop on the left-hand side so passengers can disembark at the curb.

The CurbApproach attribute is designed to work with both types 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, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

Bearing

The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

Learn more about bearing and bearing tolerance

BearingTol

The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the value from the Bearing field is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

Learn more about bearing and bearing tolerance

NavLatency

This field is only used in the solve process if Bearing and BearingTol also have values; however, entering a NavLatency value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much time is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

The time units of NavLatency are the same as the units specified by the timeUnits property of the analysis object.

Feature Set
Demand_Points

Specify one or more demand points. The solver identifies the best facilities based in large part on how they serve the demand points specified here.

A demand point is typically a location that represents the people or things requiring the goods and services your facilities provide. A demand point may be a ZIP Code centroid weighted by the number of people residing within it or by the expected consumption generated by those people. Demand points can also represent business customers. If you supply businesses with a high turnover of inventory, they will be weighted more heavily than those with a low turnover rate.

When specifying the demand points, you can set properties for each—such as its name or weight—using the following attributes:

Name

The name of the demand point. The name is included in the name of the output allocation line or lines if the demand point is part of the solution.

GroupName

The name of the group to which the demand point belongs. This field 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, for example, weight can indicate the number of people in each household.

Cutoff

The impedance value at which to stop searching for demand points from a given facility. The demand point can't be allocated to a facility that is beyond the value indicated here.

This attribute allows you to specify a cutoff value for each demand point. For example, you may find that people in rural areas are willing to travel up to 10 miles to reach a facility, while those in urban areas are only willing to travel up to 2 miles. You can model this behavior by setting the Cutoff value for all demand points that are in rural areas to 10 and setting the Cutoff value of the demand points in urban areas to 2.

The units for this attribute value are specified by the Measurement Units parameter.

A value for this attribute overrides the default set for the analysis using the Default Measurement Cutoff parameter. The default value is Null, which results in using the default value set by the Default Measurement Cutoff parameter for all the demand points.

ImpedanceTransformation

A value for this attribute overrides the default set for the analysis by the Measurement Transformation Model parameter.

ImpedanceParameter

A value for this attribute overrides the default set for the analysis by the Measurement Transformation Factor parameter.

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):

  • 0 (Either side of vehicle)—The demand point can be visited from either the right or left side of the vehicle.
  • 1 (Right side of vehicle)—Arrive at or depart the demand point so it is on the right side of the vehicle. When the vehicle approaches and departs the demand point, the curb must be on the right side of the vehicle. This is typically used for vehicles such as buses that must arrive with the bus stop on the right-hand side so passengers can disembark at the curb.
  • 2 (Left side of vehicle)—Arrive at or depart the demand point so it is on the left side of the vehicle. When the vehicle approaches and departs the demand point, the curb must be on the left side of the vehicle. This is typically used for vehicles such as buses that must arrive with the bus stop on the left-hand side so passengers can disembark at the curb.

The CurbApproach attribute is designed to work with both types 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, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

Bearing

The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

Learn more about bearing and bearing tolerance

BearingTol

The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the value from the Bearing field is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

Learn more about bearing and bearing tolerance

NavLatency

This field is only used in the solve process if Bearing and BearingTol also have values; however, entering a NavLatency value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much time is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

The time units of NavLatency are the same as the units specified by the timeUnits property of the analysis object.

Feature Set
Measurement_Units

Specify the units that will be used to measure the travel times or travel distances between demand points and facilities. The tool finds the best facilities based on those that 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 options are as follows:

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

String
Analysis_Region
(Optional)

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 required only if the automatic detection of the region name is not accurate for your inputs.

To specify a region, use one of the following values:

  • Europe
  • Japan
  • Korea
  • MiddleEastAndAfrica
  • NorthAmerica
  • SouthAmerica
  • SouthAsia
  • Thailand

Legacy:

The following region names are no longer supported and will be removed in future releases. If you specify one of the deprecated region names, the tool automatically assigns a supported region name for your region.

  • Greece redirects to Europe
  • India redirects to SouthAsia
  • Oceania redirects to SouthAsia
  • SouthEastAsia redirects to SouthAsia
  • Taiwan redirects to SouthAsia

String
Problem_Type
(Optional)

Specifies the objective of the location-allocation analysis. The default objective is to minimize impedance.

  • Minimize Impedance—This is also known as the P-Median problem type. Facilities are located such that the sum of all weighted travel time or distance between demand points and solution facilities is minimized. (Weighted travel is the amount of demand allocated to a facility multiplied by the travel distance or time to the facility.)

    This problem type is traditionally used to locate warehouses, because it can reduce the overall transportation costs of delivering goods to outlets. Since minimize impedance reduces the overall distance the public needs to travel to reach the chosen facilities, the minimize impedance problem without an impedance cutoff is typically regarded as more equitable than other problem types for locating some public-sector facilities such as libraries, regional airports, museums, department of motor vehicles offices, and health clinics.

    The following list describes how the minimize impedance problem type handles demand:

    • A demand point that cannot reach any facilities due to setting a cutoff distance or time is not allocated.
    • A demand point that can only reach one facility has all its demand weight allocated to that facility.
    • A demand point that can reach two or more facilities has all its demand weight allocated to the nearest facility only.

  • Maximize Coverage—Facilities are located such that as much demand as possible is allocated to solution facilities within the impedance cutoff.

    Maximize coverage is frequently used to locate fire stations, police stations, and ERS centers, because emergency services are often required to arrive at all demand points within a specified response time. Note that it is important for all organizations, and critical for emergency services, to have accurate and precise data so analysis results correctly model real-world results.

    Pizza delivery businesses, as opposed to eat-in pizzerias, try to locate stores where they can cover the most people within a certain drive time. People who order pizzas for delivery don't typically worry about how far away the pizzeria is; they are mainly concerned with the pizza arriving within an advertised time window. Therefore, a pizza-delivery business would subtract pizza-preparation time from their advertised delivery time and solve a maximize coverage problem to choose the candidate facility that will capture the most potential customers in the coverage area. (Potential customers of eat-in pizzerias are more affected by distance, since they need to travel to the restaurant; thus, the attendance maximizing and market share problem types are better suited to eat-in restaurants.)

    The following list describes how the maximize coverage problem type handles demand:

    • A demand point that cannot reach any facilities due to cutoff distance or time is not allocated.
    • A demand point that can only reach one facility has all its demand weight allocated to that facility.
    • A demand point that can reach two or more facilities has all its demand weight allocated to the nearest facility only.

  • Maximize Capacitated Coverage—Facilities are located such that all or the greatest amount of demand can be served without exceeding the capacity of any facility.

    Maximize capacitated coverage behaves similar to the minimize impedance and maximize coverage problem types but with the added constraint of capacity. You can specify a capacity for an individual facility by assigning a numeric value to its corresponding Capacity field on the input facilities. If the Capacity field value is null, the facility is assigned a capacity from the Default Capacity property.

    Use cases for the maximize capacitated coverage problem type include creating territories that encompass a given number of people or businesses, locating hospitals or other medical facilities with a limited number of beds or patients who can be treated, and locating warehouses whose inventory isn't assumed to be unlimited.

    The following list describes how the maximize capacitated coverage problem type handles demand:

    • Unlike maximize coverage, maximize capacitated coverage doesn't require a value for the Default Measurement Cutoff parameter; however, when a cutoff is specified, any demand point outside the cutoff time or distance of all facilities is not allocated.
    • An allocated demand point has all or none of its demand weight assigned to a facility; that is, demand isn't apportioned with this problem type.
    • If the total demand that can reach a facility is greater than the capacity of the facility, only the demand points that maximize total captured demand and minimize total weighted travel are allocated.
      Note:

      You may notice an apparent inefficiency when a demand point is allocated to a facility that isn't the nearest solution facility. This may occur when demand points have varying weights and when the demand point in question can reach more than one facility. This kind of result indicates the nearest solution facility didn't have adequate capacity for the weighted demand, or the most efficient solution for the entire problem required one or more local inefficiencies. In either case, the solution is correct.

  • Minimize Facilities—Facilities are chosen such that as much weighted demand as possible is allocated to solution facilities within the travel time or distance cutoff; additionally, the number of facilities required to cover demand is minimized.

    Minimize facilities is the same as maximize coverage but with the exception of the number of facilities to locate, which in this case is determined by the solver. When the cost of building facilities is not a limiting factor, the same kinds of organizations that use maximize coverage (emergency response, for instance) use minimize facilities so all possible demand points will be covered.

    The following list describes how the minimize facilities problem type handles demand:

    • A demand point that cannot reach any facilities due to a cutoff distance or time is not allocated.
    • A demand point that can only reach one facility has all its demand weight allocated to that facility.
    • A demand point that can reach two or more facilities has all its demand weight allocated to the nearest facility only.

  • Maximize Attendance—Facilities are chosen such that as much demand weight as possible is allocated to facilities while assuming the demand weight decreases in relation to the distance between the facility and the demand point.

    Specialty stores that have little or no competition benefit from this problem type, but it may also be beneficial to general retailers and restaurants that don't have the data on competitors necessary to perform market share problem types. Some businesses that may benefit from this problem type include coffee shops, fitness centers, dental and medical offices, and electronics stores. Public transit bus stops are often chosen with the help of maximize attendance. Maximize attendance assumes that the farther people must travel to reach your facility, the less likely they are to use it. This is reflected in how the amount of demand allocated to facilities diminishes with distance.

    The following list describes how the maximize attendance problem type handles demand:

    • A demand point that cannot reach any facilities due to a cutoff distance or time is not allocated.
    • When a demand point can reach a facility, its demand weight is only partially allocated to the facility. The amount allocated decreases as a function of the maximum cutoff distance (or time) and the travel distance (or time) between the facility and the demand point.
    • The weight of a demand point that can reach more than one facility is proportionately allocated to the nearest facility only.

  • Maximize Market Share—A specific number of facilities are chosen such that the allocated demand is maximized in the presence of competitors. The goal is to capture as much of the total market share as possible with a given number of facilities, which you specify. The total market share is the sum of all demand weight for valid demand points.

    The market share problem types require the most data because, along with knowing your own facilities' weight, you also need to know that of your competitors' facilities. The same types of facilities that use the maximize attendance problem type can also use market share problem types given that they have comprehensive information that includes competitor data. Large discount stores typically use maximize market share to locate a finite set of new stores. The market share problem types use a Huff model, which is also known as a gravity model or spatial interaction.

    The following list describes how the maximize market share problem type handles demand:

    • A demand point that cannot reach any facilities due to a cutoff distance or time is not allocated.
    • A demand point that can only reach one facility has all its demand weight allocated to that facility.
    • A demand point that can reach two or more facilities has all its demand weight allocated to them; furthermore, the weight is split among the facilities proportionally to the facilities' attractiveness (facility weight) and inversely proportional to the distance between the facility and demand point. Given equal facility weights, this means more demand weight is assigned to near facilities than far facilities.

    • The total market share, which can be used to calculate the captured market share, is the sum of the weight of all valid demand points.

  • Target Market Share—The minimum number of facilities necessary to capture a specific percentage of the total market share in the presence of competitors are chosen. The total market share is the sum of all demand weight for valid demand points. You set the percent of the market share you want to reach and the solver identifies the fewest number of facilities necessary to meet that threshold.

    The market share problem types require the most data because, along with knowing your own facilities' weight, you also need to know that of your competitors' facilities. The same types of facilities that use the maximize attendance problem type can also use market share problem types given that they have comprehensive information that includes competitor data.

    Large discount stores typically use the target market share problem type when they want to know how much expansion would be required to reach a certain level of the market share or see what strategy would be needed just to maintain their current market share given the introduction of new competing facilities. The results often represent what stores would do if budgets weren't a concern. In other cases where budget is a concern, stores revert to the maximize market share problem type and simply capture as much of the market share as possible with a limited number of facilities.

    The following list describes how the target market share problem type handles demand:

    • The total market share, which is used in calculating the captured market share, is the sum of the weight of all valid demand points.
    • A demand point that cannot reach any facilities due to a cutoff distance or time is not allocated.
    • A demand point that can only reach one facility has all its demand weight allocated to that facility.
    • A demand point that can reach two or more facilities has all its demand weight allocated to them; furthermore, the weight is split among the facilities proportionally to the facilities' attractiveness (facility weight) and inversely proportional to the distance between the facility and demand point. Given equal facility weights means more demand weight is assigned to near facilities than far facilities.

String
Number_of_Facilities_to_Find
(Optional)

The number of facilities to find. The default value is 1.

The facilities with a FacilityType field value of 1 (Required) are always chosen first. Any excess facilities are chosen from candidate facilities with 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)

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 cutoff is measured by the shortest path along roads.

This parameter can be used to model the maximum distance that people are willing to travel to visit stores or the maximum time permitted for a fire department to reach anyone in the community.

Note that Demand Points includes the Cutoff field, which, if set accordingly, overrides the Default Measurement Cutoff parameter. You may 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 field value of the demand points in urban areas to 2.

Double
Default_Capacity
(Optional)

This parameter 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 identifies 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 parameter, along with 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 refers to 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 parameter determines whether travel time or distance is analyzed.

  • Linear

    costdf = λ * impedancedf

    The transformed travel time or distance between the facility and the demand point is the same as the time or distance of the shortest path between the two locations. With this option, the impedance parameter (λ) is always set to one. This is the default.

  • Power

    costdf = impedancedfλ

    The transformed travel time or distance between the facility and the demand point is equal to the time or distance of the shortest path raised to the power specified by the impedance parameter (λ). Use the Power option with a positive impedance parameter to specify higher weight to nearby facilities.

  • Exponential

    costdf = e(λ * impedancedf)

    The transformed travel time or distance between the facility and the demand point is equal to the mathematical constant e raised to the power specified by the shortest-path network impedance multiplied with the impedance parameter (λ). Use the Exponential option with a positive impedance parameter to specify a high weight to nearby facilities.

The value set for this parameter can be overridden on a per-demand-point basis using the ImpedanceTransformation field in the input demand points.

String
Measurement_Transformation_Factor
(Optional)

Provides a parameter value to the equations specified in the Measurement 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.

The default value is 1.

The value set for this parameter can be overridden on a per-demand-point basis using the ImpedanceParameter field in the input demand points.

Double
Travel_Direction
(Optional)

Specifies whether travel times or distances will be measured from facilities to demand points or from demand points to facilities.

  • Facility to Demand—The direction of travel is from facilities to demand points. This is the default.
  • Demand to Facility—The direction of travel is from demand points to facilities.

Travel times and distances may change based on direction of travel. If traveling 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, traveling from point A to point B may take 10 minutes, but traveling 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, for problem types in which 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 (facility) to the location of the emergency (demand point). Management at a retail store is more concerned with the time it takes shoppers (demand points) to reach the store (facility); therefore, store management 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)

The time at which travel begins. This parameter is ignored unless Measurement Units is 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 constantly changes in reality, and as it changes, travel times between facilities and demand points 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.

  • Geographically Local—The Time of Day parameter refers to the time zone in which the facilities or demand points are located. If Travel Direction is facilities to demand points, this is the time zone of the facilities. If Travel Direction is demand points to facilities, this is the time zone of the demand points.
  • UTC—The Time of Day parameter refers to coordinated universal time (UTC). Choose this option if you want to find the best location for a specific time, such as now, but aren't certain in which time zone the facilities or demand points will be located.

Regardless of the Time Zone for Time of Day parameter value, the following rules are enforced by the tool if your facilities and demand points are in multiple time zones:

  • All facilities must be in the same time zone when specifying a time of day and travel is from facility to demand.
  • All demand points must be in the same time zone when specifying a time of day and travel is from demand to facility.

String
UTurn_at_Junctions
(Optional)

Specifies 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 the number of edges that 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.

  • Allowed—U-turns are permitted at junctions with any number of connected edges. This is the default value.
  • Not Allowed—U-turns are prohibited at all junctions, regardless of junction valency. Note, however, that U-turns are still permitted at network locations even when this option is chosen; however, you can set the individual network locations' CurbApproach attribute to prohibit U-turns there as well.
  • Allowed only at Dead Ends—U-turns are prohibited at all junctions, except those that have only one adjacent edge (a dead end).
  • Allowed only at Intersections and Dead Ends—U-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). Often, networks have extraneous junctions in the middle of road segments. This option prevents vehicles from making U-turns at these locations.

This parameter is ignored unless Travel Mode is set to Custom.

String
Point_Barriers

Use this parameter to specify one or more points that will 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 point barriers, you can set properties for each, such as its name or barrier type, using 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):

  • 0 (Restriction)—Prohibits travel through the barrier. The barrier is referred to as a restriction point barrier since it acts as a restriction.

  • 2 (Added Cost)—Traveling through the barrier increases the travel time or distance by the amount specified in the Additional_Time, Additional_Distance, or Additional_Cost field. This barrier type is referred to as an added cost point barrier.

Additional_Time

The added travel time when the barrier is traversed. This field is applicable only for added-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that 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 Measurement Units parameter.

Additional_Distance

The added distance when the barrier is traversed. This field is applicable only for added-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that 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 Measurement Units parameter.

Additional_Cost

The added cost when the barrier is traversed. This field is applicable only for added-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is neither time based nor distance based.

FullEdge

Specifies how the restriction point barriers are applied to the edge elements during the analysis. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (False)—Permits travel on the edge up to the barrier but not through it. This is the default value.
  • 1 (True)—Restricts travel anywhere on the associated edge.

CurbApproach

Specifies the direction of traffic that is affected by the barrier. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Either side of vehicle)—The barrier affects travel over the edge in both directions.
  • 1 (Right side of vehicle)—Vehicles are only affected if the barrier is on their right side during the approach. Vehicles that traverse the same edge but approach the barrier on their left side are not affected by the barrier.
  • 2 (Left side of vehicle)—Vehicles are only affected if the barrier is on their left side during the approach. Vehicles that traverse the same edge but approach the barrier on their right side are not affected by the barrier.

Because junctions are points and don't have a side, barriers on junctions affect all vehicles regardless of the curb approach.

The CurbApproach attribute is designed to work with both types 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 facility, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

Bearing

The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

Learn more about bearing and bearing tolerance

BearingTol

The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the value from the Bearing field is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

Learn more about bearing and bearing tolerance

NavLatency

This field is only used in the solve process if Bearing and BearingTol also have values; however, entering a NavLatency value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much time is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

The time units of NavLatency are the same as the units specified by the timeUnits property of the analysis object.

Feature Set
Line_Barriers

Use this parameter to 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 to 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 name and barrier type properties for each using the following attributes:

Name

The name of the barrier.

Feature Set
Polygon_Barriers

Use this parameter to 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 to the number of polygons you can specify as polygon barriers, the combined number of streets intersected by all the polygons cannot exceed 2,000.

When specifying the polygon barriers, you can set properties for each, such as its name or barrier type, using the following attributes:

Name

The name of the barrier.

BarrierType

Specifies whether the barrier restricts travel completely or scales the cost (such as 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):

  • 0 (Restriction)—Prohibits traveling through any part of the barrier. The barrier is referred to as a restriction polygon barrier since it prohibits traveling on streets intersected by the barrier. One use of this type of barrier is to model floods covering areas of the street that make traveling on those streets impossible.

  • 1 (Scaled Cost)—Scales the cost (such as travel time or distance) required to travel the underlying streets by a factor specified using the ScaledTimeFactor or ScaledDistanceFactor field. If the streets are partially covered by the barrier, the travel time or distance is apportioned and then scaled. For example, a factor of 0.25 means that travel on underlying streets is expected to be four times faster than normal. A factor of 3.0 means it is expected to take three times longer than normal to travel on underlying streets. This barrier type is referred to as a scaled-cost polygon barrier. It can be used to model storms that reduce travel speeds in specific regions.

ScaledTimeFactor

This is the factor by which the travel time of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

This field is applicable only for scaled-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is time based.

ScaledDistanceFactor

This is the factor by which the distance of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

This field is applicable only for scaled-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is distance based.

ScaledCostFactor

This is the factor by which the cost of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

This field is applicable only for scaled-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is neither time based nor distance based.

Feature Set
Use_Hierarchy
(Optional)

Specifies whether hierarchy will be used when finding the shortest path between facilities and demand points.

  • Checked (True)—Hierarchy will be used when measuring between facilities and demand points. When hierarchy is used, the tool prefers higher-order streets (such as freeways) to lower-order streets (such as local roads) and can be used to simulate the driver preference of traveling on freeways instead of local roads even if that means a longer trip. This is especially true when finding routes to faraway locations, because drivers on long-distance trips tend to prefer traveling on freeways where stops, intersections, and turns can be avoided. Using hierarchy is computationally faster, especially for long-distance routes, since the tool can determine the best route from a relatively smaller subset of streets.
  • Unchecked (False)—Hierarchy will not be used when measuring between facilities and demand points. If hierarchy is not used, the tool considers all streets and doesn't prefer higher-order streets when finding the route. This is often used when finding short-distance routes within a city.

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 set this parameter to not use hierarchy.

Boolean
Restrictions

Specifies which restrictions will 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 the Avoid Toll Roads restriction will result in a route that will include toll roads only when it is required to travel on toll roads 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 illegal to do so.

Note:

Some restrictions require an additional value to be specified for their use. This value must 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 in 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 determine whether the restriction is available in a particular country by reviewing the table in the Country list section of Network analysis coverage. 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 when the Restriction Usage attribute parameter value is between 0 and 1 (see the Attribute Parameter Value parameter). It prohibits all restrictions when the Restriction Usage parameter value is greater than 0.

Note:

The values you provide for this parameter are ignored unless Travel Mode is set to Custom.

The tool supports the following restrictions:

  • Any Hazmat Prohibited—The results will not include roads where transporting any kind of hazardous material is prohibited.

    Availability: Select countries in North America and Europe

  • Avoid Carpool Roads—The results will avoid roads that are designated exclusively for car pool (high-occupancy) vehicles.

    Availability: All countries

  • Avoid Express Lanes—The results will avoid roads designated as express lanes.

    Availability: All countries

  • Avoid Ferries—The results will avoid ferries.

    Availability: All countries

  • Avoid Gates—The results will avoid roads where there are gates, such as keyed access or guard-controlled entryways.

    Availability: All countries

  • Avoid Limited Access Roads—The results will avoid roads that are limited-access highways.

    Availability: All countries

  • Avoid Private Roads—The results will avoid roads that are not publicly owned and maintained.

    Availability: All countries

  • Avoid Roads Unsuitable for Pedestrians—The results will avoid roads that are unsuitable for pedestrians.

    Availability: All countries

  • Avoid Stairways—The results will avoid all stairways on a pedestrian-suitable route.

    Availability: All countries

  • Avoid Toll Roads—The results will avoid all toll roads for automobiles.

    Availability: All countries

  • Avoid Toll Roads for Trucks—The results will avoid all toll roads for trucks.

    Availability: All countries

  • Avoid Truck Restricted Roads—The results will avoid roads where trucks are not allowed, except when making deliveries.

    Availability: All countries

  • Avoid Unpaved Roads—The results will avoid roads that are not paved (for example, dirt, gravel, and so on).

    Availability: All countries

  • Axle Count Restriction—The results will not include roads where trucks with the specified number of axles are prohibited. The number of axles can be specified using the Number of Axles restriction parameter.

    Availability: Select countries in North America and Europe

  • Driving a Bus—The results will not include roads where buses are prohibited. Using this restriction will also ensure that the results will honor one-way streets.

    Availability: All countries

  • Driving a Taxi—The results will not include roads where taxis are prohibited. Using this restriction will also ensure that the results will honor one-way streets.

    Availability: All countries

  • Driving a Truck—The results will not include roads where trucks are prohibited. Using this restriction will also ensure that the results will honor one-way streets.

    Availability: All countries

  • Driving an Automobile—The results will not include roads where automobiles are prohibited. Using this restriction will also ensure that the results will honor one-way streets.

    Availability: All countries

  • Driving an Emergency Vehicle—The results will not include roads where emergency vehicles are prohibited. Using this restriction will also ensure that the results will honor one-way streets.

    Availability: All countries

  • Height Restriction—The results will not include roads where the vehicle height exceeds the maximum allowed height for the road. The vehicle height can be specified using the Vehicle Height (meters) restriction parameter.

    Availability: Select countries in North America and Europe

  • Kingpin to Rear Axle Length Restriction—The results will not include roads where the vehicle length exceeds the maximum allowed kingpin to rear axle for all trucks on the road. The length between the vehicle kingpin and the rear axle can be specified using the Vehicle Kingpin to Rear Axle Length (meters) restriction parameter.

    Availability: Select countries in North America and Europe

  • Length Restriction—The results will not include roads where the vehicle length exceeds the maximum allowed length for the road. The vehicle length can be specified using the Vehicle Length (meters) restriction parameter.

    Availability: Select countries in North America and Europe

  • Preferred for Pedestrians—The results will use preferred routes suitable for pedestrian navigation.

    Availability: Select countries in North America and Europe

  • Riding a Motorcycle—The results will not include roads where motorcycles are prohibited. Using this restriction will also ensure that the results will honor one-way streets.

    Availability: All countries

  • Roads Under Construction Prohibited—The results will not include roads that are under construction.

    Availability: All countries

  • Semi or Tractor with One or More Trailers Prohibited—The results will not include roads where semis or tractors with one or more trailers are prohibited.

    Availability: Select countries in North America and Europe

  • Single Axle Vehicles Prohibited—The results will not include roads where vehicles with single axles are prohibited.

    Availability: Select countries in North America and Europe

  • Tandem Axle Vehicles Prohibited—The results will not include roads where vehicles with tandem axles are prohibited.

    Availability: Select countries in North America and Europe

  • Through Traffic Prohibited—The results will not include roads where through traffic (non-local) is prohibited.

    Availability: All countries

  • Truck with Trailers Restriction—The results will not include roads where trucks with the specified number of trailers on the truck are prohibited. The number of trailers on the truck can be specified using the Number of Trailers on Truck restriction parameter.

    Availability: Select countries in North America and Europe

  • Use Preferred Hazmat Routes—The results will prefer roads that are designated for transporting any kind of hazardous materials.

    Availability: Select countries in North America and Europe

  • Use Preferred Truck Routes—The results will prefer roads that are designated as truck routes, such as the roads that are part of the national network as specified by the National Surface Transportation Assistance Act in the United States, or roads that are designated as truck routes by the state or province, or roads that are preferred by truckers when driving in an area.

    Availability: Select countries in North America and Europe

  • Walking—The results will not include roads where pedestrians are prohibited.

    Availability: All countries

  • Weight Restriction—The results will not include roads where the vehicle weight exceeds the maximum allowed weight for the road. The vehicle weight can be specified using the Vehicle Weight (kilograms) restriction parameter.

    Availability: Select countries in North America and Europe

  • Weight per Axle Restriction—The results will not include roads where the vehicle weight per axle exceeds the maximum allowed weight per axle for the road. The vehicle weight per axle can be specified using the Vehicle Weight per Axle (kilograms) restriction parameter.

    Availability: Select countries in North America and Europe

  • Width Restriction—The results will not include roads where the vehicle width exceeds the maximum allowed width for the road. The vehicle width can be specified using the Vehicle Width (meters) restriction parameter.

    Availability: Select countries in North America and Europe

Legacy:

The Driving a Delivery Vehicle restriction attribute is no longer available. The service will ignore this restriction since it is invalid. To achieve similar results, use the Driving a Truck restriction attribute along with the Avoid Truck Restricted Roads restriction attribute.

String
Attribute_Parameter_Values
(Optional)

Use this parameter to specify additional values required by an attribute or restriction, such as to specify whether the restriction prohibits, avoids, or prefers travel on restricted roads. 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 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 follows:

  • AttributeName—The name of the restriction.
  • ParameterName—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.

The Attribute Parameter Values parameter 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 as well as 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 in the parentheses:

  • PROHIBITED (-1)—Travel on the roads using the restriction is completely prohibited.
  • AVOID_HIGH (5)—It is highly unlikely the tool will include in the route the roads that are associated with the restriction.
  • AVOID_MEDIUM (2)—It is unlikely the tool will include in the route the roads that are associated with the restriction.
  • AVOID_LOW (1.3)—It is somewhat unlikely the tool will include in the route the roads that are associated with the restriction.
  • PREFER_LOW (0.8)—It is somewhat likely the tool will include in the route the roads that are associated with the restriction.
  • PREFER_MEDIUM (0.5)—It is likely the tool will include in the route the roads that are associated with the restriction.
  • PREFER_HIGH (0.2)—It is highly likely the tool will include in the route the roads that are associated with the restriction.

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 Restriction Usage value depends on your routing preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage attribute. 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 puts lower importance on avoiding tolls; choosing AVOID_HIGH instead gives it a higher importance and thus makes it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED entirely disallows 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, 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)

Specifies the type of line features that are output by the tool. The parameter accepts one of the following values:

  • Straight Line—Straight lines between solution facilities and the demand points allocated to them are returned. This is the default. Drawing straight lines on a map helps you visualize how demand is allocated.
  • None—A table containing data about the shortest paths between solution facilities and the demand points allocated to them is returned but lines are not.

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 demand points and facilities. That is, this parameter only changes the output line shapes; it doesn't change the measurement method.

String
Travel_Mode
(Optional)

The mode of transportation to model in the analysis. Travel modes are managed in ArcGIS Online and can be configured by the administrator of your organization to reflect your organization's workflows. You need to specify the name of a travel mode that is supported by your organization.

To get a list of supported travel mode names, use the same GIS server connection you used to access this tool, and run the GetTravelModes tool in the Utilities toolbox. The GetTravelModes tool adds a table, Supported Travel Modes, to the application. Any value in the Travel Mode Name field from the Supported Travel Modes table can be specified as input. You can also specify the value from the Travel Mode Settings field as input. This reduces the tool execution time because the tool does not have to find the settings based on the travel mode name.

The default value, Custom, allows you to configure your own travel mode using the custom travel mode parameters (UTurn at Junctions, Use Hierarchy, Restrictions, Attribute Parameter Values, and Impedance). The default values of the custom travel mode parameters model traveling by car. You can also choose Custom and set the custom travel mode parameters listed above to model a pedestrian with a fast walking speed or a truck with a given height, weight, and cargo of certain hazardous materials. You can try different settings to get the analysis results you want. Once you have identified the analysis settings, work with your organization's administrator and save these settings as part of a new or existing travel mode so that everyone in your organization can run the analysis with the same settings.

Caution:

When you choose Custom, the values you set for the custom travel mode parameters are included in the analysis. Specifying another travel mode, as defined by your organization, causes any values you set for the custom travel mode parameters to be ignored; the tool overrides them with values from your specified travel mode.

String
Impedance
(Optional)

Specifies 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 time is an impedance: a car may take 1 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.

Travel distance can also be 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.)

Caution:

The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value.

Choose from the following impedance values:

  • TravelTime—Historical and live traffic data is used. This option is good for modeling the time it takes automobiles to travel along roads at a specific time of day using live traffic speed data where available. When using TravelTime, you can optionally set the TravelTime::Vehicle Maximum Speed (km/h) attribute parameter to specify the physical limitation of the speed the vehicle is capable of traveling.
  • Minutes—Live traffic data is not used, but historical average speeds for automobiles data is used.
  • TruckTravelTime—Historical and live traffic data is used, but the speed is capped at the posted truck speed limit. This is good for modeling the time it takes for the trucks to travel along roads at a specific time. When using TruckTravelTime, you can optionally set the TruckTravelTime::Vehicle Maximum Speed (km/h) attribute parameter to specify the physical limitation of the speed the truck is capable of traveling.
  • TruckMinutes—Live traffic data is not used, but the smaller of the historical average speeds for automobiles and the posted speed limits for trucks are used.
  • WalkTime—The default is a speed of 5 km/hr on all roads and paths, but this can be configured through the WalkTime::Walking Speed (km/h) attribute parameter.
  • Miles—Length measurements along roads are stored in miles and can be used for performing analysis based on shortest distance.
  • Kilometers—Length measurements along roads are stored in kilometers and can be used for performing analysis based on shortest distance.
  • TimeAt1KPH—The default is a speed of 1 km/hr on all roads and paths. The speed cannot be changed using any attribute parameter.

If you choose a time-based impedance, such as TravelTime, TruckTravelTime, Minutes, TruckMinutes, or WalkTime, the Measurement Units parameter must be set to a time-based value. If you choose a distance-based impedance, such as Miles or Kilometers, Measurement Units must be distance-based.

Legacy:

Drive Time, Truck Time, Walk Time, and Travel Distance impedance values are no longer supported and will be removed in a future release. If you use one of these values, the tool uses the value of the Time Impedance parameter for time-based values and the Distance Impedance parameter for distance-based values.

String
Save_Output_Network_Analysis_Layer
(Optional)

Specifies whether the analysis settings will be saved as a network analysis layer file. You cannot directly work with this file even when you open the file in an ArcGIS Desktop application such as ArcMap. It is meant to be sent to Esri Technical Support to diagnose the quality of results returned from the tool.

  • Checked (True in Python)—The output will be saved as a network analysis layer file. The file will be downloaded to a temporary directory on your machine. In ArcGIS Pro, the location of the downloaded file can be determined by viewing the value for the Output Network Analysis Layer parameter in the entry corresponding to the tool execution in the geoprocessing history of your project. In ArcMap, the location of the file can be determined by accessing the Copy Location option in the shortcut menu on the Output Network Analysis Layer parameter in the entry corresponding to the tool execution in the Geoprocessing Results window.
  • Unchecked (False in Python)—The output will not be saved as a network analysis layer file. This is the default.

Boolean
Overrides
(Optional)

Additional settings that can influence the behavior of the solver when finding solutions for the network analysis problems.

The value for this parameter must be specified in JavaScript Object Notation (JSON). For example, a valid value is of the following form: {"overrideSetting1" : "value1", "overrideSetting2" : "value2"}. The override setting name is always enclosed in double quotation marks. The values can be a number, Boolean, or string.

The default value for this parameter is no value, which indicates not to override any solver settings.

Overrides are advanced settings that should be used only after careful analysis of the results obtained before and after applying the settings. For a list of supported override settings for each solver and their acceptable values, contact Esri Technical Support.

string
Time_Impedance
(Optional)

The time-based impedance is a value that represents the travel time along road segments or on other parts of the transportation network.

Note:
If the impedance for the travel mode, as specified using the Impedance parameter, is time based, the values for the Time Impedance and Impedance parameters must be identical. Otherwise, the service will return an error.
String
Distance_Impedance
(Optional)

The distance-based impedance is a value that represents the travel distance along road segments or on other parts of the transportation network.

Note:
If the impedance for the travel mode, as specified using the Impedance parameter, is distance based, the values for the Distance Impedance and Impedance parameters must be identical. Otherwise, the service will return an error.
String
Output_Format
(Optional)

Specifies the format in which the output features will be created.

  • Feature Set—The output features will be returned as feature classes and tables. This is the default.
  • JSON File—The output features will be returned as a compressed file containing the JSON representation of the outputs. When this option is specified, the output is a single file (with a .zip extension) that contains one or more JSON files (with a .json extension) for each of the outputs created by the service.
  • GeoJSON File—The output features will be returned as a compressed file containing the GeoJSON representation of the outputs. When this option is specified, the output is a single file (with a .zip extension) that contains one or more GeoJSON files (with a .geojson extension) for each of the outputs created by the service.

When a file-based output format, such as JSON File or GeoJSON File, is specified, no outputs will be added to the display because the application, such as ArcMap or ArcGIS Pro, cannot draw the contents of the result file. Instead, the result file is downloaded to a temporary directory on your machine. In ArcGIS Pro, the location of the downloaded file can be determined by viewing the value for the Output Result File parameter in the entry corresponding to the tool execution in the geoprocessing history of your project. In ArcMap, the location of the file can be determined by accessing the Copy Location option in the shortcut menu on the Output Result File parameter in the entry corresponding to the tool execution in the Geoprocessing Results window.

String

Derived Output

NameExplanationData Type
Solve_Succeeded

Determines whether the service successfully identified the best facilities.

Boolean
Output_Allocation_Lines

This provides access to the lines that connect demand points to the facilities to which they are allocated. Such lines are referenced in the documentation as allocation lines. These allocation lines include data about the demand allocated from each demand point to the associated facility.

Feature Set
Output_Facilities

This provides access to the chosen, required, and competitor facilities, as well as any candidate facilities that were not chosen.

Feature Set
Output_Demand_Points

This provides access to the demand points that participated in the analysis: those that were and were not allocated to facilities.

Feature Set
Output_Network_Analysis_Layer

The network analysis layer, with properties configured in the tool parameters, that can be used for further analysis or debugging in the map.

File
Output_Result_File

A .zip file containing the results of the analysis, with one or more files for each output. The format of the individual files is specified by the Output Format parameter.

File

Code sample

SolveLocationAllocation example (stand-alone script)

The following Python script demonstrates how to use the Solve Location Allocation tool in a script.

"""This example shows how to choose the best locations for stores that can service the maximum number of customers."""

import sys
import time
import arcpy

# Change the username and password applicable to your own ArcGIS Online account
username = "<your user name>"
password = "<your password>"
la_service = "https://logistics.arcgis.com/arcgis/services;World/LocationAllocation;{0};{1}".format(username, password)

# Add the geoprocessing service as a toolbox.
# Check https://pro.arcgis.com/en/pro-app/2.6/arcpy/functions/importtoolbox.htm for
# other ways in which you can specify credentials to connect to a geoprocessing service.
arcpy.ImportToolbox(la_service)

# Set the variables to call the tool
facilities = "C:/data/Inputs.gdb/Stores"
demand_points = "C:/data/Inputs.gdb/Customers"
output_lines = "C:/data/Results.gdb/AllocationLines"
output_facilities = "C:/data/Results.gdb/Facilities"
output_demand_points = "C:/data/Results.gdb/DemandPoints"

# Call the tool to find two best store locations that can reach a maxmimum number of customers
# with ten minutes of drive time
result = arcpy.SolveLocationAllocation_LocationAllocation(facilities, demand_points, "Minutes",
                                                          Problem_Type="Maximize Attendance",
                                                          Number_of_Facilities_to_Find=2,
                                                          Default_Measurement_Cutoff=10.0)
arcpy.AddMessage("Running the analysis with result ID: {}".format(result.resultID))

# Check the status of the result object every 1 second until it has a
# value of 4 (succeeded) or greater
while result.status < 4:
    time.sleep(1)

# print any warning or error messages returned from the tool
result_severity = result.maxSeverity
if result_severity == 2:
    arcpy.AddError("An error occured when running the tool")
    arcpy.AddError(result.getMessages(2))
    sys.exit(2)
elif result_severity == 1:
    arcpy.AddWarning("Warnings were returned when running the tool")
    arcpy.AddWarning(result.getMessages(1))

# Store the allocation lines that connect customers to allocated stores, the chosen stores,
# and the allocated customer locations to a geodatabase
result.getOutput(1).save(output_lines)
arcpy.analysis.Select(result.getOutput(2), output_facilities, "DemandCount > 0")
result.getOutput(3).save(output_demand_points)
SolveLocationAllocation example 2 (stand-alone script)

The following example shows how to perform a location-allocation analysis using a custom travel mode for trucks.

"""This example shows how to perform a location-allocation analysis using a custom travel mode for trucks."""

import sys
import time
import json
import arcpy

username = "<your user name>"
password = "<your password>"
la_service = "https://logistics.arcgis.com/arcgis/services;World/LocationAllocation;{0};{1}".format(username, password)

# Add the geoprocessing service as a toolbox.
arcpy.ImportToolbox(la_service)

# Set the variables to call the tool
facilities = "C:/data/Inputs.gdb/Stores"
demand_points = "C:/data/Inputs.gdb/Customers"
output_lines = "C:/data/Results.gdb/AllocationLines"
output_facilities = "C:/data/Results.gdb/Facilities"
output_demand_points = "C:/data/Results.gdb/DemandPoints"

# Change to moderately prefer trucking roads for the Trucking Time travel mode
# used for the analysis
portal_url = "https://www.arcgis.com"
arcpy.SignInToPortal(portal_url, username, password)
travel_mode_list = arcpy.na.GetTravelModes(portal_url)
tt = travel_mode_list["Trucking Time"]
tt_json = str(tt)
tt_dict = json.loads(tt_json)

for attr_param in tt_dict["attributeParameterValues"]:
    if attr_param['attributeName'] == 'Use Preferred Truck Routes' and attr_param['parameterName'] == 'Restriction Usage':
        attr_param['value'] = 'PREFER_MEDIUM'
travel_mode = json.dumps(tt_dict)

# Call the tool
result = arcpy.SolveLocationAllocation_LocationAllocation(facilities, demand_points, "Minutes",
                                                          Problem_Type="Maximize Attendance",
                                                          Number_of_Facilities_to_Find=2,
                                                          Default_Measurement_Cutoff=10.0,
                                                          Travel_Mode=travel_mode)

# Check the status of the result object every 1 second until it has a
# value of 4 (succeeded) or greater
while result.status < 4:
    time.sleep(1)

# print any warning or error messages returned from the tool
result_severity = result.maxSeverity
if result_severity == 2:
    arcpy.AddError("An error occured when running the tool")
    arcpy.AddError(result.getMessages(2))
    sys.exit(2)
elif result_severity == 1:
    arcpy.AddWarning("Warnings were returned when running the tool")
    arcpy.AddWarning(result.getMessages(1))

# Store the allocation lines that connect customers to allocated stores, the chosen stores,
# and the allocated customer locations to a geodatabase
result.getOutput(1).save(output_lines)
arcpy.analysis.Select(result.getOutput(2), output_facilities, "DemandCount > 0")
result.getOutput(3).save(output_demand_points)

Environments

This tool does not use any geoprocessing environments.

Related topics