URI
<geocodeService_uri>/geocodeAddress[.<format>]
支持的方法
父资源
介绍
批量地址匹配。该资源支持在一个请求中对整个地址关键词列表进行地理编码,返回一个表示地理编码地址列表的资源,包括地址、位置、匹配分数等信息。可以查询如下类型的地址:
- 街道地址,如: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 的服务是否支持”列标注。
支持的方法:
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>格式的表述。
请参见
- geocodeService、findAddressCandidates、reverseGeocode、suggest
- 客户端构建 REST 请求
- 状态码列表及说明
- SuperMap iServer REST API 表述格式介绍