ServiceArea

サマリー

An ArcPy class for performing a service area analysis.

説明

A service area analysis allows you to calculate the area reachable from one or more facilities within a designated time or distance limit.

Learn more about service area analysis

構文

ServiceArea (in_network)
パラメーター説明データ タイプ
in_network

The network dataset or service that will be used for the network analysis. The argument can be specified using the catalog path to the network dataset, a network dataset layer object, the string name of the network dataset layer, or a portal URL for a network analysis service. The network must have at least one travel mode.

To use a portal URL, you must be signed in to the portal with an account that has routing privileges.

Solving an analysis will consume credits when the object uses ArcGIS Online as the in_network. For more information, see Service Credits Overview

String

プロパティ

プロパティ説明データ タイプ
accumulateAttributeNames
(読み書き)

A list of cost attributes to be accumulated during analysis. These accumulated attributes are for reference only; the solver only uses the cost attribute used by your designated travel mode when solving the analysis.

The default is an empty list.

String
allowSaveLayerFile
(読み書き)

Specifies whether to permit saving the analysis result as a layer file using the saveAsLayerFile method on the result object. A value of True means that you can save a layer file. A value of False means that you cannot. The default is True if the analysis references a network dataset and False if it references a portal service. Allowing a layer file to be saved may slow down the analysis when the analysis references a portal service.

Boolean
defaultImpedanceCutoffs
(読み書き)

The extent of the service area to be calculated. The service area output shows the area reachable from the starting facility within this impedance cutoff. The default is an empty list, but at least one cutoff must be specified prior to solving the service area.

If the travel mode used in the analysis uses a time-based impedance attribute, the defaultImpedanceCutoffs values are interpreted in the units specified in the timeUnits property. If the travel mode used in the analysis uses a distance-based impedance attribute, the defaultImpedanceCutoffs values are interpreted in the units specified in the distanceUnits property. If the travel mode's impedance attribute is neither time based nor distance based, the defaultImpedanceCutoffs values are interpreted in the units of the impedance attribute. The default is [5, 10, 15].

The values can be overridden on a per-facility basis by specifying individual cutoff values in the Facilities input data type.

The defaultImpedanceCutoffs can be overridden on a per-facility basis using the Breaks field in the input facilities.

Double
distanceUnits
(読み書き)

The units to use when reporting the travel distance in the analysis output. Regardless of the units of the cost attributes in the network dataset, the output will be transformed to and reported in the units set in this property. The property is returned and set as a member of the DistanceUnits enumeration. The default is DistanceUnits.Kilometers.

Object
excludeSourcesFromPolygonGeneration
(読み書き)

The list of network dataset edge sources exclude when generating polygons. Learn more about excluding edge sources from service area polygon generation.

The property is returned and set as a list of strings where each list item is the name of the network edge source. The default is an empty list, which means that no edge sources are excluded from polygon generation.

String
geometryAtCutoff
(読み書き)

Controls the behavior of the output polygons for a single facility when multiple values are specified in the defaultImpedanceCutoffs property. The property is returned and set as a member of the ServiceAreaPolygonCutoffGeometry enumeration. The default is ServiceAreaPolygonCutoffGeometry.Rings.

Object
geometryAtOverlap
(読み書き)

Controls the behavior of the service area output from multiple facilities in relation to one another. The property is returned and set as a member of the ServiceAreaOverlapGeometry enumeration. The default is ServiceAreaOverlapGeometry.Overlap.

Object
ignoreInvalidLocations
(読み書き)

Specifies whether invalid input locations will be ignored. A value of True indicates that invalid input locations will be ignored so that the analysis will succeed using only valid locations. A value of False indicates that invalid locations will not be ignored and will cause the analysis to fail.

レガシー:

Routing services based on portals running versions of ArcGIS Enterprise older than 10.9 always ignore invalid input locations. The method returns a ValueError exception if you set ignoreInvalidLocations to False and the service does not support this option.

Boolean
networkDataSource
(読み取り専用)

The full catalog path to the network dataset used for the analysis.

String
outputType
(読み書き)

The type of output to be generated for the analysis. Choose whether to generate polygons, lines, or both. The property is returned and set as a member of the ServiceAreaOutputType enumeration. The default is ServiceAreaOutputType.Polygons.

Object
overrides
(読み書き)

Specify 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 either a number, Boolean, or string.

The default value for this parameter is no value, which indicates to not 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. A list of supported override settings for each solver and their acceptable values can be obtained by contacting Esri Technical Support.

String
polygonBufferDistance
(読み書き)

到達圏ポリゴンの切詰め距離。 ポリゴンの切詰め距離は、ライン バッファー サイズと同様に、他に到達可能な道路が近くにない場合に、到達圏ポリゴンが道路から延長する距離です。 ネットワークがまばらで、フィーチャが存在しない広範領域が到達圏内に含まれるのを防ぎたい場合に役立ちます。

The units for the buffer distance value are specified in the polygonBufferDistanceUnits property. The default is 100.

Double
polygonBufferDistanceUnits
(読み書き)

The units for the polygonBufferDistance property. The property is returned and set as a member of the DistanceUnits enumeration. The default is DistanceUnits.Meters.

Object
polygonDetail
(読み書き)

Specifies the desired level of detail for the output polygons. Learn more about polygon detail level. The property is returned and set as a member of the ServiceAreaPolygonDetail enumeration. The default is ServiceAreaPolygonDetail.Standard.

Object
searchQuery
(読み書き)

When locating inputs on the network, specifies a query to restrict the search to a subset of the features within a source feature class. This is useful if you don't want to find features that may be unsuited for a network location. For example, if you are loading centroids of polygons and don't want to locate on local roads, you can define a query that searches for major roads only.

Learn more about locating inputs on the network

The parameter value is specified as a list with nested lists. The nested list is composed of two values indicating the name and the SQL expression for all of the network sources. The syntax for the SQL expression differs slightly depending on the type of the network source feature class. For example, if you're querying source feature classes stored in file or enterprise geodatabases, shapefiles, or SDC, enclose field names in double quotation marks: "CFCC". If you're querying source feature classes stored in personal geodatabases, enclose fields in square brackets: [CFCC].

If you don't want to specify a query for a particular source, use "#" as the value for the SQL expression or exclude the source name and the SQL expression from the parameter value. If you don't want to specify a query for all of the network sources, use "#" as the parameter value.

For example, the parameter value [["Streets","\"CFCC\" = 'A15'"], ["Streets_ND_Junctions",""]] specifies an SQL expression for the Streets source feature class and no expression for the Streets_ND_Junctions source feature class. Note that the double quotation marks used to enclose the field name CFCC are escaped using backslash characters to avoid a parsing error from the Python interpreter.

By default, no query is used.

List
searchTolerance
(読み書き)

The maximum search distance to use when locating the input features on the network. The property is returned and set as a double, and the units of this value are accessed through the searchToleranceUnits property. The default is 5000.

Learn more about locating inputs on the network

Double
searchToleranceUnits
(読み書き)

The units of the searchTolerance property. The property is returned and set as a member of the DistanceUnits enumeration. The default is DistanceUnits.Meters.

Object
timeOfDay
(読み書き)

The time of day to use for the analysis. The default is None, which means that the analysis will be time neutral.

DateTime
timeUnits
(読み書き)

The units to use when reporting the travel time in the analysis output. Regardless of the units of the cost attributes in the network dataset, the outputs will be transformed to and reported in the units set in this property. The property is returned and set as a member of the TimeUnits enumeration. The default is TimeUnits.Minutes.

Object
timeZone
(読み書き)

Indicates whether the time specified in the timeOfDay property will be interpreted as the local time at the input locations or as coordinated universal time (UTC). The property is returned and set as a member of the TimeZoneUsage enumeration and is applicable only when the timeOfDay property is not None. The default is TimeZoneUsage.LocalTimeAtLocations.

Object
travelDirection
(読み書き)

The direction of travel with respect to the facilities. The property is returned and set as a member of the TravelDirection enumeration. The default is TravelDirection.FromFacility.

If the travel direction is TravelDirection.FromFacility, the timeOfDay is interpreted to mean the departure time from the facility. If the travel direction is TravelDirection.ToFacility, the timeOfDay is interpreted to mean the arrival time at the facility.

Object
travelMode
(読み書き)

The travel mode to use for the analysis.

The value is returned and set as an arcpy.nax.TravelMode object, but it can also be set using the string name of the travel mode or a string containing the valid JSON representation of a travel mode. The default is the default travel mode defined on the network dataset used for the analysis.

Learn more about travel modes

Object

方法の概要

方法説明
addFields (input_type, field_description)

Adds custom fields to the designated input class. These fields will be included in the field mapping dictionary created by the fieldMappings method and will also be available for use with the insertCursor method.

count (input_type)

Returns the number of rows added for an input type.

fieldMappings (input_type, {use_location_fields}, {list_candidate_fields})

Generates an NAClassFieldMappings dictionary that maps the field names of the input type to arcpy.nax.NAClassFieldMap objects that allow you to map fields from your input data to the properties of the solver. The dictionary can be used as input to the load method's field_mappings argument.

fieldNames (input_type, {use_location_fields})

Get a list of field names supported by the specified input type.

insertCursor (input_type, field_names, {append})

Establishes a write cursor on the specified input type. This cursor can be used to add rows directly to the input.

load (input_type, features, {field_mappings}, {append}, {max_features})

Set input features to use for the analysis.

solve ()

Perform the service area analysis using the properties set on the ServiceArea object and the loaded inputs.

方法

addFields (input_type, field_description)
パラメーター説明データ タイプ
input_type

The type of input to which the fields should be added.

The parameter should be set using the ServiceAreaInputDataType enumeration.

Object
field_description
[field_description,...]

The fields and their properties that will be added to the input class. The value should be constructed as a list of lists with each row containing the following items:

  • Field name—The name of the field that will be added to the input class.
  • Field type—The type of the new field.
  • Field alias—The alternate display name given to the field name.
  • Field length—The length of the field being added. This sets the maximum number of allowable characters for each record of the field. This option is only applicable to fields of type text; the default length is 255.
  • Default value—The default value of the field.
  • Field domain—The geodatabase domain that will be assigned to the field.

Available field types are as follows:

  • TEXT—Any string of characters.
  • FLOAT—Fractional numbers between -3.4E38 and 1.2E38.
  • DOUBLE—Fractional numbers between -2.2E308 and 1.8E308.
  • SHORT—Whole numbers between -32,768 and 32,767.
  • LONG—Whole numbers between -2,147,483,648 and 2,147,483,647.
  • DATE—Date or time.

The method will return an error if the field already exists in the table or if any of the field properties are invalid.

List
count (input_type)
パラメーター説明データ タイプ
input_type

The type of input features to count.

The parameter should be set using the ServiceAreaInputDataType enumeration.

Object
戻り値
データ タイプ説明
Integer

The number of rows.

fieldMappings (input_type, {use_location_fields}, {list_candidate_fields})
パラメーター説明データ タイプ
input_type

The type of input for which the field mappings are returned.

The parameter should be set using the ServiceAreaInputDataType enumeration.

See descriptions of the fields available for each input type

Object
use_location_fields

Indicates whether network location fields should be included in the returned field mappings dictionary. Network location fields describe the point on the network where an object is located. You can use network location fields to more precisely control how your analysis inputs locate on the network and to save time when calling the solve method because the solver will not have to calculate the location fields from the geometry of the inputs. You can calculate location fields for a feature class using the Calculate Locations tool.

Learn more about network location fields and how inputs are located on the network

When this argument is set to True, the returned field mappings dictionary will contain network location fields. The default is False; the field mapping dictionary will not include network location fields.

(デフォルト値は次のとおりです False)

Boolean
list_candidate_fields
[list_candidate_fields,...]

Use this parameter to map additional, non-default fields from your input data into your analysis inputs. For example, if your input feature class contains a field named MyField, and you want this field to be included in your analysis inputs, pass the MyField field object to the list_candidate_fields parameter. MyField will be included in the returned field mapping dictionary and automatically mapped. When you call the load method using these field mappings, MyField will be included in the analysis inputs along with all the default fields. In many cases, these extra fields will be passed to the analysis output as well.

The parameter should be specified as a list of arcpy.Field objects, which can be obtained from a given feature class or table using the arcpy.ListFields function.

Learn more about best practices for setting up analysis inputs

(デフォルト値は次のとおりです None)

Field
戻り値
データ タイプ説明
Dictionary

An NAClassFieldMappings dictionary in which the keys are the field names and values are arcpy.nax.NAClassFieldMap objects.

fieldNames (input_type, {use_location_fields})
パラメーター説明データ タイプ
input_type

The type of input for which the supported field names are returned.

The parameter should be set using the ServiceAreaInputDataType enumeration.

See descriptions of the fields available for each input type

Object
use_location_fields

Indicates whether network location fields will be included in the returned list of field names. Network location fields describe the point on the network where an object is located. You can use network location fields to more precisely control how your analysis inputs locate on the network and to save time when calling the solve method because the solver will not have to calculate the location fields from the geometry of the inputs. You can calculate location fields for a feature class using the Calculate Locations tool.

Learn more about network location fields and how inputs are located on the network

When this argument is set to True, the returned list of field names will contain network location fields. The default is False; the list of field names will not include network location fields.

(デフォルト値は次のとおりです False)

Boolean
戻り値
データ タイプ説明
String

A list of field names supported by the specified input type.

insertCursor (input_type, field_names, {append})
パラメーター説明データ タイプ
input_type

The type of input into which the cursor can be used to insert rows.

The parameter should be set using the ServiceAreaInputDataType enumeration.

Object
field_names
[field_names,...]

A list of field names of the input type whose values you want to set when inserting rows using the cursor. You can get the names of the fields supported by an input type by using the fieldNames method.

See descriptions of the fields available for each input type

In addition to regular fields, you can also set the geometry of the input using one of the following geometry tokens:

  • SHAPE@XYフィーチャの重心を表す X 座標と Y 座標の組み合わせ
  • SHAPE@XYZフィーチャの重心を表す XYZ 座標の組み合わせ
  • SHAPE@JSONジオメトリを表す Esri JSON 文字列
  • SHAPE@WKBOGC ジオメトリの WKB (Well-Known Binary) 表現。 ジオメトリ値の汎用的な表現が、連続的なバイト ストリームとして提供されます。
  • SHAPE@WKTOGC ジオメトリの WKT (Well-Known Text) 表現。 ジオメトリ値の汎用的な表現が、テキスト文字列として提供されます。
  • SHAPE@フィーチャのジオメトリ オブジェクト

The SHAPE@XY and SHAPE@XYZ tokens are only supported for point-based input types. When using the SHAPE@XY and SHAPE@XYZ tokens, the x-, y-, and z-values should be specified in the spatial reference of the network data source being used in the analysis.

String
append

Specifies whether the features being inserted should be appended to the existing set of features for the input type. A value of True indicates that the new features should be appended; the existing features will be preserved. This is the default. A value of False indicates that any existing features for the input type should be deleted and replaced with the features currently being inserted.

(デフォルト値は次のとおりです True)

Boolean
戻り値
データ タイプ説明
Object

A SolverInsertCursor object that can be used to write features.

load (input_type, features, {field_mappings}, {append}, {max_features})
パラメーター説明データ タイプ
input_type

The type of input feature to load.

The parameter should be set using the ServiceAreaInputDataType enumeration.

Object
features

The input features to load. This parameter accepts the following input types:

  • Catalog path to a feature class or a table
  • Layer object
  • String representing the name of a layer
  • FeatureSet or RecordSet object

For layer inputs, only selected features will be loaded. If a layer has a definition query, only the subset of features visible with the definition query will be loaded. The method also honors the Extent geoprocessing environment; only features in the specified extent will be loaded.

String
field_mappings

An NAClassFieldMappings dictionary that maps the field names of the input type to arcpy.nax.NAClassFieldMap objects representing the mapping of fields from the input features. Valid input for this parameter can be constructed using the fieldMappings method.

If field mappings are not specified, all fields from the input features that have the same name as the supported fields for the input type will be mapped.

(デフォルト値は次のとおりです None)

Dictionary
append

Indicates whether the features being loaded should be appended to the existing set of features for the input type. A value of True indicates that the new features should be appended; the existing features will be preserved. This is useful if you want to load inputs from multiple feature classes or tables to use in a single analysis. This is the default. A value of False indicates that any existing features for the input type should be deleted and replaced with the features currently being loaded.

(デフォルト値は次のとおりです True)

Boolean
max_features

The maximum number of features that can be loaded into the input type. This is useful if you are creating a tool or service and want an error returned if the size of the input exceeds the available resources. The load method will return an arcpy.nax.LimitError if the number of input features exceeds the max_features limit.

If a value is not specified, no limit is enforced for the count of the input features.

(デフォルト値は次のとおりです None)

Integer
solve ()
戻り値
データ タイプ説明
Object

An arcpy.nax.ServiceAreaResult object that can be used to access outputs and solver messages.

コードのサンプル

ServiceArea example

Perform service area analysis.

# An example showing how to perform service area analysis using a feature class for input facilities.
import arcpy
arcpy.CheckOutExtension("network")

nds = "C:/data/NorthAmerica.gdb/Routing/Routing_ND"
nd_layer_name = "Routing_ND"
input_facilities = "C:/data/io.gdb/Facilities"
output_polygons = "C:/data/io.gdb/ServiceAreaPolygons"

# Create a network dataset layer and get the desired travel mode for analysis
arcpy.nax.MakeNetworkDatasetLayer(nds, nd_layer_name)
nd_travel_modes = arcpy.nax.GetTravelModes(nd_layer_name)
travel_mode = nd_travel_modes["Driving Time"]

# Instantiate a ServiceArea solver object
service_area = arcpy.nax.ServiceArea(nd_layer_name)
# Set properties
service_area.timeUnits = arcpy.nax.TimeUnits.Minutes
service_area.defaultImpedanceCutoffs = [5, 10, 15]
service_area.travelMode = travel_mode
service_area.outputType = arcpy.nax.ServiceAreaOutputType.Polygons
service_area.geometryAtOverlap = arcpy.nax.ServiceAreaOverlapGeometry.Split
# Load inputs
service_area.load(arcpy.nax.ServiceAreaInputDataType.Facilities, input_facilities)
# Solve the analysis
result = service_area.solve()

# Export the results to a feature class
if result.solveSucceeded:
    result.export(arcpy.nax.ServiceAreaOutputDataType.Polygons, output_polygons)
else:
    print("Solve failed")
    print(result.solverMessages(arcpy.nax.MessageSeverity.All))