Using geoprocessing tools

In the ArcGIS API for Python, geoprocessing toolboxes and tools within them are represented as Python modules and functions. To learn more about this structure, refer to the page titled Accessing geoprocessing tools.

Invoking Geoprocessing Tools

You can execute a geoprocessing tool easily by importing its toolbox as a module and calling the function for the tool. Let us see how to execute the extract_zion_data tool from the Zion toolbox URL:

# connect to ArcGIS Online
from arcgis.gis import GIS
from arcgis.geoprocessing import import_toolbox
gis = GIS()

# import the Zion toolbox
zion_toolbox_url = 'http://gis.ices.dk/gis/rest/services/Tools/ExtractZionData/GPServer'
zion = import_toolbox(zion_toolbox_url)

result = zion.extract_zion_data()

Submitted.
Executing...

Executing a geoprocessing tool is that simple. Let's learn a few more concepts that will help in using these tools efficiently.

Understanding tool input parameter and output return types

The functions for calling geoprocessing tools can accept and return built-in Python types such as str, int, bool, float, dicts, datetime.datetime, as well as some helper types defined in the ArcGIS API for Python, including:

arcgis.features.FeatureSet - a set of features
arcgis.geoprocessing.LinearUnit - linear distance with specified units
arcgis.geoprocessing.DataFile - a url or item id referencing data
arcgis.geoprocessing.RasterData - url or item id and format of raster data

The tools can also accept lists of the above types.

Note: When the helper types are used an input, the function also accepts strings in their place. For example '5 Miles' can be passed as an input instead of LinearUnit(5, 'Miles') and a URL can be passed instead of a DataFile or RasterData input.

Some geoprocessing tools are configured to return an arcgis.mapping.MapImageLayer for visualizing the results of the tool.

In all cases, the documentation of the tool function indicates the type of input parameters and the output values.

Using helper types

The helper types (LinearUnit, DataFile and RasterData) defined in the arcgis.geoprocessing module are simple classes that hold strings or URLs and have a dictionary representation.

The extract_zion_data() tool invoked above returns an output zip file as a DataFile:

type(result)

arcgis.geoprocessing._types.DataFile

The output Datafile can be queried as shown in the snippet below.

result

{"url": "http://gis.ices.dk/gis/rest/directories/arcgisjobs/tools/extractziondata_gpserver/j48b6f17abdf142679b11e3a71adcce8d/scratch/output.zip"}

The value types such as DataFile include helpful methods such as download:

result.download()

'C:\\Users\\rohit\\AppData\\Local\\Temp\\output.zip'

Using strings as input

Strings can also be used as inputs in place of the helper types such as LinearUnit, RasterData and DataFile.

The example below calls the viewshed tool to compute and display the geographical area that is visible from a clicked location on the map. The function accepts an observation point as a FeatureSet and a viewshed distance as a LinearUnit, and returns a FeatureSet:

viewshed = import_toolbox('http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Elevation/ESRI_Elevation_World/GPServer')

help(viewshed.viewshed)

Help on function viewshed:

viewshed(input_observation_point:arcgis.features.feature.FeatureSet={'Fields': [{'name': 'FID', 'alias': 'FID', 'type': 'esriFieldTypeOID'}, {'name': 'Shape', 'alias': 'Shape', 'type': 'esriFieldTypeGeometry'}, {'name': 'OffsetA', 'alias': 'OffsetA', 'type': 'esriFieldTypeDouble'}], 'fields': [{'name': 'FID', 'alias': 'FID', 'type': 'esriFieldTypeOID'}, {'name': 'Shape', 'alias': 'Shape', 'type': 'esriFieldTypeGeometry'}, {'name': 'OffsetA', 'alias': 'OffsetA', 'type': 'esriFieldTypeDouble'}], 'geometryType': 'esriGeometryPoint', 'spatialReference': {'wkid': 54003}}, viewshed_distance:arcgis.geoprocessing._types.LinearUnit={'units': 'esriMeters', 'distance': 15000}, gis=None) -> arcgis.features.feature.FeatureSet
            
    
    
    Parameters:
    
       input_observation_point: Input Observation Point (FeatureSet). Required parameter. 
    
       viewshed_distance: Viewshed Distance (LinearUnit). Required parameter. 
    
            gis: Optional, the GIS on which this tool runs. If not specified, the active GIS is used.
    
    
    Returns: 
       viewshed_result - Viewshed Result as a FeatureSet
    
    See http://sampleserver1c.arcgisonline.com/arcgisoutput/Elevation_ESRI_Elevation_World/Viewshed.htm for additional help.

import arcgis
arcgis.env.out_spatial_reference = 4326

Tools with multiple outputs

Some Geoprocessing tools can return multiple results. For these tools, the corresponding function returns the multiple output values as a named tuple.

The example below uses a tool that returns multiple outputs:

sandiego_toolbox_url = 'https://gis-public.co.san-diego.ca.us/arcgis/rest/services/InitialResearchPacketCSV_Phase2/GPServer'
multioutput_tbx = import_toolbox(sandiego_toolbox_url)

help(multioutput_tbx.initial_research_packet_csv)

Help on function initial_research_packet_csv:

initial_research_packet_csv(apn_numbers:str='5980100200', project_number:str='PDS2012-3200-21193', project_title:str='PDS', gis=None) -> tuple
            
    Script for getting user's inputs and call python script to create data in term of CSV
    
    Parameters:
    
       apn_numbers: APN Numbers (str). Required parameter.  List of APNs seperated by comma.e.g.:1015300300e.g:102-690-07-00,1021809100,1021807700
    
       project_number: Project Number (str). Required parameter.  Project number
    
       project_title: Project Title (str). Required parameter.  Project Title
    
            gis: Optional, the GIS on which this tool runs. If not specified, the active GIS is used.
    
    
    Returns the following as a named tuple:
       report_output_csv_file - Report Output CSV File as a DataFile
       output_map_flags_file - Output Map Flags File as a DataFile
       soil_output_file - Soil Output File as a DataFile
       job_status - Job Status as a str
    
    See http://gis-public.co.san-diego.ca.us/arcgis/rest/directories/arcgisoutput/InitialResearchPacketCSV_Phase2_GPServer/InitialResearchPacketCSV_Phase2/InitialResearchPacket.htm for additional help.

Invoking tools that create multple outputs

The code snippet below shows how multiple outputs returned from a tool can be automatically unpacked by Python into multiple variables. Additionally, since we're not interested in the job status output, we can discard it using "_" as the variable name:

report_output_csv_file, output_map_flags_file, soil_output_file, _ = multioutput_tbx.initial_research_packet_csv()

Submitted.
Executing...

report_output_csv_file

{"url": "http://gis-public.co.san-diego.ca.us/arcgis/rest/directories/arcgisjobs/initialresearchpacketcsv_phase2_gpserver/j4eb207e79c0c4f53875b56da9bb3f015/scratch/j4eb207e79c0c4f53875b56da9bb3f015_report.csv"}

output_map_flags_file

{"url": "http://gis-public.co.san-diego.ca.us/arcgis/rest/directories/arcgisjobs/initialresearchpacketcsv_phase2_gpserver/j4eb207e79c0c4f53875b56da9bb3f015/scratch/j4eb207e79c0c4f53875b56da9bb3f015_mapflags.txt"}

soil_output_file

{"url": "http://gis-public.co.san-diego.ca.us/arcgis/rest/directories/arcgisjobs/initialresearchpacketcsv_phase2_gpserver/j4eb207e79c0c4f53875b56da9bb3f015/scratch/j4eb207e79c0c4f53875b56da9bb3f015_soil.txt"}

Using named tuple to access multiple tool outputs

The code snippet below shows using a named tuple to access the multiple outputs returned from the tool:

results = multioutput_tbx.initial_research_packet_csv()

Submitted.
Executing...

results.report_output_csv_file

{"url": "http://gis-public.co.san-diego.ca.us/arcgis/rest/directories/arcgisjobs/initialresearchpacketcsv_phase2_gpserver/j38da5f0c5a5b4136b03a2d9d693bbc8d/scratch/j38da5f0c5a5b4136b03a2d9d693bbc8d_report.csv"}

results.job_status

'Successfully created csv file'

Tools that export MapImageLayer as output

Some Geoprocessing tools are configured to return their output as MapImageLayer for easier visualization of the results. The resulting layer can be added to a map or queried.

An example of such a tool is below:

hotspots = import_toolbox('https://sampleserver6.arcgisonline.com/arcgis/rest/services/911CallsHotspot/GPServer')

help(hotspots.execute_911_calls_hotspot)

Help on function execute_911_calls_hotspot:

execute_911_calls_hotspot(query:str='("DATE" > date \'1998-01-01 00:00:00\' AND "DATE" < date \'1998-01-31 00:00:00\') AND ("Day" = \'SUN\' OR "Day"= \'SAT\')', gis=None) -> tuple
            
    The tool filters 911 calls based on the query provided by the client and creates a hotspot raster based on the frequency of calls. The hotspot raster is created using the Spatial Statistics Hot Spot Analysis tool, which uses the Getis‐Ord Gi* algorithm. The Hotspots represent statistically significant spatialclusters of high and low 911 emergency calls in the study area. The red regions in the raster indicates high frequency and the blue regions represent low frequency of calls.
    
    Parameters:
    
       query: Query (str). Required parameter.  A SQL query string to filter calls. The query can be based on the day of the week such as SUN/MON/TUE/WED/THU/FRI/SAT (Field Name: Day) or a date range between Jan 1st ,1998 to May 31, 1998 (Field Name: Date). An example SQL query string is ("DATE" &gt; date '1998-01-01 00:00:00' AND "DATE" &lt; date '1998-01-31 00:00:00') AND ("Day" = 'SUN' OR "Day"= 'SAT')
    
            gis: Optional, the GIS on which this tool runs. If not specified, the active GIS is used.
    
    
    Returns the following as a named tuple:
       result_layer - Result Layer as a MapImageLayer
       output_features - Output_Features as a dict
       hotspot_raster - Hotspot Raster as a dict
    
    See https://sampleserver6.arcgisonline.com/arcgis/rest/directories/arcgisoutput/911CallsHotspot_GPServer/911CallsHotspot/911CallsHotspot.htm for additional help.

result_layer, output_features, hotspot_raster = hotspots.execute_911_calls_hotspot()

Submitted.
Executing...

result_layer

<MapImageLayer url:"https://sampleserver6.arcgisonline.com/arcgis/rest/services/911CallsHotspot/MapServer/jobs/je7c507da0a2e45f796a170348248b4dc">

hotspot_raster

{'mapImage': {'extent': {'spatialReference': {'latestWkid': 102726,
    'wkid': 102726},
   'xmax': 7628948.291202795,
   'xmin': 7586498.220384206,
   'ymax': 687779.355638728,
   'ymin': 645329.284820139},
  'height': 400,
  'href': 'https://sampleserver6.arcgisonline.com/arcgis/rest/directories/arcgisoutput/911CallsHotspot_GPServer/911CallsHotspot_MapServer/_ags_map65dac050231e4acaa56e205d00f922fe.png',
  'scale': 122256.20395753652,
  'width': 400}}

The resultant hotspot raster can be visualized in the Jupyter Notebook using the code snippet below:

from IPython.display import Image
Image(hotspot_raster['mapImage']['href'])