What is location-allocation?
Location-allocation is the process of finding a set of facilities that will best serve demand from surrounding areas. As the name suggests, location-allocation is a two-fold problem that simultaneously locates facilities and allocates demand points to the facilities.
You can use location-allocation to build applications that answer questions such as:
- Given a set of existing fire stations, which site for a new fire station would provide the best response times for the community?
- If a retail company has to downsize, which stores should it close to maximize the overall demand?
- Where should a factory be built to minimize the distance to distribution centers?
How location-allocation works
The typical workflow for location-allocation analysis is to define:
- One or more locations that serve as facilities.
- One or more locations that represent demand for the services offered at the facilities.
- The type of travel for the analysis.
- The objective of the location-allocation analysis such as maximize the attendance or minimize the travel time.
- Number of facilities the service should choose.
- Call the service to find the best locations for the facilities and allocate demand to the chosen facilities.
URL requests
You can perform location allocation by making an HTTPS request to the location-allocation service submit operation or by using client APIs. Specify one or more facilities, demand points, the location-allocation problem type, and additional parameters to refine the operation. Some of the most common parameters are described below.
Location-allocation only supports job
Request limits
| Limit | Job |
|---|---|
| Maximum number of facilities: | 1,000 |
| Maximum number of facilities to find: | 100 |
| Maximum number of demand points: | 10,000 |
| Maximum transaction time: | 60 minutes |
| Maximum number of point barriers: | 250 |
| Maximum number of street features intersected by polyline barriers: | 500 |
| Maximum number of street features intersected by polygon barriers: | 2,000 |
| Maximum straight-line distance for the walking travel mode: (If the straight-line distance between any incidents or facilities is greater than this limit, the analysis will fail when the walking restriction is used.) | 27 miles (43.45 kilometers) |
| Force hierarchy beyond a straight-line distance of: (If the straight-line distance between any origin or destination is greater than the limit shown here, the analysis uses hierarchy, even if the travel mode defines not to use hierarchy.) | 50 miles (80.46 kilometers) |
| Maximum snap tolerance: (If the distance between an input point and its nearest traversable street is greater than the distance specified here, the point is excluded from the analysis.) | 12.42 miles (20 kilometers) |
URL
https://logistics.arcgis.com/arcgis/rest/services/World/LocationAllocation/GPServer/SolveLocationAllocation/submitJob?<parameters>Required parameters
| Name | Description | Examples |
|---|---|---|
f | The format of the data returned. | f=json f=pjson |
token | An API key or OAuth 2.0 access token | token= |
Key parameters
| Name | Description | Examples |
|---|---|---|
facilities | One or more locations that serve as facilities. | facilities={"features" |
demand | One or more locations that represent demand for the services offered at the facilities. | demand |
travel | The mode of transportation such as driving a car or a truck or walking. | travelJSON Object |
problem | The objective of the location-allocation analysis | problem |
number | Number of facilities the service should choose | number |
Additional parameters: Set additional constraints when performing location-allocation such as default to limit the travel time or travel distance between a facility and a demand point, ortravel to indicate if travel occurs from facility to demand points or vice versa.
Code examples
Job: Find new restaurant location
In this example, you want to expand a popular fast-food restaurant in the downtown central business district by opening a second location for employees in nearby office buildings. Use the location-allocation service to find the best site.
Provide the following inputs to the service:
-
Customers in office buildings are the
demand._points -
The existing and prospective restaurant locations are the
facilities. SetFacilitytoType 1for the existing restaurant so the service always includes it in the solution. SetFacilitytoType 0for the four prospective locations so the service can select the best one in addition to the existing restaurant. -
Since customers walk to the restaurant, set
travelto_mode walking time. -
Choose the problem type that matches your goal. Here, select
Maximize Attendanceto attract the maximum number of nearby customers and minimize their walking distance from their offices. -
To find one new location in addition to the existing restaurant, set
numberto_of _facilities _to _find 2. The service first allocates customers to the existing restaurant, then assigns the remaining customers to the best of the four candidates. -
Set
travelto_direction Demand To Facilitybecause customers travel from their offices to the restaurant.
APIs
# Connect to the location-allocation service
api_key = "YOUR_ACCESS_TOKEN"
arcgis.GIS("https://www.arcgis.com", api_key=api_key)
# Get the walking time travel mode defined for the portal. Fail if the travel mode is not found.
walking_time_travel_mode = ""
for feature in arcgis.network.analysis.get_travel_modes().supported_travel_modes.features:
attributes = feature.attributes
if attributes["AltName"] == "Walking Time":
walking_time_travel_mode = attributes["TravelMode"]
break
assert walking_time_travel_mode, "Walking Time travel mode not found"
# Call the location-allocation service
result = arcgis.network.analysis.solve_location_allocation(facilities=facilities,
demand_points=demand_points,
travel_mode=walking_time_travel_mode,
problem_type="Maximize Attendance",
number_of_facilities_to_find=2,
travel_direction="Demand to Facility",
)
print_result(result)
REST API
Unlike Direct request type which allows you to make a request and get back all the results in the response, when working with a Job request type, you need to follow a three step workflow:
- Make the
submitrequest with the appropriate request parameters to get a job id.Job - Using the job id, check the job status to see if the job completed successfully.
- Use the job id to get one or more results.
curl https://logistics.arcgis.com/arcgis/rest/services/World/LocationAllocation/GPServer/SolveLocationAllocation/submitJob? \
-d "f=json" \
-d "token=<ACCESS_TOKEN>" \
-d "facilities={'features':[{'attributes':{'Name':'Existing Location','FacilityType':1},'geometry':{'x':-122.333906,'y':47.609152}},{'attributes':{'Name':'Candidate 1','FacilityType':0},'geometry':{'x':-122.333585,'y':47.604501}},{'attributes':{'Name':'Candidate 2','FacilityType':0},'geometry':{'x':-122.334550,'y':47.605557}},{'attributes':{'Name':'Candidate 3','FacilityType':0},'geometry':{'x':-122.337753,'y':47.609442}},{'attributes':{'Name':'Candidate 4','FacilityType':0},'geometry':{'x':-122.335319,'y':47.607317}}]}" \
-d "demand_points={'features':[{'attributes':{'Name':'Colman Building','Weight':1573},'geometry':{'x':-122.335583,'y':47.603495}},{'attributes':{'Name':'Norton Parking Garage','Weight':1262},'geometry':{'x':-122.33482,'y':47.603745}},{'attributes':{'Name':'DocuSign Tower','Weight':2385},'geometry':{'x':-122.334151,'y':47.605060}},{'attributes':{'Name':'Fourth and Madison Building','Weight':1096},'geometry':{'x':-122.333227,'y':47.605493}},{'attributes':{'Name':'Safeco Plaza','Weight':3618},'geometry':{'x':-122.333899,'y':47.606190}},{'attributes':{'Name':'1201 Third Avenue','Weight':1782},'geometry':{'x':-122.336163,'y':47.607204}},{'attributes':{'Name':'Puget Sound Plaza','Weight':2165},'geometry':{'x':-122.335796,'y':47.608602}},{'attributes':{'Name':'Rainier Square','Weight':1316},'geometry':{'x':-122.334881,'y':47.609021}},{'attributes':{'Name':'Century Square','Weight':1974},'geometry':{'x':-122.337503,'y':47.610273}},{'attributes':{'Name':'Miken Building','Weight':3920},'geometry':{'x':-122.336516,'y':47.609510}},{'attributes':{'Name':'Westlake Park','Weight':2467},'geometry':{'x':-122.336353,'y':47.6110466}},{'attributes':{'Name':'U.S. Bank Centre','Weight':3997},'geometry':{'x':-122.334571,'y':47.610492}},{'attributes':{'Name':'Westlake Center','Weight':2440},'geometry':{'x':-122.337406,'y':47.611980}},{'attributes':{'Name':'Nordstrom Flagship Store','Weight':2438},'geometry':{'x':-122.336295,'y':47.6123047}},{'attributes':{'Name':'Columbia Center','Weight':5400},'geometry':{'x':-122.330746,'y':47.604502}},{'attributes':{'Name':'800 Fifth Avenue','Weight':3697},'geometry':{'x':-122.330228,'y':47.605698}},{'attributes':{'Name':'Seattle Municipal Tower','Weight':2025},'geometry':{'x':-122.329605,'y':47.605143}},{'attributes':{'Name':'Washington State Convention Center','Weight':1076},'geometry':{'x':-122.331520,'y':47.611664}}]}" \
-d "travel_mode={'attributeParameterValues':[{'attributeName':'Avoid Private Roads','parameterName':'Restriction Usage','value':'AVOID_MEDIUM'},{'attributeName':'Walking','parameterName':'Restriction Usage','value':'PROHIBITED'},{'attributeName':'Preferred for Pedestrians','parameterName':'Restriction Usage','value':'PREFER_LOW'},{'attributeName':'WalkTime','parameterName':'Walking Speed (km/h)','value':5},{'attributeName':'Avoid Roads Unsuitable for Pedestrians','parameterName':'Restriction Usage','value':'AVOID_HIGH'}],'description':'Follows paths and roads that allow pedestrian traffic and finds solutions that optimize travel time. The walking speed is set to 5 kilometers per hour.','distanceAttributeName':'Kilometers','id':'caFAgoThrvUpkFBW','impedanceAttributeName':'WalkTime','name':'Walking Time','restrictionAttributeNames':['Avoid Private Roads','Avoid Roads Unsuitable for Pedestrians','Preferred for Pedestrians','Walking'],'simplificationTolerance':2,'simplificationToleranceUnits':'esriMeters','timeAttributeName':'WalkTime','type':'WALK','useHierarchy':false,'uturnAtJunctions':'esriNFSBAllowBacktrack'}"
-d "problem_type=Maximize Attendance" \
-d "number_of_facilities_to_find=2" \
-d "travel_direction=Demand to Facility"Response (JSON)
{
"jobId": "j64631b4afe854912bfe914d2400af60d",
"jobStatus": "esriJobSubmitted"
}