URI

<geocodeService_uri>/findAddressCandidates[.<format>]

支持的方法

GET、POST、HEAD

父资源

geocodeService

介绍

正向匹配，根据关键词查找地址，并返回地址、位置和匹配分数等信息。支持的搜索范围较 Suggest 资源更大。

请注意：转发由 10.2、10.9 版本 ArcGIS Server 发布的地址匹配服务仅支持部分请求参数，支持的情况在下表中“转发 10.2/10.9 ArcGIS Server 的服务是否支持”列标注。

支持的方法：

  • GET：获取正向地址匹配结果。
  • POST：按照给定参数进行正向地址匹配查询。
  • HEAD：检查 findAddressCandidates 资源是否存在，或权限是否可以访问 findAddressCandidates 资源。

HTTP 请求方法

对如下 URI 执行 HTTP 请求，以 json 输出格式为例加以说明，其中，supermapiserver 是服务器名，{component}是服务组件名。

http://supermapiserver:8090/iserver/services/{component}/arcgisrest/geocode/GeocodeServer/findAddressCandidates.json

GET 请求

获取正向地址匹配结果。

请求参数

名称 类型 含义 转发10.2/10.9 ArcGIS Server的服务是否支持
f String 【必填参数】响应格式，支持 json，pjson √
address， address2， address3 String[] 多行地址参数，针对国外地址有多行/多组词汇的情况设计的参数结构，利用三个地址参数来表示街道地址的不同组成部分

每一个 address 是一个字符串，例如：address=Beetham Tower、address2=301 Deansgate 和 address3=Suite 4208
一般情况下，一个 address 代表地址中的一行 		由geocodeService响应中返回的addressFields字段名称作为地址查询参数
neighborhood String 与地址关联的最小行政单位，较 city 更小（不是所有国家或地区都使用该参数）  
city String 与地址关联的第二小行政单位，通常是城市或直辖市，较 subregion 或 region 更小  
subregion String 与地址关联的第二大行政单位，根据国家/地区的不同，可以表示县、州或省  
region String 与地址关联的最大行政区域，通常是州或省  
postal String 地址的标准邮政编码，通常为3到6位字母数字代码      
postalExt String 邮政编码扩展名  
countryCode String 用于限制返回结果的国家代码。可使用的值包括英文或国家/地区官方语言的国家/地区全名、双字符国家/地区代码或三字符国家/地区代码。

代码列表见：https://developers.arcgis.com/rest/geocode/geocode-coverage

请注意：如果 请求参数中同时包含 countryCode 和 sourceCountry ，并且值不同时，则优先使用 countryCode 的参数值。   		 
sourceCountry String[] 用于限制返回结果的关联国家。可传入单个值或多个值，传入多个值时用逗号分隔。仅支持三字符国家/地区代码。

代码列表见：https://developers.arcgis.com/rest/geocode/geocode-coverage

请注意：如果 请求参数中同时包含 countryCode 和 sourceCountry ，并且值不同时，则优先使用 countryCode 的参数值。   		 
singleLine String 单行地址参数，将多行/多组地址词汇在一个参数中传递。与上述多行地址参数不能同时使用 由geocodeService响应中返回的singleLineAddressField字段名称作为地址查询参数
category String[] 用于设置过滤的地点或地址类型，从而在指定地址字段中进行匹配而不再返回匹配其他字段的结果。可传入单个或多个类别值，用逗号分隔。可与 address 或 singleLine 参数组合使用，也可单独使用。
请注意：当通过工作空间发布 ArcGIS REST 地址匹配服务时，该参数不可通过在服务配置文件中指定 filterFields 参数控制 		 
outFields String[] 响应体中 attributes 对象中返回的字段列表。可传入多个值，需用逗号分隔。

默认情况下，响应中会返回 address 、 location（匹配点的 x、y 坐标）、 score 、 extent 和 spatialReference 对象。如果请求中不包含该参数，或者包含该参数但未设置值，则响应中的 attributes 对象为空。 		√
maxLocations int 返回匹配结果的最大数量。如果未指定，则返回所有匹配的候选项，直到服务允许的最大值  
outSR String 结果的坐标系。如果未指定，则坐标系与服务的坐标系相同 √
searchExtent ArcGISEnvelope 一组边界框坐标，用于指定特定搜索区域，如果搜索区域的坐标系与服务的坐标系不同，则必需设置坐标系。例如：
searchExtent= -109.55,25.76,-86.39,49.94		 √
location ArcGISPoint2D 一个点坐标，用于根据候选项与该位置的接近程度来排序，如果搜索区域的坐标系与服务的坐标系不同，则必需设置坐标系。例如：location=-109.55,25.76  
magicKey String 用于优化检索速度。使用方法：

1、先对 suggest 资源进行请求，响应体中返回 {text} 和 {magicKey}

2、在本资源的请求参数中，{text} 作为 singleLine 的参数值、{magicKey} 作为 magicKey 的参数值

3、若在步骤1对 suggest 资源的请求中使用了 searchExtent 和 location 参数，对本资源请求时也需体现 		 
matchOutOfRange Boolean 请求时设置的门牌号超出设置的街道定义的门牌号范围时，是否应返回该街道地址匹配项，默认为true  
locationType String 用于指定响应体中 location 坐标使用的位置，可选值为rooftop（屋顶坐标）和 street（街道位置坐标）。默认为rooftop  
langCode String 指定响应体中返回结果的语言，只可设置一种语言代码；若未设置或无匹配项，将按搜索请求中使用的语言返回

代码列表见：https://developers.arcgis.com/rest/geocode/geocode-coverage 		 
preferredLabelValues String[] 指定响应体中包含的地址按照何种信息返回。可传入单个或多个类别值，用逗号分隔。

参数值对应于两个组，每组只能提供一个值：City 和 Street 。City 的可选值包括：postalCity（邮政城市） , localCity（本地城市）和 matchedCity（匹配城市）；Street 的可选值包括：primaryStreet（主要街道）和 matchedStreet（匹配街道）。

若 countryCode 或 sourceCountry 为美国时，地址信息将默认按照 postalCity 和 matchedStreet 返回 		 

响应结构

对 findAddressCandidates 资源执行 GET 请求，返回的资源表述的结构如下:

字段 类型 说明
spatialReference ArcGISSpatialReference 空间参考
candidates AddressInfo 匹配结果的地址信息，包括如下字段：

1、address：完整匹配地址；
2、location：匹配位置的点坐标，包括 x、y 和 spatialReference 属性；
3、score：匹配分数；
4、extent：匹配地址所在区域的最小几何范围，包括 xmin、ymin、xmax、ymax等坐标信息。坐标系由 spatialReference 参数决定；
5、attributes：匹配地址的属性信息，包含的字段如下表所示。

附表 attributes 对象参数结构（实际包含的参数以数据源本身为准）

字段 类型 说明
Status String 指示匹配程度。

1、当该地址能够匹配且为得分最高者时，则为 M；
2、当该地址能够匹配但与一个或多个其他候选项的分数相同时，则为 T；
3、没有地址可匹配，则为 U。
Score double 该地址的匹配分数
Match_addr String 完整地址。格式基于地址所在国家/地区的地址标准
LongLabel String 完整地址。较 Match_addr 包含更多信息的地址书写方式
ShortLabel String Match_addr 的简化书写
Addr_type String 地理编码请求的地址类型。支持的类型因国家/地区而异。可选值包括 Subaddress、StreetAddress、PointAddress、POI、Locality 等19种。

详见：https://developers.arcgis.com/rest/geocode/service-output/
Type String 返回结果的特征类型。仅当 Addr_type 为 POI、Locality 时有值，其他为空
PlaceName String 地址候选项的正式名称，如 Paris
Place_addr String 地点的完整街道地址信息，包括街道、城市和区域
Phone String 地址所在地点的电话，仅当 Addr_type 为 POI 时有值，其他为空
URL String 地址所在地点的主网站 URL，仅当 Addr_type 为 POI 时有值，其他为空
Rank double 此项结果相对于其他同名结果的优先级
AddBldg String 地址所在地点的建筑物名称
AddNum String 地址中含有的数字值，仅当 Addr_type 为 StreetAddress、PointAddress 时有值，其他为空
例如：在 380 New York Street 中，该值为380
AddNumFrom int 表示街道地址范围的开始编号。仅当 Addr_type 为 StreetAddress 时有值，其他为空

请注意：该值与矢量化方向相关，不一定是范围内的最小数字
AddNumTo int 表示街道地址范围的结束编号。仅当 Addr_type 为 StreetAddress 时有值，其他为空

请注意：该值与矢量化方向相关，不一定是范围内的最大数字
AddRange String 地址所在街段的完整门牌号范围，格式为 AddNumFrom-AddNumTo
Side String 地址所在的街道相对于矢量化方向的一侧，可选值为 R 或 L。大多数情况该字段为空
StPreDir String 地址中的街道方向，一般出现在主要街道名称之前。
例如：在 North Main Street 中，该值为 North
StPreType String 地址中的街道类型。
例如：在 Avenida Central 中，该值为 Avenida
StName String 地址中街道的主名称。
例如：在 380 New York St 中，该值为 New York
StType String 地址中街道的定义方式。
例如：在 380 New York St 中，该值为 St
StDir String 地址中的街道方向，一般出现在主要街道名称之后。
例如：在 Main Street North 中，该值为 North
BldgType String 地址中建筑的类型，例如 building、hangar 和 tower
BldgName String 地址中建筑的名称或编号。
例如：在 building A 中，该值为 A
LevelType String 地址中楼层的类型，例如 floor、level、department 和 wing
LevelName String 地址中楼层的名称或编号。
例如：在 level 3 中，该值为 3
UnitType String 地址中单元的类型，例如 unit、apartment、flat、office 和 suite
UnitName String 地址中单元的名称或编号。
例如：在 apartment 2B 中，该值为 2B
SubAddr String Subaddress 中的完整子地址信息，包括 type 和 name。仅当 Addr_type 为 Subaddress 时有值，其他为空，例如 Apt 4B。
StAddr String 地址中的街道地址，不含城市和区域等信息
Block String 地址中的行政区划
Sector String 地址中的部级行政区域名称，是 block 的集合
Nbrhd String 地址中的社区级行政区域名称，是 city 的子集
District String 地址中的区级行政区域名称
City String 地址中的市级行政区域名称
MetroArea String 地址中的多市级行政区域名称，指由大城市和周围的小城市组成的城市区域
Subregion String 地址中的子区域级行政区域名称，是 Region 的子集
Region String 地址中的地区级行政区域的名称，是一个国家或地区的子集
RegionAbbr String 区域的缩写名称。
例如：对于 California，该值为 CA
Territory String 地址中的地区级行政区域的名称，是 country 的子集
Zone String 地址中的地区名称，与国家同级
Postal String 地址中的邮政编码
PostalExt String 地址中的邮政编码分号
例如：对于 92373-8110，该值为 8110
Country String 地址中国家的 3 字符代码

国家与代码列表详见：https://doc.arcgis.com/zh-cn/arcgis-online/reference/geocode-coverage
CountryName String 地址中国家的完整名称
LangCode String 地址使用的语言，由 3 字符组成的语言代码

语言与代码列表详见：https://www.loc.gov/languages/language_code.html
Distance double 地址所在地点到指定位置的距离。仅当请求参数种包含 location 字段时会进行计算，否则返回值为0
X double 地址的 X 坐标（4326坐标系下）
Y double 地址的 Y 坐标（4326坐标系下）
DisplayX double 地址的显示 X 坐标（4326坐标系下）。通常情况下与 X 参数值相同，对于 Subaddress、PointAddress，可能存在不同
DisplayY double 地址的显示 Y 坐标（4326坐标系下）。通常情况下与 Y 参数值相同，对于 Subaddress、PointAddress，可能存在不同
Xmin、Ymin、Xmax、Ymax double 4326坐标系下的坐标，用于表示地址所在区域的最小几何范围
ExInfo String 若查询的地址字符串中存在无法与任何地址匹配的字符值，在该字段中体现
StrucType String 地址所在地点的类型，仅当国家为美国且 Addr_type 为Subaddress、PointAddress 时返回该字段。可选值为 Residential 和 Commercial
StrucDet String 地址所在地点的细分类型，由 StrucType 决定，仅当国家为美国且 Addr_type 为 Subaddress、PointAddress 时返回该字段

可选值详见：https://developers.arcgis.com/rest/geocode/service-output/

响应示例

对 findAddressCandidates 资源：http://supermapiserver:8090/iserver/services/addressmatch-arcgisGeocode/arcgisrest/geocode/GeocodeServer/findAddressCandidates?Address=广东省&Address2=&Address3=&Neighborhood=&City=&Subregion=&Region=&Postal=&PostalExt=&CountryCode=&SingleLine=&outFields=&maxLocations=&matchOutOfRange=true&langCode=&locationType=&sourceCountry=&category=&location=&searchExtent=&outSR=&magicKey=&preferredLabelValues=&f=pjson 执行 GET 请求，查找地址为广东省的地点位置，返回 json 格式的资源表述如下：

{
    "candidates": [{
        "extent": null,
        "score": 100,
        "address": "广东省",
        "attributes": {},
        "location": {
            "x": 3.982640983587552E7,
            "y": 2597586.8380455966,
            "spatialReference": null
        }
    }],
    "spatialReference": null
}

POST 请求

跟 GET 请求结构类似。

HEAD 请求

返回跟 GET 请求一样的 HTTP 响应头，但是没有响应实体。可以在不必传输整个响应内容的情况下，获取包含在响应消息头中的元数据信息。元数据信息包括媒体类型，字符编码，压缩编码，实体内容长度等。

HEAD 请求可以用来判断 findAddressCandidates 资源是否存在，或者客户端是否有权限访问 findAddressCandidates 资源。通过对加.<format>的 URI 执行 HEAD 请求，还可以快速判断 findAddressCandidates 资源是否支持<format>格式的表述。

请参见