Skip To Content
ArcGIS Developer
Dashboard

Choose Best Facilities

Choose Best Facilities

The Choose Best Facilities task finds the set of facilities that will best serve demand from surrounding areas.

Facilities might be public institutions that offer a service, such as fire stations, schools, or libraries, or they might be commercial ones such as drug stores or distribution centers for a parcel delivery service. Demand represents the need for a service that the facilities can meet. Demand is associated with point locations, with each location representing a given amount of demand.

Licensing

As described in the Get Started topic, in order to use any analysis task, the administrator of the organization needs to grant you certain basic privileges. To use the Choose Best Facilities task, you need to be granted the Network Analysis privilege.

Limits

  • demandLocationsLayer— maximum 10,000 features
  • candidateFacilitiesLayer—maximum of 1,000
  • candidateCount—maximum 100 features. This means that the number of features in the requiredFacilitiesLayer cannot exceed 100 since all features in the requiredFacilitiesLayer are allocated before any features in the candidateFacilitiesLayer. For example, if there are 99 features in the requiredFacilitiesLayer, only one feature from the candidateFacilitiesLayer will be allocated.
  • pointBarrierLayer—Maximum 250 features.
  • lineBarrierLayer—An error will occur if the number of street features intersected by all the line barriers exceeds 500.
  • polygonBarrierLayer—An error will occur if the number of street features intersected by all the polygon barriers exceeds 2000.
  • An error will occur if the tool takes more than 60 minutes to run when using travel modes. If this error occurs, rerun the analysis with fewer input features.

Request URL

http://<analysis url>/ChooseBestFacilities/submitJob

Request Parameters

For more information on using this task, see Choose Best Facilities in the ArcGIS Online help. The table below shows the correspondence between the values for the goal parameter and the terms used in the Choose Best Facilities help topic.

ArcGIS OnlineREST

Allocate to existing facilities

Allocate

Minimize travel

MinimizeImpedance

Maximize coverage

MaximizeCoverage

Maximize coverage with capacity

MaximizeCapacitatedCoverage

Cover a percentage of demand

PercentCoverage

ParameterDescription

goal

(Required)

The goal to satisfy when allocating demand locations to facilities. See the ArcGIS Online help topic Choose Best Facilities and the correspondence table above. Default value is Allocate.

Values: Allocate | MinimizeImpedance | MaximizeCoverage | MaximizeCapacitatedCoverage | PercentCoverage

demandLocationsLayer

(Required)

A point layer specifying the locations that have demand for facilities

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A feature collection

Examples:

  • {"url": <feature service layer url>, "filter": <where clause>}
  • {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

demand

A double value representing amount of demand available at every demand location.

The default value is 1.0.

demandField

A numeric field on the demandLocationsLayer representing the amount of demand available at each demand location. If specified, the demand parameter is ignored.

maxTravelRange

A double value representing the maximum travel time or distance allowed between a demand location and the facility it is allocated to. The default is unlimited (2,147,483,647.0)

maxTravelRangeField

A numeric field on the demandLocationsLayer containing the maximum travel time or distance allowed between a demand location and the facility it is allocated to. If specified, the maxTravelRange parameter is ignored.

Example: "maxTravelRangeField" : "NStudents"

maxTravelRangeUnits

The units for the maximum travel time or distance allowed between a demand location and the facility it is allocated to. The default is Minutes.

Values: Seconds | Minutes | Hours | Days | Meters | Kilometers | Feet | Yards | Miles

Example: "maxTravelRangeUnits" : "Miles"

travelMode

The mode of transportation for the analysis.

Travel modes are managed in ArcGIS Online and can be configured by the administrator of your organization to better reflect your organization's workflows. You must specify the JSON object containing the settings for a travel mode supported by your organization. To get a list of supported travel modes, run the GetTravelModes operation from the Utilities service.

Use a JSON object representing travel mode settings for the travelMode parameter value. When you use the GetTravelModes operation from the Utilities service, the result is a string representing the travel mode JSON. You must convert this string to a valid JSON object using the API and pass the JSON object as the value for the travelMode parameter.

For example, the following is a string representing the Walking Time travel mode as returned by the GetTravelModes operation:

"{\"attributeParameterValues\": [{\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Walking\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Preferred for Pedestrians\", \"value\": \"PREFER_LOW\"}, {\"parameterName\": \"Walking Speed (km/h)\", \"attributeName\": \"WalkTime\", \"value\": 5}], \"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.\", \"impedanceAttributeName\": \"WalkTime\", \"simplificationToleranceUnits\": \"esriMeters\", \"uturnAtJunctions\": \"esriNFSBAllowBacktrack\", \"restrictionAttributeNames\": [\"Preferred for Pedestrians\", \"Walking\"], \"useHierarchy\": false, \"simplificationTolerance\": 2, \"timeAttributeName\": \"WalkTime\", \"distanceAttributeName\": \"Miles\", \"type\": \"WALK\", \"id\": \"caFAgoThrvUpkFBW\", \"name\": \"Walking Time\"}"

Convert the value above to a valid JSON object and pass it as the value for the travelMode parameter.

travelMode=

{
  "attributeParameterValues": [
    {
      "parameterName": "Restriction Usage",
      "attributeName": "Walking",
      "value": "PROHIBITED"
    },
    {
      "parameterName": "Restriction Usage",
      "attributeName": "Preferred for Pedestrians",
      "value": "PREFER_LOW"
    },
    {
      "parameterName": "Walking Speed (km\/h)",
      "attributeName": "WalkTime",
      "value": 5
    }
  ],
  "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.",
  "impedanceAttributeName": "WalkTime",
  "simplificationToleranceUnits": "esriMeters",
  "uturnAtJunctions": "esriNFSBAllowBacktrack",
  "restrictionAttributeNames": [
    "Preferred for Pedestrians",
    "Walking"
  ],
  "useHierarchy": false,
  "simplificationTolerance": 2,
  "timeAttributeName": "WalkTime",
  "distanceAttributeName": "Miles",
  "type": "WALK",
  "id": "caFAgoThrvUpkFBW",
  "name": "Walking Time"
}

timeOfDay

Specify whether travel times should consider traffic conditions. To use traffic in the analysis, To use traffic in the analysis, set travelMode to a travel mode object whose impedanceAttributeName property is set to TravelTime and assign a value to timeOfDay. (A travel mode with other impedanceAttributeName values don't support traffic.). The timeOfDay value represents the time at which travel begins, or departs, from the input points. The time is specified as Unix time (milliseconds since midnight, January 1 1970).

The service supports two kinds of traffic: typical and live. Typical traffic references travel speeds that are made up of historical averages for each five-minute interval spanning a week. Live traffic retrieves speeds from a traffic feed that processes phone probe records, sensors, and other data sources to record actual travel speeds and predict speeds for the near future.

The Data Coverage page shows the countries Esri currently provides traffic data for.

Typical Traffic:

To ensure the task uses typical traffic in locations where it is available, choose a time and day of the week, and then convert the day of the week to one of the following dates from 1990:

  • Monday—1/1/1990
  • Tuesday—1/2/1990
  • Wednesday—1/3/1990
  • Thursday—1/4/1990
  • Friday—1/5/1990
  • Saturday—1/6/1990
  • Sunday—1/7/1990

Set the time and date as Unix time in milliseconds.

For example, to solve for 1:03 p.m. on Thursdays, set the time and date to 1:03 p.m., 4 January 1990; and convert to milliseconds (631458180000).

Note:

Although the dates representing days of the week are from 1990, typical traffic is calculated from recent traffic trends—usually over the last several months.

Live Traffic:

To use live traffic when and where it is available, choose a time and date and convert to Unix time.

Esri saves live traffic data for 4 hours and references predictive data extending 4 hours into the future. If the time and date you specify for this parameter is outside the 8-hour time window, or the travel time in the analysis continues past the predictive data window, the task falls back to typical traffic speeds.

Note:

  • All points in inputLayer need to be in the same time zone when using traffic and setting overlapPolicy to split or dissolve.
  • This parameter is ignored when breakUnits is set to distance unit.
  • The time zone for timeOfDay can be UTC or the time zone or zones in which the points in inputLayer are located. Specify time zones with the timeZoneForTimeOfDay parameter.

Syntax: The number of milliseconds since the Unix epoch (January 1, 1970).

Examples:

  • "timeOfDay":631458180000 // 13:03, 4 January 1990. Typical traffic on Thursdays at 1:03 p.m.
  • "timeOfDay": 631731600000 // 17:00, 7 January 1990. Typical traffic on Sundays at 5:00 p.m.
  • "timeOfDay": 1413964800000 // 8:00, 22 October 2014. If the current time is between 8:00 p.m., 21 Oct. 2014 and 8:00 p.m., 22 Oct. 2014, live traffic speeds are referenced in the analysis; otherwise, typical traffic speeds are referenced.
  • "timeOfDay": 1426674000000 // 10:20, 18 March 2015. If the current time is between 10:20 p.m., 17 Mar. 2015 and 10:20 p.m., 18 Mar. 2015, live traffic speeds are referenced in the analysis; otherwise, typical traffic speeds are referenced.

timeZoneForTimeOfDay

Specify the time zone or zones of the timeOfDay parameter. There are two options: GeoLocal (default) and UTC.

GeoLocal:

The timeOfDay value refers to the time zone or zones in which the input points are located. This option causes the analysis to have rolling start times across time zones.

GeoLocal Illustration: Setting timeOfDay to 9:00 a.m., 4 January 1990 (631443600000 milliseconds); timeZoneForTimeOfDay to GeoLocal; and submitting a valid request causes the drive times for points in the Eastern Time Zone to start at 9:00 a.m. Eastern Time and 9:00 a.m. Central Time for points in the Central Time Zone. (The start times are offset by an hour in real or UTC time.)

Input: timeOfDay is 9:00 a.m., 4 Jan. 1990 (631443600000 milliseconds), and timeZoneForTimeOfDay is set to GeoLocal

UTC:

The timeOfDay value refers to Coordinated Universal Time (UTC). The start times for all points are simultaneous, regardless of time zones.

UTC Illustration: Setting timeOfDay to 9:00 a.m., 4 January 1990 (631443600000 milliseconds) and timeZoneForTimeOfDay to UTC, the start time for points in the Eastern Time Zone is 4:00 a.m. Eastern Time and 3:00 a.m. Central Time for those in the Central Time Zone.

Input: timeOfDay is 9:00 a.m., 4 Jan. 1990 (631443600000 milliseconds), and timeZoneForTimeOfDay is set to UTC

Values: GeoLocal | UTC

travelDirection

Determines whether to measure travel times or distances from facilities to demand locations or from demand locations to facilities. The default is FacilityToDemand.

Values: FacilityToDemand | DemandToFacility

Example: "travelDirection" : "DemandToFacility"

requiredFacilitiesLayer

(Required if goal is set to Allocate. Optional for all other goals. )

A point layer specifying one or more locations that act as facilities by providing some kind of service. Facilities specified by this parameter are required to be part of the output solution and will be used before any facilities from the candidatesFacilitiesLayer when allocating demand locations.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A feature collection

Examples:

  • {"url": <feature service layer url>, "filter": <where clause>}
  • {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

requiredFacilitiesCapacity

A double value representing how much demand every facility in the requiredFacilitiesLayer is capable of supplying. default value is unlimited (2,147,483,647).

requiredFacilitiesCapacityField

A field on the requiredFacilitiesLayer representing how much demand each facility in the requiredFacilitiesLayer is capable of supplying. If specified, the requiredFacilitiesCapacity parameter is ignored.

Example: "requiredFacilitiesCapacityField" : "NumberOfSeats"

candidateFacilitiesLayer

(Required for all goals except Allocate.)

A point layer specifying one or more locations that act as facilities by providing some kind of service. Facilities specified by this parameter are not required to be part of the output solution and will be used only after all the facilities from the requiredFacilitiesLayer have been used when allocating demand locations.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A feature collection

Examples:

  • {"url": <feature service layer url>, "filter": <where clause>}
  • {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

candidateCount

The number of candidate facilities to choose when allocating demand locations. Note that the sum of the features in the requiredFacilitiesLayer and the value specified for candidateCount cannot exceed 100. The default value is 1.

candidateFacilitiesCapacity

A double value representing how much demand every facility in the candidateFacilitiesLayer is capable of supplying. default value is unlimited (2,147,483,647.0).

candidateFacilitiesCapacityField

A field on the candidateFacilitiesLayer representing how much demand each facility in the candidatesFacilitiesLayer is capable of supplying. If specified, the candidateFacilitiesCapacity parameter is ignored.

percentDemandCoverage

A double value containing the percentage of the total demand that you want the candidate and required facilities to capture. The default value is 100.

outputName

If provided, the task will create a feature service of the results. You define the name of the service. If an outputName value is not provided, the task will return a feature collection.

Syntax:

{
  "serviceProperties": {
    "name": "<service name>"
  }
}
In ArcGIS Online or ArcGIS Enterprise 10.9.1 and later, you can overwrite an existing feature service by providing the itemId value of the existing feature service and setting the overwrite property to true. Including the serviceProperties parameter is optional. As described in the Feature output topic, you must either be the owner of the feature service or have administrative privileges to perform the overwrite.

Syntax:

{

  "itemProperties": {
			"itemId": "<itemID of the existing feature service>",
			"overwrite": true
	}
}
or
{
"serviceProperties": {
    "name": "<existing service name>"
  },
"itemProperties": {
				"itemId": "<itemID of the existing feature service>",
				"overwrite": true
	}
}

pointBarrierLayer

Specify one or more point features that act as temporary restrictions (barriers) when traveling on the underlying streets.

A point barrier can model a fallen tree, an accident, a downed electrical line, or anything that completely blocks traffic at a specific position along the street. Travel is permitted on the street but not through the barrier.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A feature collection

Examples:

  • {"url": <feature service layer url>, "filter": <where clause>}
  • {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

lineBarrierLayer

Specify one or more line features that prohibit travel anywhere the lines intersect the streets.

A line barrier prohibits travel anywhere the barrier intersects the streets. For example, a parade or protest that blocks traffic across several street segments can be modeled with a line barrier.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A feature collection

Examples:

  • {"url": <feature service layer url>, "filter": <where clause>}
  • {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

polygonBarrierLayer

Specify one or more polygon features that completely restrict travel on the streets intersected by the polygons.

One use of this type of barrier is to model floods covering areas of the street network and making road travel there impossible.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A feature collection

Examples:

  • {"url": <feature service layer url>, "filter": <where clause>}
  • {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

context

The Context parameter contains the following additional settings that affect task operation:

  • Extent (extent)—A bounding box that defines the analysis area. Only input features that intersect the bounding box will be analyzed.
  • Output spatial reference (outSR)—The output features will be projected into the output spatial reference.

Syntax:

{
"extent" : {extent},
"outSR" : {spatial reference}
}

f

The response format. The default response format is html.

Values: html | json

Response

When you submit a request, the service assigns a unique job ID for the transaction.

Syntax:
{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}

After the initial request is submitted you can use the jobId to periodically check the status of the job and messages as described in the topic Checking job status. Once the job has successfully completed, you use the jobId to retrieve the results. To track the status, you can make a request of the following form:

http://<analysis url>/ChooseBestFacilities/jobs/<jobId>

Accessing results

When the status of the job request is esriJobSucceded, you can access the results of the analysis by making a request of the following form.

http://<analysis url>/ChooseBestFacilities/jobs/<jobId>/results/allocatedDemandLocationsLayer?token=<your token>&f=json

ParameterDescription

allocatedDemandLocationsLayer

The output layer containing the set of demand locations that were allocated to a facility.

Example:
{"url": 
"http://<analysis url>/ChooseBestFacilities/jobs/<jobId>/results/allocatedDemandLocationsLayer"}

The result has properties for parameter name, data type, and value. The contents of value depends upon the outputName parameter provided in the initial request.

  • If outputName was provided, value contains the url to the feature service layer.

    {
    "paramName":"allocatedDemandLocationsLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }

  • If outputName was not provided, value contains a feature collection.

    {
    "paramName":"allocatedDemandLocationsLayer",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {} }
    }

See Feature Output for more information about how the result layer or collection is accessed.

allocationLinesLayer

The output layer containing a set of lines, each line connecting the demand location to its assigned facility.

Example:
{"url": 
"http://<analysis url>/ChooseBestFacilities/jobs/<jobId>/results/allocationLinesLayer"}

The result has properties for parameter name, data type, and value. The contents of value depends upon the outputName parameter provided in the initial request.

  • If outputName was provided, value contains the url to the feature service layer.

    {
    "paramName":"allocationLinesLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }

  • If outputName was not provided, value contains a feature collection.

    {
    "paramName":"allocationLinesLayer",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {} }
    }

See Feature Output for more information about how the result layer or collection is accessed.

assignedFacilitiesLayer

The output layer containing the facilities that were assigned demand.

Example:
{"url": 
"http://<analysis url>/ChooseBestFacilities/jobs/<jobId>/results/assignedFacilitiesLayer"}

The result has properties for parameter name, data type, and value. The contents of value depends upon the outputName parameter provided in the initial request.

  • If outputName was provided, value contains the url to the feature service layer.

    {
    "paramName":"assignedFacilitiesLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }

  • If outputName was not provided, value contains a feature collection.

    {
    "paramName":"assignedFacilitiesLayer",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {} }
    }

See Feature Output for more information about how the result layer or collection is accessed.