批处理地理编码 (地理编码)

摘要

使用 batchGeocode REST API 异步对地址或地点的大型表或 .csv 文件进行地理编码。 地理编码结果将以要素类形式返回，无需 ArcGIS Pro 将请求分割成较小的批处理任务。

使用此工具，地理编码任务可以在服务器上独立运行，与其他进程隔离，并可弹性伸缩。 例如，将作业提交到 ArcGIS World Geocoding Service 时，系统会分配专用硬件资源来处理文件，从而缩短处理时间。 您可以选择在 ArcGIS Enterprise on Kubernetes 11.5 及更高版本中托管且配置了 Kubernetes 集群的 ArcGIS World Geocoding Service 或服务。

注：

使用 ArcGIS World Geocoding Service 执行地理编码操作需要 ArcGIS 组织账户并需要消耗配额。 组织账户必须具有足够的配额，才能完成整个地理编码请求。

当活动门户为 ArcGIS Online 时，地理处理窗格中工具界面的顶部会显示配额估算值。

使用情况

• 当使用 ArcGIS World Geocoding Service 作为输入批处理服务参数值时，输入表或文件必须至少包含 100,000 条记录。

• 当使用 ArcGIS World Geocoding Service 作为输入批处理服务参数值时，输入表参数值将临时存储在您的 ArcGIS Online 门户中，直到作业完成。 作业完成后，临时文件将从门户中删除。

• 此工具支持的最大记录数为 5000 万条。 如果表包含的记录数超过 5000 万条，请将该表拆分为多个记录数不超过 5000 万条的表。 如果输入为 .csv 文件，则其必须使用 UTF-8 编码，并且包含字节顺序标记 (BOM)。

  注：

  您可以使用 Microsoft Excel 或 Notepad++ 等第三方应用程序向 .csv 文件添加 UTF-8 BOM。

• 除了从定位器追加的字段之外，输入 .csv 文件的第一行用作输出要素类的字段名称。 字段名称不能包含空格或下划线以外的特殊字符。

  注：

  在 Python 中使用此工具时，如果使用 address_fields 参数进行字段映射，则 table_field_name 参数值的字段名称必须与 input_address_field 参数值的字段名称大小写一致。

• 当定位器发布到 ArcGIS Enterprise on Kubernetes 并启用批处理地理编码功能时，系统会自动创建两个服务：GeocodeServer 和 GPServer。 在 Python 中使用此工具时，in_batch_service 参数值必须是 GPServer，例如 https://machinename.domain.com/server/rest/services/service_name/GPServer。

• 地理编码结果保存在与服务相同的空间参考中。 您可以通过设置输出坐标系环境来更改输出结果的空间参考。

• 地理编码结果将包含所有相关的地理编码信息，包括每个记录的得分、状态和匹配的地址，以及原始输入表或文件中的值。 此工具的地理编码结果包含原始输入表的静态快照，因此在原始表中添加或更新值都不会更新输出要素类中的结果。 重新运行此工具以创建包含这些更改的新输出要素类。

• 并非所有用于输入批处理服务参数值的批处理服务都支持以下参数：国家或地区、首选位置类型和类别。

• 此工具不支持选择集操作。 要仅对表的一部分进行地理编码，请先导出该部分数据，然后对导出的新表运行此工具。

参数

对话框

标注	说明	数据类型
输入表	将进行地理编码的地址或地点的表或 .csv 文件。	Table View
输入批处理服务	具有批处理地理编码支持的门户上的地理编码服务，用于对地址和地点的表进行地理编码。 注： 如果该服务是自定义定位器或 ArcGIS StreetMap Premium 定位器，则必须将其发布到 ArcGIS Enterprise on Kubernetes 11.5 或更高版本，并启用批处理地理编码功能。	String
地址字段映射	定位器所使用的地址字段与输入地址表或文件中的字段之间的映射。 如果输入表或文件中的完整地址存储在一个字段中，例如 303 Peachtree St NE, Atlanta, GA 30308，则需指定单个字段。 如果将常规美国地址的输入划分为 Address、City、State 和 ZIP 等多个字段，则需指定多个字段。 如果将完整地址和国家/地区拆分为多个字段，例如 Address (303 Peachtree St NE, Atlanta, GA 30308) 和 Country (USA)，则指定单个字段和国家/地区字段。 某些定位器支持多个输入地址字段，例如 Address、Address2 和 Address3。 在此情况下，可以将地址组件分为多个字段，然后在进行地理编码时将地址字段连接在一起。 例如，跨三个字段的 100、Main st 和 Apt 140，或者跨两个字段的 100 Main st 和 Apt 140，在进行地理编码时，都将成为 100 Main st Apt 140。 如果不想将地址定位器所使用的可选输入地址字段映射到输入地址表或文件中的字段，请使用 <None> 来代替字段名，以此指定不存在任何映射。	Field Info
输出要素类	经过地理编码的输出要素类。 注： 由于 shapefile 限制，系统不支持将输出保存为 shapefile 格式。	Feature Class
国家/地区	用于将搜索范围限定为特定国家或地区的地理编码地址。 指定一个国家/地区将在大多数情况下提高地理编码的准确性。 如果未指定国家/地区，则使用定位器的所有受支持国家/地区执行地理编码。 当您在地址字段映射参数中同时指定单个字段和国家/地区字段时，此参数将被忽略。	String
首选位置类型 (可选)	用于指定将返回的 PointAddress 匹配的首选输出几何。 如果数据中不存在首选位置，则将返回默认位置。 有关 geocodeAddresses 的 locationType 参数的详细信息，请参阅 ArcGIS REST API Web 帮助。 地址位置—将返回地理编码结果的几何，该几何可以表示地址位置，例如屋顶位置、宗地质心或前门。 这是默认设置。 路径位置—将返回表示靠近街道一侧（可用于车辆配送）的位置的地理编码结果的几何。	String
类别 (可选)	限制定位器搜索的地点类型，避免误匹配、不必要的地址级别匹配或坐标搜索的歧义。 此参数有助于加快搜索速度。 如果未使用任何类别，将使用所有支持的类别执行地理编码。 并非所有位置和国家/地区都支持所有类别值。 有关类别过滤的详细信息，请参阅 ArcGIS REST API Web 帮助。	String
输出字段 (可选)	指定将在地理编码结果中返回的定位器输出字段。 如果选择仅位置、最小化或最小化和用户字段选项，则会保留输入表参数值中的原始字段名称。 全部—在地理编码结果中包含所有可用的定位器输出字段。 这是默认设置。 仅位置—在地理编码结果中存储 Shape 字段。 最小化—添加以下字段，用于描述位置以及其与地理编码结果中定位器中的信息的匹配程度：Shape、Status、Score、Match_type、Match_addr 和 Addr_type。 最小化和用户字段—用户自定义的字段以及 MINIMAL 字段也将被添加到地理编码结果中并返回。	String

Python

arcpy.geocoding.BatchGeocode(in_table, in_batch_service, address_fields, out_feature_class, country, {location_type}, {category}, {output_fields})

名称	说明	数据类型
in_table	将进行地理编码的地址或地点的表或 .csv 文件。	Table View
in_batch_service	具有批处理地理编码支持的门户上的地理编码服务，用于对地址和地点的表进行地理编码。 注： 如果该服务是自定义定位器或 ArcGIS StreetMap Premium 定位器，则必须将其发布到 ArcGIS Enterprise on Kubernetes 11.5 或更高版本，并启用批处理地理编码功能。	String
address_fields	此参数中的每个字段映射均采用 input_address_field, table_field_name 格式，其中 input_address_field 是定位器指定的输入地址字段名称，table_field_name 是要进行地理编码的地址表或文件中相应字段的名称。 如果完整地址信息存储在 in_table 值的一个字段中（例如 303 Peachtree St NE, Atlanta, GA 30308），则指定为单个输入字段。 如果常规美国地址的输入地址划分为 Address、City、State 和 ZIP 等多个字段，也可以指定多个字段。 也可以指定单个输入字段可存储完整地址，例如，303 Peachtree St NE, Atlanta, GA 30308，以及存储与地址关联的国家/地区的字段（例如，USA）。 某些定位器支持多个输入地址字段，例如 Address、Address2 和 Address3。 在此情况下，可以将地址组件分为多个字段，然后在进行地理编码时将地址字段连接在一起。 例如，跨三个字段的 100、Main st 和 Apt 140，或者跨两个字段的 100 Main st 和 Apt 140，在进行地理编码时，都将成为 100 Main st Apt 140。 如果不想将地址定位器所使用的可选输入地址字段映射到输入地址表或文件中的字段，请使用 <None> 来代替字段名，以此指定不存在任何映射。	Field Info
out_feature_class	经过地理编码的输出要素类。 注： 由于 shapefile 限制，系统不支持将输出保存为 shapefile 格式。	Feature Class
country [country,...]	用于将搜索范围限定为特定国家或地区的地理编码地址。 指定一个国家/地区将在大多数情况下提高地理编码的准确性。 如果未指定国家/地区，则使用定位器的所有受支持国家/地区执行地理编码。 当 in_table 参数值中的字段已映射到 address_fields 参数中的 Country 字段时，此参数值将被忽略。 在以逗号分隔的列表中，将值指定为 2 个字符或 3 个字符的国家/地区代码。 有关要使用的输入值，请参阅受支持的国家/地区代码列。	String
location_type (可选)	用于指定将返回的 PointAddress 匹配的首选输出几何。 如果数据中不存在首选位置，则会返回 ADDRESS_LOCATION 的默认位置。 有关 geocodeAddresses 的 locationType 参数的详细信息，请参阅 ArcGIS REST API Web 帮助。 ADDRESS_LOCATION—将返回地理编码结果的几何，该几何可以表示地址位置，例如屋顶位置、宗地质心或前门。 这是默认设置。 ROUTING_LOCATION—将返回表示靠近街道一侧（可用于车辆配送）的位置的地理编码结果的几何。	String
category [category,...] (可选)	限制定位器搜索的地点类型，避免误匹配、不必要的地址级别匹配或坐标搜索的歧义。 此参数有助于加快搜索速度。 如果未使用任何类别，将使用所有支持的类别执行地理编码。 并非所有位置和国家/地区都支持所有类别值。 有关类别过滤的详细信息，请参阅 ArcGIS REST API Web 帮助。	String
output_fields (可选)	指定将在地理编码结果中返回的定位器输出字段。 如果指定了 LOCATION_ONLY、MINIMAL 或 MINIMAL_AND_USER 选项，则将保留来自 in_table 参数值的原始字段名称。 ALL—在地理编码结果中包含所有可用的定位器输出字段。 这是默认设置。 LOCATION_ONLY—在地理编码结果中存储 Shape 字段。 MINIMAL—添加以下字段，用于描述位置以及其与地理编码结果中定位器中的信息的匹配程度：Shape、Status、Score、Match_type、Match_addr 和 Addr_type。 MINIMAL_AND_USER—用户自定义的字段以及 MINIMAL 字段也将被添加到地理编码结果中并返回。	String

代码示例

BatchGeocode 示例 1（独立脚本）

以下脚本演示了如何使用 BatchGeocode 函数通过 ArcGIS World Geocoding Service 对 .csv 文件进行地理编码，并在地理编码结果中返回 MINIMAL output_fields。

注：

如果您正在使用您的门户上的定位器，请确保您已登录系统并在 ArcGIS Pro 中将其设置为您的活动门户。 要访问除活动门户之外的门户上的定位器，请使用 SignInToPortal 函数进行身份验证。

注：

使用 ArcGIS World Geocoding Service 时，此操作可能会消耗配额。

import arcpy

# Set local variables

# Input is a local file
in_table = r"C:\data\customers.csv"

# Sign in to Portal
#arcpy.SignInToPortal("https://www.arcgis.com.", "MyUsername", "MyPassword")

in_batch_service = "https://geocode.arcgis.com/arcgis/rest/services/World/GPServer/BatchGeocode/"

# One way to generate the value for the field mapping parameter is to first run the tool in ArcGIS 
# Pro and right-click the green success ribbon and click "Copy Python command"
# The table_field_name fields must be in the same case as the input_address_field fields.

address_fields = "'Address or Place' Address VISIBLE NONE;Address2 <None> VISIBLE NONE;Address3 <None> VISIBLE NONE;
Neighborhood <None> VISIBLE NONE;City City VISIBLE NONE;County <None> VISIBLE NONE;State State VISIBLE NONE;
ZIP ZIPCODE VISIBLE NONE;ZIP4 <None> VISIBLE NONE;Country <None> VISIBLE NONE"

geocode_result = r"C:\Mydata\results.gdb\geocode_results"

# Optional geocoding parameters. Only some are supported depending on the in_batch_service that you use.
country = USA
location_type = "ADDRESS_LOCATION"
category = "'Point Address'"
output_fields = "MINIMAL"

arcpy.geocoding.BatchGeocode(in_table, in_batch_service, address_fields, geocode_result, 
                             country, location_type, category, output_fields)

BatchGeocode 示例 2（独立脚本）

以下脚本演示了如何使用 BatchGeocode 函数通过门户批处理服务对表进行地理编码，并在地理编码结果中使用默认 output_fields。

注：

如果您正在使用您的门户上的定位器，请确保您已登录系统并在 ArcGIS Pro 中将其设置为您的活动门户。 要访问除活动门户之外的门户上的定位器，请使用 SignInToPortal 函数进行身份验证。

import arcpy

# Set local variables

# Input is a local file
in_table = r"C:\data\mytables.gdb\restaurants"

in_batch_service = "https://machinename.domain.com/server/rest/services/service_name/GPServer/"

# One way to generate the value for the field mapping parameter is to first run the tool in ArcGIS 
# Pro and right-click the green success ribbon and click "Copy Python command"
# The table_field_name fields must be in the same case as the input_address_field fields.

address_fields = "'Address or Place' Address VISIBLE NONE;Address2 <None> VISIBLE NONE;Address3 <None> VISIBLE NONE;
Neighborhood <None> VISIBLE NONE;City City VISIBLE NONE;County <None> VISIBLE NONE;State State VISIBLE NONE;
ZIP ZIPCODE VISIBLE NONE;ZIP4 <None> VISIBLE NONE;Country <None> VISIBLE NONE"

geocode_result = r"C:\My_Output.gdb\geocode_result"

# Optional geocoding parameters. Only some are supported depending on the in_batch_service that you use.
country = USA
location_type = "ROUTING_LOCATION"
category = "'Point Address'"
output_fields = "ALL"

arcpy.geocoding.BatchGeocode(in_table, in_batch_service, address_fields, geocode_result,
                             country, location_type, category, output_fields)

环境

输出坐标系

许可信息

• Basic: 需要 ArcGIS Enterprise 中的帐户有执行分析的权限
• Standard: 需要 ArcGIS Enterprise 中的帐户有执行分析的权限
• Advanced: 需要 ArcGIS Enterprise 中的帐户有执行分析的权限