Accessing geoprocessing tools
In this page we will observe how you can search for geoprocessing tools and access them in your code.
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.
import arcgis
from arcgis.gis import GIS
from IPython.display import displaygis = GIS('home')toolboxes = gis.content.search('travel', 'Geoprocessing Toolbox',
outside_org=True, max_items=3)for toolbox in toolboxes:
display(toolbox)
Geoprocessing Toolbox by omolarakareem
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:
from arcgis.geoprocessing import import_toolboxocean_currents_toolbox = toolboxes[1]
ocean_currents_toolbox
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.
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('_')]['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:
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:
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.