URI

<geocodeService_uri>/geocodeAddress[.<format>]

支持的方法

GETHEAD

父资源

geocodeService

介绍

批量地址匹配。该资源支持在一个请求中对整个地址关键词列表进行地理编码,返回一个表示地理编码地址列表的资源,包括地址、位置、匹配分数等信息。可以查询如下类型的地址:

  • 街道地址,如:380 New York St, Redlands, CA 92373
  • 行政地名,如城市、县、州、省或国家/地区名称,如:Seattle, Washington
  • 邮政编码,如:92591
  • 由名称表示的 POI,如:mount everest
  • 坐标,如:-117.123,32.7037

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

支持的方法:

  • GET:获取批量地址匹配结果。
  • HEAD:检查 geocodeAddress 资源是否存在,或权限是否可以访问 geocodeAddress 资源。

HTTP 请求方法

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

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

GET 请求

获取批量地址匹配结果。

请求参数

名称 类型 含义 转发10.2/10.9 ArcGIS Server的服务是否支持
f String 【必填参数】响应格式,支持 json
token String 访问服务所需的 token  
addresses String[] 【必填参数】地址记录集,每条地址均需含有唯一 OBJECTID 属性,以及服务支持的地址字段的值,有以下两种传参方式:

1、通过多行地址参数进行批量传参,每一个 address 是一个字符串,例如:address=Beetham Tower、address2=301 Deansgate 和 address3=Suite 4208
一般情况下,一个 address 代表地址中的一行
2、通过多个 singleLine 单行地址参数进行批量传参

以多行地址参数传参方式为例:
{"records":[{"attributes":{"address": "温馨布艺(龙珠路)"}}, {"attributes":{"address": "锦华窗帘装饰中心(龙珠路)"}}]}
由geocodeService响应中返回的addressFields字段名称、singleLineAddressField字段名称作为地址查询参数,不支持多行地址用法
sourceCountry String[] 用于限制返回结果的关联国家。可传入单个值或多个值,传入多个值时用逗号分隔。

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

请注意:如果 请求参数中同时包含 countryCode 和 sourceCountry ,并且值不同时,则优先使用 countryCode 的参数值。  
 
category String[] 用于设置过滤的地点或地址类型,从而在指定地址字段中进行匹配而不再返回匹配其他字段的结果。可传入单个或多个类别值,用逗号分隔。  
outFields String[] 响应体中 attributes 对象中返回的字段列表。可传入多个值,需用逗号分隔。默认情况下,响应中会返回所有字段。其他用法:

1、若传参为 none,则将只返回最小结果集,包括:spatialReference、locations(完整地址和坐标)、score 和 attributes(只含 ResultID);
2、若传参为具体值(需与 geocodeService 资源响应体中 candidateFields 的 name 一致),则返回对应字段和ResultID;
3、若请求中不传该参数,或传为空/通配符“*”,则返回所有字段
outSR String 结果的坐标系。如果未指定,则坐标系与服务的坐标系相同
searchExtent ArcGISEnvelope 一组边界框坐标,用于指定特定搜索区域,如果搜索区域的坐标系与服务的坐标系不同,则必需设置坐标系。例如:

searchExtent= { "xmin" : -109.55, "ymin" : 25.76, "xmax" : -86.39, "ymax" : 49.94}
 
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 返回
 

响应结构

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

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

1、address:完整匹配地址;
2、location:匹配位置的点坐标,包括 x、y 和 spatialReference 属性;
3、score:匹配分数;
4、attributes:匹配地址的属性信息,包含的字段如下表所示。

附表 attributes 对象参数结构

字段 类型 说明
ResultID String 返回的每组地址信息都包含一个 ResultID,该值等于请求时每条地址中的唯一 OBJECTID 值,从而将响应结果与查询条件进行映射
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
CntryName String 地址中国家的完整名称
LangCode String 地址使用的语言,由 3 字符组成的语言代码

语言与代码列表详见:https://www.loc.gov/languages/language_code.html
X double 地址的 X 坐标(4326坐标系下)
Y double 地址的 Y 坐标(4326坐标系下)
Distance double 地址所在地点到指定位置的距离。仅当请求时传入 location 字段时会进行计算,否则返回值为0
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/

响应示例

对 geocodeAddress 资源:http://supermapiserver:8090/iserver/services/addressmatch-arcgisGeocode/arcgisrest/geocode/GeocodeServer/geocodeAddresses?addresses=%7B"records"%3A+%5B%7B"attributes"%3A+%7B"Address"%3A+"广东省"%7D%7D%2C%7B"attributes"%3A+%7B"Address"%3A+"江西省"%7D%7D%5D%7D&category=&sourceCountry=&matchOutOfRange=true&langCode=&locationType=&searchExtent=&outSR=&outFields=&preferredLabelValues=&f=json 执行 GET 请求,查找地址为广东省和江西省的地点位置,返回的 pjson 格式的表述如下:

HEAD 请求

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

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

请参见