对文件进行地理编码 (地理编码)

摘要

将大型本地地址或地点表转换为要素类中的点或 CSV 或 XLS 表。 此工具使用在 ArcGIS Enterprise 门户上托管的定位器。

注:

此工具适用于在 ArcGIS AllSource 2.4 或更高版本中与 ArcGIS Enterprise 10.7 或更高版本的门户结合使用。

使用情况

  • 此工具支持将以下表格式作为输入:

    • 逗号分隔值文件 (.csv)
    • 文件地理数据库表
    • Microsoft Excel 工作表(.xls.xlsx 文件)

    对于输入 CSV 表,除了从定位器追加的字段之外,输入文件的第一行用作输出表的字段名称。 字段名称不能包含空格或特殊字符,例如 $ 或 *。

    了解有关在 ArcGIS AllSource 中使用 Microsoft Excel 文件的更多信息

    注:

    要以最快速方式使用文件地理数据库形式的输入表返回地理编码结果,可限制文件地理数据库的内容,或提供包含单个表的文件地理数据库。

  • 您可以对存储在单个字段中或拆分成多个字段的地址进行地理编码,也可以对存储在单个字段和国家/地区字段的地址编码。 单个输入字段可存储完整地址,例如,303 Peachtree St NE, Atlanta, GA 30308。 如果将常规美国地址的输入地址划分为 AddressCityStateZIP 等多个字段,则系统支持多个字段。 单个输入字段可存储完整地址,例如,303 Peachtree St NE, Atlanta, GA 30308,以及存储与地址关联的国家/地区的字段(例如,USA)

  • 某些定位器支持多个输入地址字段,例如 AddressAddress2Address3。 在此情况下,可以将地址组件分为多个字段,然后在进行地理编码时将地址字段连接在一起。 例如,跨三个字段的 100、Main St 和 Apt 140,或者跨两个字段的 100 Main St 和 Apt 140,在进行地理编码时,都将成为 100 Main St Apt 140。

  • ArcGIS Enterprise 10.7 或更高版本的门户需要使用此工具。

  • 如果有门户定位器未在门户上作为公共设施服务提供,则需要请求门户管理员将此定位器添加为门户公共设施服务,并配置该定位器以进行批量地理编码

  • 使用 ArcGIS Enterprise 门户上已配置为使用多个线程的定位器可提高地理编码性能。

  • 地理编码结果保存在与定位器相同的空间参考中。 可通过在工具的环境设置中设置其他输出坐标系来更改输出空间参考。

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

  • 当地理编码结果作为要素类返回时,可使用重新匹配地址工具或重新匹配地址选项(将打开重新匹配地址窗格)重新匹配地址。

    注:

    该表必须在 ArcGIS Enterprise 10.8 门户中使用具有多个用于批量地理编码的线程的定位器进行地理编码。

    了解有关重新匹配地理编码结果的详细信息

  • 当使用使用 z 感知数据构建的输入定位器时,该工具将返回非 z 感知的输出。 该工具仅支持 2D 输出。

  • 当将定位器视图作为定位器参数值使用时,工具不会应用ArcGIS Pro 3.2 中创建的定位器视图的配置。

参数

标注说明数据类型
输入表

包含要以 CSV、XLS 或 XLSX 格式或文件地理数据库表格式进行地理编码的地址或地点的输入表。

Record Set
定位器

将用于对表进行地理编码的门户定位器。

可以从活动门户上的已填充定位器列表中选择一个定位器,或者浏览活动门户以搜索其他可用定位器。 默认情况下,已在活动门户中设置为实用程序服务的定位器将可用。

注:

ArcGIS World Geocoding Service 已针对此工具禁用。 如果想要使用 ArcGIS World Geocoding Service,请使用地理编码地址工具。

Address Locator
地址字段映射

定位器使用的地址字段会映射到输入地址表中的字段。 如果输入表中的完整地址存储在一个字段中,例如 303 Peachtree St NE, Atlanta, GA 30308,则需指定单个字段。 如果将常规美国地址的输入划分为 AddressCityStateZIP 等多个字段,则需指定多个字段。 如果将完整地址和国家/地区拆分为多个字段,例如,303 Peachtree St NE, Atlanta, GA 30308 和 USA 被拆分为 AddressCountry,则需指定单个字段和国家/地区字段

某些定位器支持多个输入地址字段,例如 AddressAddress2Address3。 在此情况下,可以将地址组件分为多个字段,然后在进行地理编码时将地址字段连接在一起。 例如,跨三个字段的 100、Main st 和 Apt 140,或者跨两个字段的 100 Main st 和 Apt 140,在进行地理编码时,都将成为 100 Main st Apt 140。

如果不想将定位器所使用的可选输入地址字段映射到输入地址表中的字段,请使用 <None> 来代替字段名,以此指定不存在任何映射。

Field Info
输出类型

指定将写入地理编码结果的文件类型。

  • CSV将返回 .csv 文件。
  • 要素类将返回文件地理数据库中的要素类。
  • XLS将返回 .xls 文件。
String
输出位置

将写入输出地理编码结果的文件夹。

如果输出为 .csv.xls 文件,则输出文件将置于指定的文件夹中。

如果输出为要素类,则将创建输出文件地理数据库并将其置于指定的文件夹中,新文件地理数据库将包含已进行地理编码的要素类。 输出文件地理数据库和文件地理数据库中的要素类将具有相同的名称。

Workspace
输出名称

输出已地理编码结果的名称。

String
国家/地区
(可选)

搜索地理编码地址的一个或多个国家/地区。

此参数可用于支持国家/地区参数的定位器,并将地理编码限制在指定国家/地区。 指定一个国家/地区将在大多数情况下提高地理编码的准确性。 当为地址字段映射参数指定单个字段和国家/地区字段,并在映射表示国家的字段时将输入表参数值用于地址字段映射参数值的 Country 字段,输入表参数中的国家/地区值将覆盖国家/地区参数。

这仅限于指定的一个或多个国家/地区。 如果未指定国家/地区,则使用定位器的所有受支持国家/地区执行地理编码。

国家/地区参数不适用于所有定位器。

String
首选位置类型
(可选)

用于指定将返回的 PointAddress 匹配的首选输出几何。 此参数的选项包括路由位置(可用于路由的街道位置侧)和地址位置(表示地址屋顶或宗地质心的位置)。 如果数据中不存在首选位置,则将返回默认位置。 对于 Addr_type=PointAddress 的地理编码结果,x,y 属性值用于描述沿着街道的地址的坐标,而 DisplayX 和 DisplayY 值用于描述屋顶或建筑物质心坐标。

此参数并非支持所有定位器。

  • 地址位置将返回地理编码结果的几何,该几何可以表示地址位置,例如屋顶位置、宗地质心或前门。
  • 路径位置将返回表示靠近街道一侧(可用于车辆配送)的位置的地理编码结果的几何。 这是默认设置。
String
类别
(可选)

限制定位器搜索的地点类型,从而消除误报匹配并可能加快搜索过程的速度。 如果未使用任何类别,将使用所有支持的类别执行地理编码。 并非所有位置和国家/地区都支持所有类别值。 通常,该参数可以用于以下几个方面:

  • 将匹配限制到特定地点类型或地址级别
  • 避免回退匹配到不需要的地址级别
  • 消除坐标搜索的歧义

此参数并非支持所有定位器。

String
输出字段
(可选)

指定将在地理编码结果中返回的定位器输出字段。

  • 全部在地理编码结果中包含所有可用的定位器输出字段。 这是默认设置。
  • 仅位置如果地理编码结果是要素类,将存储 Shape 字段。 如果结果为 .csv.xls 文件,将存储 Shape XShape Y 字段。 输入表参数中的原始字段名称与其原始字段名称一起保留。
  • 最小化添加以下字段,用于描述位置以及其与地理编码结果中定位器中的信息的匹配程度:ShapeStatusScoreMatch_typeMatch_addrAddr_type。 将保留输入表参数值中的原始字段名称。
  • 最小和用户字段添加以下字段,用于描述位置以及其与定位器中的信息的匹配程度,以及地理编码结果中任何用户定义的自定义输出字段:ShapeStatusScoreMatch_typeMatch_addrAddr_type。 将保留输入表参数值中的原始字段名称。
注:

此参数可与使用创建定位器创建要素定位器工具创建的输入定位器一起使用,这些定位器已发布到 Enterprise 10.9 或更高版本。 包含至少一个使用创建地址定位器工具创建的定位器的复合定位器不支持此参数。

String

派生输出

标注说明数据类型
输出要素类

输出要素类。

Feature Class
输出表

采用 CSV 或 XLS 格式的输出表,具体取决于输出类型值。

Table

arcpy.geocoding.GeocodeFile(in_table, locator, address_fields, output_type, output_location, output_name, {country}, {location_type}, {category}, {output_fields})
名称说明数据类型
in_table

包含要以 CSV、XLS 或 XLSX 格式或文件地理数据库表格式进行地理编码的地址或地点的输入表。

Record Set
locator

将用于对表进行地理编码的门户定位器。

可以从活动门户上的已填充定位器列表中选择一个定位器,或者浏览活动门户以搜索其他可用定位器。 默认情况下,已在活动门户中设置为实用程序服务的定位器将可用。

注:

ArcGIS World Geocoding Service 已针对此工具禁用。 如果想要使用 ArcGIS World Geocoding Service,请使用地理编码地址工具。

Address Locator
address_fields

此参数中的每个字段映射均采用 input_locator_field, table_field_name 格式,其中 input_locator_field 是定位器指定的输入地址字段名称,table_field_name 是要进行地理编码的地址表中相应字段的名称。

您可以可以指定单个输入字段以存储完整地址,例如,303 Peachtree St NE, Atlanta, GA 30308。 如果常规美国地址的输入地址划分为 AddressCityStateZIP 等多个字段,也可以指定多个字段。 也可以指定单个输入字段可存储完整地址,例如,303 Peachtree St NE, Atlanta, GA 30308,以及存储与地址关联的国家/地区的字段(例如,USA)。

某些定位器支持多个输入地址字段,例如 AddressAddress2Address3。 在此情况下,可以将地址组件分为多个字段,然后在进行地理编码时将地址字段连接在一起。 例如,跨三个字段的 100、Main st 和 Apt 140,或者跨两个字段的 100 Main st 和 Apt 140,在进行地理编码时,都将成为 100 Main st Apt 140。

如果不想将定位器所使用的可选输入地址字段映射到输入地址表中的字段,请使用 <None> 来代替字段名,以此指定不存在任何映射。

Field Info
output_type

指定将写入地理编码结果的文件类型。

  • CSV将返回 .csv 文件。
  • FEATURE_CLASS将返回文件地理数据库中的要素类。
  • XLS将返回 .xls 文件。
String
output_location

将写入输出地理编码结果的文件夹。

如果输出为 .csv.xls 文件,则输出文件将置于指定的文件夹中。

如果输出为要素类,则将创建输出文件地理数据库并将其置于指定的文件夹中,新文件地理数据库将包含已进行地理编码的要素类。 输出文件地理数据库和文件地理数据库中的要素类将具有相同的名称。

Workspace
output_name

输出已地理编码结果的名称。

String
country
[country,...]
(可选)

搜索地理编码地址的一个或多个国家/地区。

此参数可用于支持国家/地区参数的定位器,并将地理编码限制在指定国家/地区。 指定一个国家/地区将在大多数情况下提高地理编码的准确性。 如果 in_table 参数中表示国家/地区的字段映射到 address_fields 中的 Country 字段,则 in_table 参数中的国家/地区值将覆盖 country 参数。

这仅限于指定的一个或多个国家/地区。 如果未指定国家/地区,则对定位器的所有受支持国家/地区进行地理编码。

在以逗号分隔的列表中,将值指定为 2 个字符或 3 个字符的国家/地区代码。 有关要使用的输入值,请参阅受支持的国家/地区代码列

country 参数并非支持所有定位器。

String
location_type
(可选)

用于指定将返回的 POINT_ADDRESS 匹配的首选输出几何。 此参数的选项包括 ROUTING_LOCATION(可用于路由的街道位置侧)和 ADDRESS_LOCATION(表示屋顶、地址宗地质心或前门的位置) 如果数据中不存在首选位置,则会返回 ROUTING_LOCATION 的默认位置。 对于 Addr_type=PointAddress 的地理编码结果,x,y 属性值用于描述沿着街道的地址的坐标,而 DisplayX 和 DisplayY 值用于描述屋顶或建筑物质心坐标。 有关 geocodeAddresseslocationType 参数的详细信息,请参阅 ArcGIS REST API Web 帮助。

此参数并非支持所有定位器。

  • ADDRESS_LOCATION将返回地理编码结果的几何,该几何可以表示地址位置,例如屋顶位置、宗地质心或前门。
  • ROUTING_LOCATION将返回表示靠近街道一侧(可用于车辆配送)的位置的地理编码结果的几何。 这是默认设置。
String
category
[category,...]
(可选)

限制定位器搜索的地点类型,从而消除误报匹配并可能加快搜索过程的速度。 如果未使用任何类别,将使用所有支持的类别执行地理编码。 并非所有位置和国家/地区都支持所有类别值。 通常,该参数可以用于以下几个方面:

  • 将匹配限制到特定地点类型或地址级别
  • 避免回退匹配到不需要的地址级别
  • 消除坐标搜索的歧义

此参数并非支持所有定位器。

有关类别过滤的详细信息,请参阅 ArcGIS REST API Web 帮助。

String
output_fields
(可选)

指定将在地理编码结果中返回的定位器输出字段。

注:

此参数可与使用创建定位器创建要素定位器工具创建的输入定位器一起使用,这些定位器已发布到 Enterprise 10.9 或更高版本。 包含至少一个使用创建地址定位器工具创建的定位器的复合定位器不支持此参数。

  • ALL在地理编码结果中包含所有可用的定位器输出字段。 这是默认设置。
  • LOCATION_ONLY如果地理编码结果是要素类,将存储 Shape 字段。 如果结果为 .csv.xls 文件,将存储 Shape XShape Y 字段。 in_table 参数中的原始字段名称与其原始字段名称一起保留。
  • MINIMAL添加以下字段,用于描述位置以及其与地理编码结果中定位器中的信息的匹配程度:ShapeStatusScoreMatch_typeMatch_addrAddr_type。 将保留 in_table 参数值中的原始字段名称。
  • MINIMAL_AND_USER添加以下字段,用于描述位置以及其与地理编码结果中定位器中的信息的匹配程度,以及任何用户定义的自定义输出字段:ShapeStatusScoreMatch_typeMatch_addrAddr_type。 将保留 in_table 参数值中的原始字段名称。
String

派生输出

名称说明数据类型
out_feature_class

输出要素类。

Feature Class
out_table

采用 CSV 或 XLS 格式的输出表,具体取决于输出类型值。

Table

代码示例

GeocodeFile 示例(独立脚本)

以下 Python 脚本演示了如何在独立脚本中使用 GeocodeFile 函数。

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

import arcpy

# Input is a local table
input_table = r"C:\data\customers.csv"

# This tool works with locators on a portal
in_locator = "https://<machine_name>/server/rest/services/<service_name>/GeocodeServer/<service_name>"

# The best way to generate a field mapping is to run the tool in ArcGIS 
# Pro, right-click the green success ribbon, and click "Copy Python command"

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

# Output folder for the output CSV, Excel, or GDB table. If you select 
# FEATURE_CLASS output_type, a new GDB will be created in the 
# output_folder with the geocoding results
output_folder = r"C:\data\outputs"
output_name = "Geocoding_output"

# Optional geocoding parameters. Only some are supported depending on the 
# in_locator that you use.
country = None
location_type = "ROUTING_LOCATION"
category = "'Street Address'"

arcpy.geocoding.GeocodeFile(input_table, in_locator, field_mapping, output_type, 
                            output_folder, output_name, country, location_type, 
                            category)