CreateGeocodeSDDraft

Summary

Converts a locator to a Service Definition Draft file (.sddraft) that can be used to create a service definition for publishing a geocode service.

Caution:

Service Definition Draft files must be converted to Service Definition files (.sd) before they can be used to publish to ArcGIS Server.

Note:

A draft service definition does not contain data. A draft service alone cannot be used to publish a service.

Discussion

CreateGeocodeSDDraft is the first step to automating the publishing of a locator to a geocode service using ArcPy. The output created from the CreateGeocodeSDDraft is a Service Definition Draft file (.sddraft). A Service Definition Draft is the combination of locator properties, information about the server, and a set of service properties.

All geocode services require a locator. The locator is the main tool for geocoding in ArcGIS and contains all the data necessary to perform address matching. In ArcGIS AllSource, you can use the Create Locator tool or the Create Feature Locator tool to create a locator. For step-by-step instructions, see Create a locator or Create a feature locator. Composite locators, which combine many locators into one, can also be published to ArcGIS Server. For more information, see Combine multiple locators into a composite locator.

Information about the server includes the server connection, server type being published to, metadata for the service (Item info), and data references (whether data is copied to the server).

Service properties include operations such as geocoding and reverse geocoding supported by the service, the maximum number of candidates returned by the service when geocoding a single address, or the maximum number of records to be processed in each batch job when performing batch geocoding.

Note:

The pooling properties for the service, such as the minimum or maximum number of instances per machine, cannot be set using this function. Instead, you need to publish the .sddraft file first and modify the draft by editing the .sddraft file using XML libraries such as xml.dom.minidom.

The function returns a dictionary containing errors and other potential issues that you should address before creating the Service Definition file.

A Service Definition Draft file can be authored without knowing the specific server connection information. In this case, the connection_file_path argument can be omitted; however, the server_type value must be provided. A server connection can be provided later when the Service Definition Draft file is published using the Upload Service Definition tool.

The Service Definition Draft file can then be converted to a fully consolidated Service Definition file (.sd) using the Stage Service tool. Staging compiles all the necessary information to successfully publish the GIS resource. If the data is not registered with the server, it will be added when the Service Definition Draft file is staged. The Service Definition file can be uploaded and published as a GIS service to a specified GIS server using the Upload Service Definition tool. This step takes the Service Definition file and copies it to the server, extracts required information, and publishes the GIS resource. For more information, see An overview of the Publishing toolset.

Syntax

CreateGeocodeSDDraft (loc_path, out_sddraft, service_name, {server_type}, {connection_file_path}, {copy_data_to_server}, {folder_name}, {summary}, {tags}, {max_result_size}, {max_batch_size}, {suggested_batch_size}, {supported_operations}, {overwrite_existing_service})

Parameter	Explanation	Data Type
loc_path	The catalog path to the locator files (.loc) in a file folder.	String
out_sddraft	The path and file name for the output Service Definition Draft file (.sddraft).	String
service_name	The name of the service. This is the name people will see and use to identify the service. The name can only contain alphanumeric characters and underscores. No spaces or special characters are allowed. The name cannot be more than 120 characters.	String
server_type	The server type. If a connection_file_path parameter value is not supplied, a server_type value must be provided. If a connection_file_path parameter value is supplied, the server_type value is taken from the connection file. In this case, you can choose FROM_CONNECTION_FILE or skip the parameter entirely. ARCGIS_SERVER—The ArcGIS Server server type. FROM_CONNECTION_FILE—Get the server_type value as specified by the connection_file_path parameter. (The default value is ARCGIS_SERVER)	String
connection_file_path	The path and file name to an ArcGIS Server connection file (.ags). To publish a geocoding service in ArcGIS AllSource, you will need an .ags file that has been created with publisher or administrator credentials for ArcGIS Server 10.6 or later. You can create a connection file using ArcGIS AllSource and use the path to that file when publishing in ArcGIS AllSource.	String
copy_data_to_server	A Boolean that indicates whether the data referenced in the locator will be copied to the server. The copy_data_to_server parameter is only used if the server_type value is ARCGIS_SERVER and the connection_file_path value is not specified. If the connection_file_path value is specified, the server's registered data stores are used. For example, if the data in the locator is registered with the server, copy_data_to_server will always be False. Conversely, if the data in the locator is not registered with the server, copy_data_to_server will always be True. False—The data will not be copied to the server. This is the default. True—The data will be copied to the server. (The default value is False)	Boolean
folder_name	The folder name where the service definition will be published. If the folder does not exist, it will be created when the service definition is published as a service. The default folder is the server root level. (The default value is None)	String
summary	The Item Description Summary. Use this parameter to override the user interface summary or to provide a summary if one does not exist. (The default value is None)	String
tags	The Item Description Tags. Use this parameter to override the user interface tags or to provide tags if they do not exist. To specify multiple tags, separate each tag with a comma in the string. (The default value is None)	String
max_result_size	The maximum number of candidates returned by the service when geocoding a single address. (The default value is 500)	Integer
max_batch_size	The maximum number of records to be processed in each batch job when performing batch geocoding. (The default value is 1000)	Integer
suggested_batch_size	The recommended number of records to pass in each batch job when performing batch geocoding. (The default value is 1000)	Integer
supported_operations [supported_operations,...]	The built-in operations that will be supported by the service. The parameter should be specified as a list containing one or more of the following string keywords: GEOCODE—The service will allow geocoding operations. REVERSE_GEOCODE—The service will allow reverse geocoding operations. SUGGEST—The service will allow suggest operations. For example, to specify that the service will only support geocoding operations and will not allow reverse geocoding operations, specify the parameter as ["GEOCODE"]. (The default value is [GEOCODE, REVERSE_GEOCODE, SUGGEST])	String
overwrite_existing_service	Specifies whether an existing service on the server will be overwritten by a new service with the same service_name value. If the service_name value is unique, this parameter is not applicable.	Boolean

Return Value

Data Type	Explanation
Dictionary	A dictionary of information messages, warnings, and errors.

Code sample

Publishing a geocode service to a stand-alone server

The following script demonstrates the complete workflow to publish an address locator as a geocode service on a stand-alone server. The first step in the publishing workflow is to create a Service Definition Draft file (.sddraft) from the address locator using the CreateGeocodeSDDraft function. Then create a Service Definition file (.sd) from the Service Definition Draft file using the StageService function. The final step is to publish the Service Definition file as a service to a GIS server using the UploadServiceDefinition function.

If a geocoding service already exists, set the overwrite_existing_service argument to True for the service to publish successfully. If you are using a data store to publish the locator, set the copy_data_to_server argument to False.

import arcpy
import pprint

# Overwrite any existing outputs
arcpy.env.overwriteOutput = True

locator_path = "C:\\Data\\Locators\\Atlanta"
sddraft_file = "C:\\Output\\Atlanta.sddraft"
sd_file = "C:\\Output\\Atlanta.sd"
service_name = "Atlanta"
summary = "Address locator for the city of Atlanta"
tags = "address, locator, geocode"
# Create an AGS connection file to your standalone server
# in ArcGIS Pro
gis_server_connection_file = "C:\\Data\\server_connection"

# Create the sd draft file
analyze_messages = arcpy.CreateGeocodeSDDraft(locator_path, sddraft_file, service_name,
                        connection_file_path=gis_server_connection_file, 
                        copy_data_to_server=True,
                        summary=summary, tags=tags, max_result_size=20,
                        max_batch_size=500, suggested_batch_size=150, 
                        overwrite_existing_service=False)

# Stage and upload the service if the sddraft analysis did not contain errors
if analyze_messages['errors'] == {}:
    try:
        # Execute StageService to convert sddraft file to a service definition 
        # (sd) file 
        arcpy.server.StageService(sddraft_file, sd_file)

        # Execute UploadServiceDefinition to publish the service definition 
        # file as a service
        arcpy.server.UploadServiceDefinition(sd_file, gis_server_connection_file)
        print("The geocode service was successfully published")
    except arcpy.ExecuteError:
        print("An error occurred")
        print(arcpy.GetMessages(2))
else: 
    # If the sddraft analysis contained errors, display them
    print("Error were returned when creating service definition draft")
    pprint.pprint(analyze_messages['errors'], indent=2)

Publishing a geocode service to ArcGIS Enterprise

The following script demonstrates the complete workflow to publish an address locator as a geocode service on ArcGIS Enterprise. The first step in the publishing workflow is to create a Service Definition Draft file (.sddraft) from the address locator using the CreateGeocodeSDDraft function. Then create a Service Definition file (.sd) from the Service Definition Draft file using the StageService function. The final step is to publish the Service Definition file as a service to a GIS server using the UploadServiceDefinition function.

If a geocoding service already exists, set the overwrite_existing_service argument to True for the service to publish successfully. If you are using a data store to publish the locator, set the copy_data_to_server argument to False.

Note:

If you are working with locators on your portal, ensure that you are signed in and have it set as your active portal in ArcGIS AllSource. To access a locator that is on a portal other than your active portal, you can authenticate using SignInToPortal.

import arcpy
import pprint

# Overwrite any existing outputs
arcpy.env.overwriteOutput = True

locator_path = "C:\\Data\\Locators\\Atlanta"
sddraft_file = "C:\\Output\\Atlanta.sddraft"
sd_file = "C:\\Output\\Atlanta.sd"
service_name = "Atlanta"
summary = "Address locator for the city of Atlanta"
tags = "address, locator, geocode"

# The URL of the federated server you are publishing to
in_server = "https://machinename.domainname.com/server"

# Create the sd draft file
analyze_messages = arcpy.CreateGeocodeSDDraft(locator_path, sddraft_file, service_name,
                        copy_data_to_server=True,
                        summary=summary, tags=tags, max_result_size=20,
                        max_batch_size=500, suggested_batch_size=150, 
                        overwrite_existing_service=False)

# Stage and upload the service if the sddraft analysis did not contain errors
if analyze_messages['errors'] == {}:
    try:
        # Execute StageService to convert sddraft file to a service definition 
        # (sd) file 
        arcpy.server.StageService(sddraft_file, sd_file)

        # Execute UploadServiceDefinition to publish the service definition 
        # file as a service
        arcpy.server.UploadServiceDefinition(sd_file, in_server)
        print("The geocode service was successfully published")
    except arcpy.ExecuteError:
        print("An error occurred")
        print(arcpy.GetMessages(2))
else: 
    # If the sddraft analysis contained errors, display them
    print("Error were returned when creating service definition draft")
    pprint.pprint(analyze_messages['errors'], indent=2)