Accessing geoprocessing tools

In this page we will observe how you can search for geoprocessing tools and access them in your code. Thus, we will observe:

Searching for geoprocessing tools

Geoprocessing tools can be considered as web tools that can shared with others. Users organize their tools into toolboxes and share with on their GIS. You can search for geoprocessing tools just like you search for any other item.

To search your GIS for geoprocessing toolboxes, specify Geoprocessing Toolbox as the item type.

In [1]:
import arcgis
from arcgis.gis import GIS
from IPython.display import display
In [3]:
gis = GIS('https://www.arcgis.com', 'arcgis_python', 'P@ssword123')
In [4]:
toolboxes = gis.content.search('travel', 'Geoprocessing Toolbox', 
                               outside_org=True, max_items=3)
In [5]:
for toolbox in toolboxes:
    display(toolbox)
DriveTimePolygonsService
This tool calculates drive-time polygons in Lagos Metropolis. The drive-time polygons represent areas that can be reached within a given amount of time when departing from a facility and traveling along the road network. Optionally, the polygons can Geoprocessing Toolbox by omolarakareem
Last Modified: March 27, 2013
0 comments, 316 views
Ocean Currents
Calculates the path of an unpowered vessel drifiting in ocean currents from a user defined point. Excludes wind or atmospheric conditions.Geoprocessing Toolbox by esri_apac
Last Modified: August 25, 2014
1 comments, 165 views
World Origin Destination Cost Matrix
OriginDestinationCostMatrix, currently in beta, is an ArcGIS Online service that helps you to create an origin-destination cost matrix from multiple origins to multiple destinations. ArcGIS Online subscription required.Geoprocessing Toolbox by esri
Last Modified: June 21, 2016
0 comments, 42 views

Pythonic representation of tools and toolboxes

In ArcGIS API for Python, geoprocessing toolboxes are represented as Python modules and the individual tools as Python functions. These tools, represented as Python functions, take in a set of input parameters and return one or more output values.

To use custom geoprocessing tools, users simply import that toolbox as a module in their programs and call functions within the module.

Importing toolboxes

The import_toolbox() function in the arcgis.geoprocessing module imports geoprocessing toolboxes as native Python modules. It accepts a toolbox location which could be a Geoprocessing Toolbox item in your GIS, or a URL to a Geoprocessing Service.

Developers can then call the functions available in the imported module to invoke these tools. Let us see how to import toolboxes from these two sources.

Importing toolbox from an Item

The code snippet below shows how the Ocean Currents toolbox above can be imported as a module:

In [6]:
from arcgis.geoprocessing import import_toolbox
In [7]:
ocean_currents_toolbox = toolboxes[1]
ocean_currents_toolbox
Out[7]:
Ocean Currents
Calculates the path of an unpowered vessel drifiting in ocean currents from a user defined point. Excludes wind or atmospheric conditions.Geoprocessing Toolbox by esri_apac
Last Modified: August 25, 2014
1 comments, 165 views
In [8]:
ocean_currents = import_toolbox(ocean_currents_toolbox)

The import_toolbox() function inspects the geoprocessing toolbox and dynamically generates a Python module containing a function for each tool within the toolbox. Invoking the function invokes the corresponding geoprocessing tool.

The code snippet below uses Python's inspect module to list the public functions in the imported module. Developers will typically use their IDE's intellisense to discover the functions in the module.

In [9]:
import inspect

# list the public functions in the imported module
[ f[0] for f in inspect.getmembers(ocean_currents, inspect.isfunction) 
             if not f[0].startswith('_')]
Out[9]:
['message_in_a_bottle']

Importing toolbox from a geoprocessing service URL

The example below uses a URL to a geoprocessing service to import a geoprocessing toolbox:

In [10]:
zion_toolbox_url = 'http://gis.ices.dk/gis/rest/services/Tools/ExtractZionData/GPServer'
zion = import_toolbox(zion_toolbox_url)

Tool signature, parameters and documentation

The function for invoking the geoprocessing tool includes documentation about that tool. This doc shows up using your IDE's intellisense and can also be accessed using Python's help function:

In [11]:
help(zion.extract_zion_data)
Help on function extract_zion_data:

extract_zion_data(layers_to_clip:str="['Research_areas', 'Roads', 'Springs', 'Zion park boundary']", area_of_interest:arcgis.features.feature.FeatureSet={'exceededTransferLimit': False, 'fields': [{'name': 'FID', 'alias': 'FID', 'type': 'esriFieldTypeOID'}, {'name': 'Id', 'alias': 'Id', 'type': 'esriFieldTypeInteger'}, {'name': 'Shape_Length', 'alias': 'Shape_Length', 'type': 'esriFieldTypeDouble'}, {'name': 'Shape_Area', 'alias': 'Shape_Area', 'type': 'esriFieldTypeDouble'}], 'features': [], 'displayFieldName': '', 'spatialReference': {'wkid': None}, 'geometryType': 'esriGeometryPolygon'}, feature_format:str='File Geodatabase - GDB - .gdb', raster_format:str='ESRI GRID - GRID', gis=None) -> arcgis.geoprocessing._types.DataFile
            
     Extracts the specified Layers in the specified Area of Interest to the selected Formats and returns all the data in a zip file. This tool is intended primarily for use as a part of a geoprocessing service. Full step by step instructions for making a Clip and Ship / Data Extraction geoprocessing service can be found here (under construction).When using this tool as a part of a geoprocessing service, first copy the tool into a custom toolbox. After copying, edit the model and configure it if necessary.
    
    Parameters:
    
       layers_to_clip: Layers to Clip (str). Required parameter.  The Layers to be clipped. Layers should be either raster layers or feature layers.
          Choice list:['Research_areas', 'Tracts', 'Roads', 'Trails', 'Springs', 'Streams', 'Zion park boundary', 'Hillshade']
    
       area_of_interest: Area of Interest (FeatureSet). Required parameter.  The area by which the layers will be clipped.
    
       feature_format: Feature Format (str). Required parameter.  The format in which the output features will be delivered.
          Choice list:['File Geodatabase - GDB - .gdb', 'Shapefile - SHP - .shp', 'Geographic Markup Language - GML - .gml', 'OpenGIS KML Encoding Standard - OGCKML - .kmz', 'Autodesk AutoCAD - DXF_R2007 - .dxf', 'Autodesk AutoCAD - DWG_R2007 - .dwg', 'Bentley Microstation Design (V8) - DGN_V8 - .dgn', 'Adobe 3D PDF - PDF - .pdf', 'Autodesk AutoCad DWF - DWF - .dwf', 'Scalable Vector and Graphics (SVG) - SVG - .svg', 'Scalable Vector and Graphics (SVG) - SVG - .svgz']
    
       raster_format: Raster Format (str). Required parameter.  The format in which the output rasters will be delivered.
          Choice list:['ESRI GRID - GRID', 'File Geodatabase - GDB - .gdb', 'ERDAS IMAGINE - IMG - .img', 'Tagged Image File Format - TIFF - .tif', 'Graphic Interchange Format - GIF - .gif', 'Joint Photographics Experts Group - JPEG - .jpg', 'Joint Photographics Experts Group - JPEG 2000 - .jp2', 'Bitmap - BMP - .bmp', 'Portable Network Graphics - PNG - .png']
    
            gis: Optional, the GIS on which this tool runs. If not specified, the active GIS is used.
    
    
    Returns: 
       output_zip_file - Output Zip File as a DataFile
    
    See http://gis.ices.dk/gis/rest/directories/arcgisoutput/Tools/ExtractZionData_GPServer/Tools_ExtractZionData/ExtractZionData.htm for additional help.

As shown in the example above, tool functions are annotated using type hints to help indicate the input they accept and the output they produce. The function signature includes default values for the input parameters, so the caller doesn't have to specify them unless required. Parameter documentation includes a description of each parameter, it's expected type, and whether it is required or optional. If the parameter accepts from a list of input values, that list is included with the documentation as a 'Choice List'. The documentation includes the type and description of the functions return value.

Next, head over to the topic Using geoprocessing tools to see how these tools can be used in Python scripts.


Feedback on this topic?