摘要
Locator 类可用于修改定位器并将其用于地理编码。 地理编码是指将位置描述（例如坐标对、地址或地名）转换为地球表面上某位置的过程。
地理编码模块支持使用创建定位器工具创建的定位器。 使用旧版工具创建的定位器的功能可能有限，且不支持多个属性和参数。
说明
定位器是一个可移植文件，用于执行地理编码，即在地图上查找地址和位置的过程。 定位器中包含用于地理编码的参考数据快照，同时还包含索引和局部编址信息，这有助于在地理编码过程中返回最佳匹配项。
定位器可以在您的门户中作为服务访问，例如 ArcGIS World Geocoding Service，将作为通过 ArcGIS Server 连接访问的服务或作为磁盘上的文件。
语法
Locator (path)
| 参数 | 说明 | 数据类型 |
path | The path to the locator. | String |
注：
如果您正在使用您的门户上的定位器，请确保您已登录系统并在 ArcGIS AllSource 中将其设置为您的活动门户。 要访问除活动门户之外的门户上的定位器，您可以使用 SignInToPortal 函数进行身份验证。从存储在磁盘上的定位器创建 Locator 对象。
import arcpy
# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)从 ArcGIS World Geocoding Service 创建 Locator 对象。
import arcpy
# Log in to Portal
#arcpy.SignInToPortal("https://www.arcgis.com", "MyUsername", "MyPassword")
# Create a new Locator object from ArcGIS World Geocoding Service
locator_path = "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/ArcGIS World Geocoding Service"
locator = arcpy.geocoding.Locator(locator_path)从 AGS 连接创建 Locator 对象。
import arcpy
# Create a new Locator object from a locator published to ArcGIS Server
locator_path = r"C:\AGS Files\MyAGSConnectionFile.ags\Atlanta"
locator = arcpy.geocoding.Locator(locator_path)在您的 ArcGIS Enterprise 门户中从定位器项目创建 Locator 对象。
import arcpy
# Sign in to your portal
#arcpy.SignInToPortal("https://www.myenterpriseportal.esri.com/portal", "MyUsername", "MyPassword")
# Create a new Locator object from the locator on your portal
locator_path = "https://myenterpriseportal.esri.com/server/rest/services/Geocode/Atlanta/GeocodeServer/Atlanta"
locator = arcpy.geocoding.Locator(locator_path)属性
| 属性 | 说明 | 数据类型 |
| capabilities (只读) | 指定可作为服务共享到 ArcGIS Enterprise 或作为地理编码发布到 ArcGIS Server 的定位器可用的功能。 可用功能包括：
该属性仅可用于地理编码服务。 不受本地定位器支持，如果您尝试访问本地定位器的该属性，则会返回错误。 | String |
| categories (可读写) | 通过将可以从定位器返回的类别限制为已定义的集合来控制精度。 如果您有一个支持多种地址类型的多角色定位器，则可以修改此属性以排除与某些类型的匹配。 例如，定位器支持“点地址”级别、“街道地址”级别、“街道名称”级别和“邮政编码”级别下的匹配项，您想要排除“邮政编码”级别下的匹配项。 此设置可用于控制结果的精确度。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | String |
| compatibilityVersion (只读) | 与定位器兼容的较早版本的 ArcGIS AllSource。 该定位器也仅会在 ArcGIS Server 和 ArcGIS Enterprise 的相应版本中受支持。 例如，值 3.4 仅在 ArcGIS AllSource 3.4 及更高版本、ArcGIS Server 以及 ArcGIS Enterprise 11.4 或更高版本中受支持。 | String |
| comprehensiveZoneMatch (可读写) | 指定与城市名称不完全匹配的输入地址是否会通过 geocode 和 geocodeWithSuggest 方法返回候选项。 默认值为 True。 当此属性设置为 True 时，即使城市名称不正确，地址也将视为匹配。 当此属性设置为 False 时，不会返回匹配项或匹配项的得分显著降低。 有关此属性使用方法的详细信息，请参阅综合区域匹配。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Boolean |
| defaultLocationType (可读写) | 指定由 geocode、geocodeWithSuggest 和 reverseGeocode 方法返回的 POINT_ADDRESS 匹配项的首选输出几何。 此参数的选项是 Routing_Location（可用于路径选择的街道位置所在的一侧）和 Address_Location（表示屋顶、宗地质心或地址的前门）。 如果数据中不存在首选位置，则会返回 Address_Location 的默认位置。 对于 Addr_type = PointAddress 的地理编码结果，x,y 属性值用于描述沿着街道的地址的坐标，而 DisplayX 和 DisplayY 值用于描述屋顶或建筑物质心坐标。 有关如何使用此属性的详细信息，请参阅首选位置类型。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | String |
| defaultSuggestCandidates (可读写) | suggest 方法默认返回的建议候选项数。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Integer |
| endOffset (可读写) | 出于显示目的，用于将结果从街道要素的末端（朝向中心）向远偏移的距离（以米为单位）。 有关如何使用此属性的详细信息，请参阅末端偏移。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Double |
| intersectionConnectors (可读写) | 交叉点连接符列表，可以是符号或单词，将用于覆盖默认交叉点连接符。 使用由引号括起来的逗号分隔列表列出交叉点连接符，例如 "&","|","//","@"。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | String |
| matchOutOfRange (可读写) | 用于指定当搜索到的街道编号略微超出构建定位器的数据中路段的范围时，是否返回匹配项。 要匹配路段，即使数据中的线段上不存在街道编号，但是街道编号在合理的阈值内并且可能存在，则需将属性设置为 True。 当此属性设置为 True 时，该点位于地址略微超出门牌号范围的路段末端。 这可确保您不会错过潜在的匹配，因为数据不是 100% 最新的。 此属性仅适用于支持并返回“街道地址”匹配项的定位器。 有关此属性的详细信息，请参阅匹配超出范围。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Boolean |
| maxCandidates (可读写) | geocode 方法返回的最大候选项数。 如果地理编码花费了很长时间并且也获得了高质量匹配，请确保未将此属性设置过高。 如果您获得了不错的结果，则可以通过生成更少的结果并专注于前几条结果来提高性能。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Integer |
| maxSuggestCandidates (可读写) | suggest 方法返回的最大建议结果数。 如果 suggest 方法性能较差，则可能是因为定位器生成了大量建议结果。 将此值设置为较小的数字可以提高性能。 有关此属性的详细信息，请参阅最大建议候选项数。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Integer |
| minCandidateScore (可读写) | 使结果必须被视为 geocode 操作的匹配候选项的最低得分。 定位器的最低得分是一个介于 0 和 100 之间的值。仅包括达到或超过 geocode 方法返回的最小候选得分的候选项。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Integer |
| minMatchScore (可读写) | geocode 方法的结果要被视为匹配项而必须具备的最小得分。 最低得分是一个阈值，用于控制地址与参考数据中最有可能被视为匹配项的候选项的必须匹配程度。 如果潜在候选项低于阈值，则地址与候选项不匹配。 定位器的最低匹配得分是一个介于 0 和 100 之间的值。 完全匹配的得分是 100。 如果工作流需要置信度较高的匹配地址，请将属性设置为更高的阈值。 较高的设定值可确保仅返回质量最高的匹配项。 要尽可能得到更多的可匹配地址而不介意某些地址可能存在匹配错误，则使用较低的阈值设置。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Integer |
| multilineInputFields (只读) | 用于多行地理编码的定位器字段。 此属性针对定位器的多行输入字段返回 arcpy.Field 对象列表。 对表进行地理编码时，可以将多行地理编码表字段 映射到 Field 对象的 name 属性。 | Field |
| numberOfThreads (可读写) | 要用于批量地理编码的线程数。 为了达到此属性的最佳使用效果，请确定您的计算机上可用于地理编码作业的可用物理核数。 可以使用计算机上的所有物理核更快地完成地理编码作业。 默认情况下，此值设置为较小的值以在任何计算机上运行（无论计算机上可用的物理核数是多少），但如果您知道可用的核数，则可以进行配置以使用更多物理核。 例如，要检测计算机上的物理核数并优化所使用的线程数，请使用 numberOfThreads = 0，这相当于在定位器的定位器属性对话框中选择自动。 如果您需要其他资源供其他应用程序使用，还可以指定用于地理编码的物理核的数量，例如 numberOfThreads = 2。 如果您计划将定位器共享至 ArcGIS Enterprise，则建议您将此值设置为 4。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Integer |
| partialHouseNumberSuggestions (可读写) | 指定仅输入门牌号的一部分时是否返回门牌号建议。 此选项仅适用于门牌号附加在街道名称之后的国家。 有关如何使用此属性的详细信息，请参阅提高地理编码质量的提示。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Boolean |
| partialSubaddressSuggestions (可读写) | 指定当仅提供部分子地址值作为输入时，suggest 方法是否返回子地址。 有关如何使用此属性的详细信息，请参阅子地址建议。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Boolean |
| preferredLabelValues (可读写) | 通过指定输出字段中将包含的地址部分，可使用此属性配置定位器响应中返回的输出字段。 此属性支持使用单个值或逗号分隔的字符串值作为输入。 有关此属性工作原理的详细信息，请参阅其他调整选项。 可能的值包括 postalCity、localCity、matchedCity、primaryStreet 和 matchedStreet。 注：仅可包含一个用于城市标注的值和一个用于街道标注的值。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | String |
| returnCollections (可读写) | 指定搜索 POI 时 suggest 方法是否返回集合（感兴趣点 [POI] 类别）。 有关如何使用此属性的详细信息，请参阅返回集合。 默认设置为 True。 此属性设置为 False 时，如果第一个字符与用于根据 POI 角色构建定位器的数据中的一个类别相关联，则返回的 POI 候选项列表中不会包含类别名称。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Boolean |
| returnInputLocation (可读写) | 指定 reverseGeocode 方法返回的几何是原始输入几何还是返回的匹配地址的几何。 默认值为 False。 当设置为 True 时，reverseGeocode 结果将与原始输入几何一起返回。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Boolean |
| reverseOutputFields (可读写) | reverseGeocode 方法将返回的输出字段。 默认值为空字符串，表示所有输出字段都将随 reverseGeocode 结果一起返回。 值可以是一个字符串，其中包含要与 reverseGeocode 结果一起返回的字段子集的逗号分隔列表。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | String |
| sideOffset (可读写) | 出于显示目的，用于将结果从街道要素的一端向远偏移的距离（以米为单位）。 有关如何使用此属性的详细信息，请参阅单侧偏移。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Double |
| singleLineInputField (只读) | 用于单行地理编码的定位器字段。 此属性可返回代表定位器的单行输入字段的 arcpy.Field 对象。 对表进行地理编码时，可以将单行地理编码表字段映射到 Field 对象的 name 属性。 | Field |
| spatialReference (只读) | 定位器的空间参考。 空间参考将与用于创建定位器的数据相同。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | String |
| subaddressAfterBaseAddressSuggestions (可读写) | 指定在输入基础地址后是否返回子地址建议。 设置为 True 时，还支持输入完整单元或部分单元。 表示基址的要素必须存在于定位器中，才能查看为基址列出的建议候选项。 有关如何使用此属性的详细信息，请参阅提高地理编码质量的提示。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Boolean |
| subaddressSummaryWithBaseAddress (可读写) | 指定在输入基础地址后是否返回某地址处子地址单元的汇总。 子单元的摘要可以是参考数据中基于属性的子单元值的范围或者地址的子单元数，后者适用于参考数据是多种单元类型的组合或多个子地址元素映射到定位器中的情况。 只有表示基础地址的要素显示在定位器中时，在键入基础地址时才可以看到子单元的摘要。 有关如何使用此属性的详细信息，请参阅提高地理编码质量的提示。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | Boolean |
| supportedCategories (只读) | 定位器支持的类别。 有关可用于自定义构建定位器和 ArcGIS StreetMap Premium 定位器的受支持的类别的详细信息，请参阅支持的类别。 | String |
| supportedCountries (只读) | 定位器支持的国家/地区。 | String |
| supportedRoles (只读) | 定位器支持的角色。 | String |
| reverseGeocodeFeatureTypes (可读写) | reverseGeocode 方法支持的要素类型。 有关此属性的详细信息，请参阅支持反向地理编码的要素。 对于地理编码服务，此属性是只读的。 要在已发布的定位器中更改此属性，请在本地进行修改，然后再次发布定位器。 注：此属性仅设置为运行时属性。 除非您使用 updateLocator 方法，否则该属性不会保存至当前会话之外的定位器。 | String |
方法概述
| 方法 | 说明 |
| geocode (searchText, forStorage, {preferredSearchLocation}, {countryCode}, {categories}, {locationType}, {outFields}, {maxResults}, {minScore}, {outputLanguageCode}, {preferredLabelValues}, {searchExtent}, {matchNarrative}, {searchWithin}, {start}, {num}, {matchID}, {comprehensiveZoneMatch}) |
以地址或位置作为输入，并返回地理编码结果候选项。结果候选项是可以在地图上显示或用作其他分析的输入的点。 |
| reverseGeocode (location, forStorage, {featureTypes}, {locationType}, {outputLanguageCode}, {preferredLabelValues}) |
以 PointGeometry 对象作为输入，并返回最接近的地址、兴趣点或与该点的交叉点。结果是反向地理编码结果，其中包含有关匹配地址或位置的信息、包括 x 坐标和 y 坐标的几何信息以及其他属性（取决于使用的 Locator）。 |
| suggest (searchText, {preferredSearchLocation}, {countryCode}, {categories}, {maxResults}, {preferredLabelValues}, {returnCollections}, {searchExtent}) | 为不完整或部分用户输入生成自动完成建议。 单个建议结果可被传递至 geocodeWithSuggest 方法，以生成可在地图上显示或用作其他分析的输入的点。 |
| geocodeWithSuggest (suggestResult, forStorage, {preferredSearchLocation}, {countryCode}, {categories}, {locationType}, {outFields}, {maxResults}, {minScore}, {outputLanguageCode}, {preferredLabelValues}, {searchExtent}) | 以单个 suggest 方法结果作为输入，并返回地理编码结果候选项。结果候选项是可以在地图上显示或用作其他分析的输入的点。 建议您将相同参数传递至在生成 suggest 方法结果时传递至 geocodeWithSuggest 的方法，这将用来获得一致的结果。 |
| updateLocator () | 保留在与定位器的当前 Python 会话期间对 Locator 属性进行的更改，以便应用这些属性以供未来使用。 |
方法
geocode (searchText, forStorage, {preferredSearchLocation}, {countryCode}, {categories}, {locationType}, {outFields}, {maxResults}, {minScore}, {outputLanguageCode}, {preferredLabelValues}, {searchExtent}, {matchNarrative}, {searchWithin}, {start}, {num}, {matchID}, {comprehensiveZoneMatch})| 参数 | 说明 | 数据类型 |
searchText | 将用于查找位置的地址或地名。 | String |
forStorage | 指定是否存储结果。 当设置为 False 时，结果可以临时显示在地图上。 例如，如果将结果存储在数据库中，则将此参数设置为 True。 此参数仅适用于使用 ArcGIS World Geocoding Service 的地理编码请求。 对于所有其他定位器，它将被忽略。 注：合同中禁止应用程序存储使用 ArcGIS World Geocoding Service 的地理编码操作结果，除非其通过传递值为 True 的此参数进行请求。 对于定位器，使用 ArcGIS World Geocoding Service 有效，您必须使用有效的组织账户登录 ArcGIS Online。 对于每个地理编码事务，将从组织账户中扣除 ArcGIS Online 服务配额。 | Boolean |
preferredSearchLocation | 将用于根据其与位置的邻近程度来优先使用或增强地理编码候选项的原点。 相对于较远的位置，该位置附近的候选人优先。 | PointGeometry |
countryCode | 以逗号分隔的三字符国家/地区代码字符串，可将地理编码结果限制为一组指定的国家/地区，这将在大多数情况下提高地理编码的准确性。 如果未指定国家/地区，则使用定位器的所有受支持国家/地区进行带建议的地理编码。 如果您使用 ArcGIS World Geocoding Service，则请参阅受支持国家/地区的列表。 | String |
categories | 以逗号分隔的类别列表，限制定位器搜索的位置类型，从而消除误报匹配并可能加快搜索过程的速度。 有关类别过滤的详细信息，请参阅 REST API Web 帮助。 | String |
locationType | 指定将用于 PointAddress 匹配的首选输出位置。 如果数据中不存在首选位置，则会返回默认位置。 此参数仅影响几何，不影响属性值。
(默认值为 rooftop) | String |
outFields | 将作为结果中属性一部分返回的字段列表。 此参数支持单个字段名称或以逗号分隔的字段名称字符串（无空格）。 要返回默认输出字段，不需要通过此参数。 使用星号 ("*") 将返回结果的所有可用输出字段。 输出字段将在地理编码结果中包含的内容中进行说明。 | String |
maxResults | 将返回的位置的最大数量，高达定位器允许的最大数。 如果未指定任何值，则将返回所有匹配候选项，最高可达 Locator 属性中指定的最大数量。 | Integer |
minScore | 将返回的候选项限制为得分高于此值的那些候选项。 有效值介于 0 和 100 之间。 | Integer |
outputLanguageCode | 将返回的地理编码结果所使用的语言。 由于许多国家/地区的地址和地点都可以使用一种以上的语言，这可确保以预期的语言返回结果。 如果您正在使用 ArcGIS World Geocoding Service，请参阅受支持国家/地区列表，以了解这些国家/地区支持的语言代码。 | String |
preferredLabelValues | 通过指定应包含在输出字段中的地址组件值，配置定位器响应中返回的输出字段。 此参数支持使用单个值或逗号分隔的字符串值作为输入。 有关此参数工作原理的详细信息，请参阅其他调整选项。 可能的值包括 postalCity、localCity、matchedCity、primaryStreet 和 matchedStreet。 注：仅可包含一个用于城市标注的值和一个用于街道标注的值。 | String |
searchExtent | 用于限制将搜索的区域的范围。 返回超出指定范围的所有结果都将被排除。 | Extent |
matchNarrative | 指定是否将返回有关地理编码结果获取方式的信息。 当此参数设置为 True 时，返回值将描述定位器如何处理或分类 geocode 请求中输入字符串的每个部分。 该信息将作为一个名为 match-narrative 的额外 JSON 对象添加进来。 例如，如果字符串为 380 New York Street, Redlands，match-narrative 对象将描述输入中每个部分的匹配方式。 在 match-narrative 对象中，输入搜索字符串的每个部分都由一个子对象表示，其顺序与输入部分的顺序相对应。 例如，对于地址 380 New York Street, Redlands，每个子对象都将包含以下键：
有关匹配叙述代码和描述的完整列表，请参阅匹配叙述代码描述。 (默认值为 False) | Boolean |
searchWithin | 指定为与地理编码位置相关联的地点集合返回的要素类型。 例如，该参数可用来返回存在于某个邮政编码范围内的所有地址，或位于特定地址的所有企业。 仅可针对具有 Addr_type 值 PointAddress 和 PostalExt 的地理编码匹配项返回集合。 此参数支持使用单个值或逗号分隔的字符串值作为输入，例如 searchWithin="POI,Subaddress"。 有关此参数工作原理的详细信息，请参阅返回关联要素或 REST API 文档。 可能的值包括 PointAddress、Subaddress 和 POI。 此参数支持分页。 因为在一个地理编码位置上或范围内可能存在数以百计或数以千计的地点，所以此参数将与 start 和 num 参数搭配使用，用于将大型集合分解为可管理的结果集或每页包含不超过 50 个候选项的页面。 这是通过向定位器连续传递具有不同 start 值的请求来实现的。 为了支持分页，当为 searchWithin 请求返回一个集合时，JSON 响应将在响应末尾包含以下键：
如果将此参数与 ArcGIS World Geocoding Service 搭配使用，该请求还必须包含有效的令牌。 注：响应中的第一个对象（候选项 1）始终为地理编码对象：被搜索的地点。 以下是与地理编码对象相关联并对应于指定要素类型的要素。 | String |
start | 要在返回值中返回的候选项集合中第一个条目的索引编号。 此参数将与 searchWithin 和 num 参数搭配使用，以分页查看超过 50 个候选项的大型结果集。 仅在指定 searchWithin 值时使用此参数。 (默认值为 1) | Integer |
num | 每个页面中将返回的集合候选结果数量。 此参数将与 searchWithin 和 start 参数搭配使用，以分页查看超过 50 个候选项的大型结果集。 值应为 1 和 50 之间的整数。 如果指定的值大于 50，则最多只会返回 50 个候选项。 仅在指定 searchWithin 值时使用此参数。 (默认值为 50) | Integer |
matchID | 地址或地点的 ID。 可以从结果中获取该值，并在以后进行使用。 在大多数情况下，特定地址的值在各个版本的 ArcGIS World Geocoding Service 和 ArcGIS StreetMap Premium 定位器中将保持不变；然而对于自定义定位器，MatchID 字段的值将与使用创建定位器工具构建定位器时所用的数据保持一致。 以下为使用此参数的示例：matchID="AQFV9QAAmeQBAJUBBAAAAAAMD05FVyBZT1JLIFNUUkVFVBUDMzgwZgNFTkc"。 要了解有关此参数的详细信息，请参阅 REST API 文档。 | String |
comprehensiveZoneMatch | 指定与城市名称不完全匹配的输入地址是否会返回候选项。 当设置为 True 时，即使城市名称不正确，地址也将视为匹配。 当设置为 False 时，不会返回匹配项或匹配项的得分显著降低。 有关此参数使用方法的详细信息，请参阅综合区域匹配。 (默认值为 True) | Boolean |
| 数据类型 | 说明 |
| List | 输出是字典对象的列表。 每个字典对象代表一个地理编码结果。 每个地理编码结果包含有关匹配地址或位置的信息，包括 x 坐标和 y 坐标的几何信息以及其他属性，具体取决于所使用的 Locator 对象和指定的 outFields 值。 |
注：
如果您正在使用您的门户上的定位器，请确保您已登录系统并在 ArcGIS AllSource 中将其设置为您的活动门户。 要访问除活动门户之外的门户上的定位器，您可以使用 SignInToPortal 进行身份验证：用来使用磁盘上的定位器查找地点位置或地址的地理编码。
import arcpy
# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)
# Geocode to find the location of an address
geocoding_candidates = locator.geocode("1670 W Peachtree St NE, Atlanta, GA 30309", False)用来使用 ArcGIS World Geocoding Service 查找地点位置或地址的地理编码。
import arcpy
# Create a new Locator object from the ArcGIS World Geocoding Service
locator_path = "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/ArcGIS World Geocoding Service"
locator = arcpy.geocoding.Locator(locator_path)
# Geocode to find the location of an address
geocoding_candidates = locator.geocode("1670 W Peachtree St NE, Atlanta, GA 30309", True)用来使用通过 AGS 连接访问的定位器查找地点位置或地址的地理编码。
import arcpy
# Create a new Locator object from a locator published to ArcGIS Server
locator_path = r"C:\AGS Files\MyAGSConnectionFile.ags\Atlanta"
locator = arcpy.geocoding.Locator(locator_path)
# Geocode to find the location of an address
geocoding_candidates = locator.geocode("1670 W Peachtree St NE, Atlanta, GA 30309", False)reverseGeocode (location, forStorage, {featureTypes}, {locationType}, {outputLanguageCode}, {preferredLabelValues})| 参数 | 说明 | 数据类型 |
location | A point for which you want to find the nearest address, point of interest, or intersection. | PointGeometry |
forStorage | Specifies whether the results will be stored. The default value is False, which indicates the results won't be stored, but they can be temporarily displayed on a map. If you store the results, in a database, for example, set this parameter to True. This parameter only applies to geocoding requests made with ArcGIS World Geocoding Service. For all other locators, the parameter is ignored. 注：Applications are contractually prohibited from storing the results of geocoding operations using ArcGIS World Geocoding Service unless they make the request by passing the forStorage parameter with a value of True. For a locator using ArcGIS World Geocoding Service to be valid, you must sign in to ArcGIS Online with a valid organizational account. ArcGIS Online service credits are deducted from the organizational account for each geocode transaction that includes the forStorage parameter with a value of True. (默认值为 False) | Boolean |
featureTypes | The match types that will be returned. If only one value is provided, the search tolerance is adjusted. For more information about how this parameter is used in ArcGIS World Geocoding Service, see the REST API documentation. | String |
locationType | Specifies the preferred output location that will be used. If the preferred location does not exist in the data, the default location will be returned instead. For more information about this parameter, see the Reverse Geocode REST API documentation. This parameter only affects the geometry, not the attribute values.
(默认值为 rooftop) | String |
outputLanguageCode | The language in which the reverse geocode results will be returned. Since addresses and places in many countries are available in more than one language, this ensures that results are returned in the expected language. If you are using ArcGIS World Geocoding Service, see the list of supported countries for the language codes that are supported for those countries. | String |
preferredLabelValues | Configures the output fields returned in a response from the locator by specifying the address component values that should be included in the output fields. The parameter supports a single value or a comma-delimited string of values as input. For more information about how this parameter works, see Additional tuning options. Possible values include postalCity, localCity, matchedCity, primaryStreet, and matchedStreet. 注：Only one value for city labeling and one value for street labeling can be included. | String |
| 数据类型 | 说明 |
| List | 反向地理编码结果包含有关匹配地址或位置的信息，包括 x 和 y 坐标的几何信息以及其他属性，具体取决于使用的 Locator 对象以及 Shape 键（当值为 PointGeometry 对象时）。 |
注：
如果您正在使用您的门户上的定位器，请确保您已登录系统并在 ArcGIS AllSource 中将其设置为您的活动门户。 要访问除活动门户之外的门户上的定位器，您可以使用 SignInToPortal 进行身份验证：通过反向地理编码以使用磁盘上的定位器查找到给定位置的最近地点或地址。
import arcpy
# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)
# Create input PointGeometry object
spatial_reference = arcpy.SpatialReference(4326)
point = arcpy.Point(-84.374, 33.797)
point_geometry = arcpy.PointGeometry(point, spatial_reference)
# Reverse geocode to find the nearest address or place to the point
reverse_geocode_result = locator.reverseGeocode(point_geometry, False)反向地理编码以使用 ArcGIS World Geocoding Service 查找到给定位置的最近地点或地址。
import arcpy
# Create a new Locator object from the ArcGIS World Geocoding Service
locator_path = "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/ArcGIS World Geocoding Service"
locator = arcpy.geocoding.Locator(locator_path)
# Create input PointGeometry object
spatial_reference = arcpy.SpatialReference(4326)
point = arcpy.Point(-84.374, 33.797)
point_geometry = arcpy.PointGeometry(point, spatial_reference)
# Reverse geocode to find the nearest address or place to the point
geocoding_candidates = locator.reverseGeocode(point_geometry, True)通过地理编码以使用 AGS 连接查找到给定位置的最近地点或地址。
import arcpy
# Create a new Locator object from a locator published to ArcGIS Server
locator_path = r"C:\AGS Files\MyAGSConnectionFile.ags\Atlanta"
locator = arcpy.geocoding.Locator(locator_path)
# Create input PointGeometry object
spatial_reference = arcpy.SpatialReference(4326)
point = arcpy.Point(-84.374, 33.797)
point_geometry = arcpy.PointGeometry(point, spatial_reference)
# Reverse geocode to find the nearest address or place to the point
geocoding_candidates = locator.reverseGeocode(point_geometry, False)suggest (searchText, {preferredSearchLocation}, {countryCode}, {categories}, {maxResults}, {preferredLabelValues}, {returnCollections}, {searchExtent})| 参数 | 说明 | 数据类型 |
searchText | The partial text that will be used to generate suggestions. | String |
preferredSearchLocation | The origin point that will be used to prefer or boost suggestion candidates based on their proximity to the location. Candidates near the location are prioritized relative to those farther away. | PointGeometry |
countryCode | A comma-delimited string of three-character country codes that limits suggestion results to the set of specified countries, which will improve the accuracy of suggestions in most cases. When no country is specified, suggestions will be generated from all countries supported by the locator. If you are using ArcGIS World Geocoding Service, see the list of supported countries in Geocode data coverage. | String |
categories | A comma-separated list of categories that limits the types of places the locator uses to generate suggestions, eliminating false positive matches and potentially speeding up the process. See the REST API web help for details about category filtering. | String |
maxResults | The maximum number of suggestions that will be returned, up to the maximum number allowed by the locator. If no value is provided, all matching suggestions up to the maximum specified by the maxSuggestCandidates property in the Locator properties will be returned. | Integer |
preferredLabelValues | Configures the output fields returned in a response from the locator by specifying the address component values that should be included in the output fields. The parameter supports a single value or a comma-delimited string of values as input. For more information about how this parameter works, see Additional tuning options. Possible values include postalCity, localCity, matchedCity, primaryStreet, and matchedStreet. 注：Only one value for city labeling and one value for street labeling can be included. | String |
returnCollections | Specifies whether collections (points of interest [POI] categories) will be returned when searching for POI. For more information about how to use the returnCollections parameter, see Return collections. When this parameter is False, if the first character is associated with a category that exists in the data used to build a locator based on the POI role, the category name will not be included in the list of POI candidates returned. (默认值为 True) | Boolean |
searchExtent | An extent that limits the area that will be searched. All results that are returned outside of the specified extent will be excluded. | Extent |
| 数据类型 | 说明 |
| List | suggest 方法的输出是字典对象的数组。 每个字典代表一个建议结果。 每个建议结果包含 text、magicKey 和 isCollection 键。 要使用此方法的输出，在所需的列表索引处将整个字典传递至 geocodeWithSuggest 方法。 注：要了解有关字典键值的详细信息，请参阅 REST API 文档。 |
注：
如果您正在使用您的门户上的定位器，请确保您已登录系统并在 ArcGIS AllSource 中将其设置为您的活动门户。 要访问除活动门户之外的门户上的定位器，您可以使用 SignInToPortal 进行身份验证：使用磁盘上的定位器根据不完整的用户输入字符串生成建议。
import arcpy
# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)
# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")使用 ArcGIS World Geocoding Service 根据不完整的用户输入字符串生成建议。
import arcpy
# Create a new Locator object from the ArcGIS World Geocoding Service
locator_path = "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/ArcGIS World Geocoding Service"
locator = arcpy.geocoding.Locator(locator_path)
# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")使用通过 AGS 连接访问的定位器，根据不完整的用户输入字符串生成建议。
import arcpy
# Create a new Locator object from a locator published to ArcGIS Server
locator_path = r"C:\AGS Files\MyAGSConnectionFile.ags\Atlanta"
locator = arcpy.geocoding.Locator(locator_path)
# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")geocodeWithSuggest (suggestResult, forStorage, {preferredSearchLocation}, {countryCode}, {categories}, {locationType}, {outFields}, {maxResults}, {minScore}, {outputLanguageCode}, {preferredLabelValues}, {searchExtent})| 参数 | 说明 | 数据类型 |
suggestResult | The output from the suggest method. The suggestion result is a dictionary that contains text, magicKey, and isCollection keys and is used to locate an address or place. To learn more about the keys included in the suggestion result dictionary objects, see the REST API documentation. | Dictionary |
forStorage | Specifies whether the results will be stored. The default value is False, which indicates the results won't be stored, but they can be temporarily displayed on a map. If you store the results, in a database, for example, set this parameter to True. This parameter only applies to geocoding requests made with ArcGIS World Geocoding Service. For all other locators, the parameter is ignored. 注：Applications are contractually prohibited from storing the results of geocoding operations using ArcGIS World Geocoding Service unless they make the request by passing the forStorage parameter with a value of True. For a locator using ArcGIS World Geocoding Service to be valid, you must sign in to ArcGIS Online with a valid organizational account. ArcGIS Online service credits are deducted from the organizational account for each geocode transaction that stores results.(默认值为 False) | Boolean |
preferredSearchLocation | The origin point that will be used to prefer or boost geocoding candidates based on their proximity to the location. Candidates near the location are prioritized relative to those farther away. | PointGeometry |
countryCode | A comma-delimited string of three-character country codes that limits geocoding results to the set of specified countries, which will improve the accuracy of geocoding in most cases. When no country is specified, geocoding with suggestions will be performed using all countries supported by the locator. If you are using ArcGIS World Geocoding Service, see the list of supported countries. | String |
categories | A comma-separated list of categories that limits the types of places the locator searches, eliminating false positive matches and potentially speeding up the search process. See the REST API web help for details about category filtering. | String |
locationType | Specifies the preferred output geometry that will be used forPointAddress matches. If the preferred location does not exist in the data, the default location will be returned instead. This parameter only affects the geometry, not the attribute values.
(默认值为 rooftop) | String |
outFields | The list of fields that will be returned as part of the attributes in the result. This parameter supports a single field name or a comma-delimited string of field names (with no spaces). To return the default output fields, outFields does not need to be passed. Use an asterisk ("*") to return all available output fields with the result. The output fields are described in What's included in the geocoded results. | String |
maxResults | The maximum number of locations that will be returned, up to the maximum number allowed by the locator. If no value is provided, all matching candidates up to the maximum specified by the maxCandidate property in the Locator properties will be returned. | Integer |
minScore | Limits the candidates that are returned to those with a score above the value set for this parameter. Valid values are between 0 and 100. | Integer |
outputLanguageCode | The language in which the geocode results will be returned. Since addresses and places in many countries are available in more than one language, this ensures that results are returned in the expected language. If you are using ArcGIS World Geocoding Service, see the list of supported countries for the language codes that are supported for those countries. | String |
preferredLabelValues | Configures the output fields returned in a response from the locator by specifying the address component values that should be included in the output fields. The parameter supports a single value or a comma-delimited string of values as input. For more information about how this parameter works, see Additional tuning options. Possible values include postalCity, localCity, matchedCity, primaryStreet, and matchedStreet. 注：Only one value for city labeling and one value for street labeling can be included. | String |
searchExtent | An extent that limits the area that will be searched. All results that are returned outside of the specified extent will be excluded. | Extent |
| 数据类型 | 说明 |
| List |
geocodeWithSuggest 方法的输出是字典对象的列表。 每个字典代表一个地理编码结果。 每个地理编码结果包含有关匹配地址或位置的信息，包括 x 坐标和 y 坐标的几何信息以及其他属性，具体取决于所使用的 Locator 对象和指定的 outFields 值。 |
注：
如果您正在使用您的门户上的定位器，请确保您已登录系统并在 ArcGIS AllSource 中将其设置为您的活动门户。 要访问除活动门户之外的门户上的定位器，您可以使用 SignInToPortal 进行身份验证：根据不完整的用户输入字符串生成建议，并使用生成的建议之一作为该操作的输出来进行地理编码，以使用磁盘上的定位器查找位置。
import arcpy
# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)
# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")
# Geocode using one of the suggestions generated as the output of the suggest
# operation
geocoding_candidates = locator.geocodeWithSuggest(suggestion_candidates[0], False)根据不完整的用户输入字符串生成建议，并使用生成的建议之一作为该操作的输出来进行地理编码，以使用 ArcGIS World Geocoding Service 查找位置。
import arcpy
# Create a new Locator object from the ArcGIS World Geocoding Service
locator_path = "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/ArcGIS World Geocoding Service"
locator = arcpy.geocoding.Locator(locator_path)
# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")
# Geocode using one of the suggestions generated as the output of the suggest
# operation
geocoding_candidates = locator.geocodeWithSuggest(suggestion_candidates[0], True)根据不完整的用户输入字符串生成建议，并使用生成的建议之一作为该操作的输出来进行地理编码，以使用通过 AGS 连接访问的定位器查找位置。
import arcpy
# Create a new Locator object from a locator published to ArcGIS Server
locator_path = r"C:\AGS Files\MyAGSConnectionFile.ags\Atlanta"
locator = arcpy.geocoding.Locator(locator_path)
# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")
# Geocode using one of the suggestions generated as the output of the suggest
# operation
geocoding_candidates = locator.geocodeWithSuggest(suggestion_candidates[0], False)updateLocator ()
更新磁盘上定位器的属性，并保留更改。
import arcpy
# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)
# Update the minimum match score property on the locator
locator.minMatchScore = 95
# Persist changes to the .loc file
locator.updateLocator()