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
- Pythonic representation of tools and toolboxes
- Importing toolboxes
- Tool signature, parameters and documentation
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 display
gis = GIS('https://www.arcgis.com', 'arcgis_python', 'P@ssword123')
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_toolbox
ocean_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('_')]
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)
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?