map

URI

1.<maps_uri>/{mapName}[.<format>]

2.<maps_uri>/{mapIndex}[.<format>]

介绍

map 资源是访问在线地图服务的入口，通过 map 资源，可以获得该地图的基本状态信息，如中心点，比例尺，地图范围，图片大小，地图单位，包含的图层，包含的图片等等，并可以创建一个临时的图层集。

对 map 资源执行 GET 请求时，可以获取 javascript 表述，即针对该地图资源的 JavaScript 客户端应用，这些应用实现了简单的地图功能。对 map 资源执行 GET 请求时，还可以获取 KML 表述，如 http://supermapiserver:8090/iserver/services/map-world/rest/maps/World%20Map.kml， 在 GoogleEarth 客户端可以直接打开此 kml URI 进行显示。

关于本资源的使用方法，可参考开发指南：获取地图参数。

支持的表述格式：RJSON、JSON、FASTJSON、JSONP、HTML、XML、KML、JavaScript、Leaflet、openlayers3 (with MVT)、MapboxGL、for Classic、WebGL3D。

资源层次

resources.htm maps.htm map.htm

父资源

maps

子资源

image、entireImage、overview、trackingLayer、layers、tempLayersSet、distance、area、chartFeatureInfoSpecs、queryResults、tileImage、tileFeature、tilesets、utfGrid、highlightImage、clearCache、symbol、prjCoordSys、zxyTileImage、tileImages

支持的方法

HTTP 请求方法

对如下 URI 执行 HTTP 请求，以 rjson 输出格式为例加以说明，其中，supermapiserver 是服务器名，“世界地图” 是地图名（{mapName}）。

http://supermapiserver:8090/iserver/services/map-world/rest/maps/世界地图.rjson

GET 请求

获取地图当前状态的基本信息，包括该地图的中心点，比例尺，地图显示范围，出图图片大小，地图单位，距离度量单位等。其中，地图进行动态投影时，地图显示范围（viewBounds）是指原地图显示范围在目标投影下所转换成的多边形的外接矩形，而其他地图状态参数也会随之变化，如中心点和比例尺。

URI 参数

map 资源对应的 URI 有两种，优先以 mapName 匹配：

第一种：<maps_uri>/{mapName}[.<format>]，地图资源由具体的地图名称{mapName}来标识，地图名称可以是中文；

第二种：<maps_uri>/{mapIndex}[.<format>]，地图资源由具体地图的索引号{mapIndex}来标识，从0开始编号，依次为0、1、2、3等。

请求参数

URI 中，在“?”后面支持传递的参数如下表所示：

名称 类型 含义
_cache boolean 【可选参数】
是否使用缓存，默认为 true。如果为 false，则关闭所有缓存。
prjCoordSys

PrjCoordSys

 【可选参数】
用于指定请求地图的坐标参考系统，服务端会按照指定的坐标参考系统返回相应的地图状态信息。
如果此参数为空，则默认返回地图原坐标参考系统下的状态信息；如果指定的坐标参考系统与地图原坐标参考系统不同，服务端会对地图进行动态投影，然后返回动态投影后的地图状态信息。

参数使用时，需按照PrjCoordSys中的字段结构来构建，同时也支持通过只传递 epsgCode 的方式传入坐标参考系，如：

prjCoordSys={"epsgCode":3857}。
queryResultID

String

 【可选参数】【JavaScript 表述中支持】
用于展示地图查询结果。
地图查询结果（queryResult）可以叠加在地图上，借助 map 资源的 JavaScript 表述进行显示，如：queryResultID=eiicoeik_889fa578956b4c90bb8aa841e5abfb7d。

动态投影

SuperMap iServer 的 REST Map 服务支持发布各坐标参考系下的地图，且支持对 REST Map 服务中的地图进行动态投影（无投影的平面坐标系暂不支持）。

REST 地图服务动态投影的使用方法如下：

  1. 获取动态投影后的地图状态：通过 map 资源的 GET 操作获取当前地图的状态，包括当前地图支持的目标投影坐标系列表，然后通过在 GET 请求中传递 prjCoordSys 参数，获取动态投影后的地图信息，如 prjCoordSys={"epsgCode":3857}。
  2. 获取动态投影后的地图图片：根据需要对出图资源，如image、entireImage或tileImage资源执行 GET 请求并传递 prjCoordSys 参数，即可获取动态投影后的地图图片。

需要注意的是，地图进行动态投影后，其中坐标单位、中心点，比例尺，地图范围等状态信息与投影前会有不同，获取图片时，请注意设置相关参数。对 map 资源进行动态投影时，是以地图在目标投影下的 viewBounds 为范围来计算其他地图状态参数的，如中心点和比例尺，而新 viewBounds 是原 viewBounds 投影变换后对应多边形的外接矩形。此外，map 资源的当前坐标系状态会转递给子资源，如image、entireImage、tileImage，即这些子资源的默认坐标系与 map 资源的当前坐标系一致。

关于 SuperMap iServer 目前支持的 EPSG Code，请参考：。

响应结构

对地图资源执行 GET 请求，返回的资源表述的结构如下（资源表述在响应消息的实体主体里）：  

字段 类型 说明
name String 当前地图的名称。
center Point2D 地图显示的中心点。
scale double 地图的显示比例尺，详见比例尺的定义。
maxScale double 地图的最大显示比例尺。该值为0时，表示没有比例尺显示限制。
minScale double 地图的最小显示比例尺。该值为0时，表示没有比例尺显示限制。
bounds Rectangle2D 地图的全幅地理范围。
viewBounds Rectangle2D 地图窗口显示区域的范围，是一个矩形框。
如果对地图设置了动态投影，则此参数表示原 viewBounds 在目标投影下所转换成的多边形的外接矩形。
viewer Rectangle 用户显示视窗，即产生的图片的大小。
prjCoordSys PrjCoordSys 返回当前地图的坐标参考系统。
dynamicPrjCoordSyses PrjCoordSys 返回当前地图所支持的目标投影坐标系列表。

如果当前坐标参考系统支持动态投影为所有类型的坐标参考系统，则 epsgCode 为0，type 为 PCS_ALL。
customParams String 自定义参数。
可以是任何形式组织的字符串。用户可以通过该属性传入自定义的参数。
userToken UserInfo 用户信息。
clipRegion Geometry 地图显示裁剪的区域。
clipRegionEnabled boolean 地图显示裁剪的区域是否有效。
customEntireBounds Rectangle2D 自定义的地图全幅显示范围。
customEntireBoundsEnabled boolean 自定义的地图全幅显示范围是否有效。
angle double 当前地图的旋转角度。
antialias boolean 是否反走样地图。
backgroundStyle Style 地图的背景风格。
colorMode MapColorMode 地图的颜色模式。
coordUnit Unit 地图的坐标单位。
distanceUnit Unit 地图的距离量度单位。
description String 当前地图的描述信息。
dynamicProjection boolean 是否允许地图动态投影显示。
markerAngleFixed boolean 指定点状符号的角度是否固定。
maxVisibleTextSize double 文本的最大可见尺寸，单位为像素。
maxVisibleVertex int

最大几何对象可见节点数。

如果几何对象的节点数超过指定的个数，则该几何对象不显示。
minVisibleTextSize double 文本的最小可见尺寸，单位为像素。
overlapDisplayed boolean 重叠时是否显示对象。
paintBackground boolean 是否绘制地图背景。
textAngleFixed boolean 文本角度是否固定。
textOrientationFixed boolean 文本朝向是否固定。
overlapDisplayedOptions OverlapDisplayedOptions 避免地图对象压盖显示的过滤选项，当 overlapDisplayed 为 false 时有效，用来增强对地图对象压盖时的处理。
visibleScales double[] 地图的可见比例尺数组。
dpi double 分辨率，单位为每英寸点数。
visibleScalesEnabled boolean 是否使用固定比例尺来显示地图。
customEntireBoundsEnabled boolean 自定义的地图全幅显示范围是否有效。
cacheEnabled boolean 是否启用缓存。
mapCapabilities MapCapability 地图支持的能力，如支持缓存、距离量算、SQL查询等，全部支持的能力请参见：MapCapability
autoAvoidEffectEnabled boolean 是否启用自动避让效果。

示例

对 World 地图资源：http://supermapiserver:8090/iserver/services/map-world/rest/maps/世界地图.rjson 执行 GET 请求，返回 rjson 格式的资源表述如下：

{

    "viewBounds": {

        "top": 62.74347709538654,

        "left": -98.83707939483622,

        "bottom": -68.1095235243148,

        "leftBottom": {

            "x": -98.83707939483622,

            "y": -68.1095235243148

        },

        "right": 32.01592122486511,

        "rightTop": {

            "x": 32.01592122486511,

            "y": 62.74347709538654

        }

    },

    "viewer": {

        "leftTop": {

            "x": 0,

            "y": 0

        },

        "top": 0,

        "left": 0,

        "bottom": 256,

        "rightBottom": {

            "x": 256,

            "y": 256

        },

        "width": 256,

        "right": 256,

        "height": 256

    },

    "distanceUnit": "METER",

    "minVisibleTextSize": 0.3,

    "coordUnit": "DEGREE",

    "scale": 4.649942170950459E-9,

    "description": "",

    "paintBackground": true,

    "maxVisibleTextSize": 1000,

    "maxVisibleVertex": 36000,

    "clipRegionEnabled": false,

    "antialias": true,

    "textOrientationFixed": false,

    "angle": 0,

    "prjCoordSys": {

        "distanceUnit": "METER",

        "projectionParam": null,

        "epsgCode": 4326,

        "coordUnit": "DEGREE",

        "name": "GCS_WGS_1984",

        "projection": null,

        "type": "PCS_EARTH_LONGITUDE_LATITUDE",

        "coordSystem": {

            "datum": {

                "name": "D_WGS_1984",

                "type": "DATUM_WGS_1984",

                "spheroid": {

                    "flatten": 0.0033528106647474805,

                    "name": "WGS_1984",

                    "axis": 6378137,

                    "type": "SPHEROID_WGS_1984"

                }

            },

            "unit": "DEGREE",

            "spatialRefType": "SPATIALREF_EARTH_LONGITUDE_LATITUDE",

            "name": "GCS_WGS_1984",

            "type": "GCS_WGS_1984",

            "primeMeridian": {

                "longitudeValue": 0,

                "name": "Greenwich",

                "type": "PRIMEMERIDIAN_GREENWICH"

            }

        }

    },

    "mapCapabilities": [

        "MapImage",

        "UTFGrid",

        "VectorTile",

        "Area",

        "CharFeatureInfoSpecs",

        "Cache",

        "Distance",

        "HighlightImage",

        "BoundsQuery",

        "ChartAttributeQuery",

        "DistanceQuery",

        "FindNearest",

        "SpatialQuery",

        "SqlQuery",

        "Symbol",

        "TempLayer",

        "TrackingLayer",

        "MVTCapabilities",

        "MBStyle"

    ],

    "minScale": 0,

    "markerAngleFixed": false,

    "overlapDisplayedOptions": {

        "allowPointWithTextDisplay": true,

        "horizontalOverlappedSpaceSize": 0,

        "allowPointOverlap": true,

        "allowThemeGraduatedSymbolOverlap": false,

        "verticalOverlappedSpaceSize": 0,

        "allowTextOverlap": false,

        "allowThemeGraphOverlap": false,

        "allowTextAndPointOverlap": true

    },

    "visibleScales": [

        1.6901635716026555E-9,

        3.3803271432053056E-9,

        6.760654286410611E-9,

        1.3521308572821222E-8,

        2.7042617145642408E-8,

        5.4085234291284816E-8,

        1.0817046858256963E-7,

        2.1634093716513927E-7,

        4.3268187433027853E-7,

        8.653637486605571E-7

    ],

    "dpi": 96,

    "visibleScalesEnabled": false,

    "customEntireBoundsEnabled": false,

    "clipRegion": {

        "center": null,

        "parts": null,

        "style": null,

        "prjCoordSys": null,

        "id": 0,

        "type": "REGION",

        "partTopo": null,

        "points": null

    },

    "maxScale": 1.0E12,

    "customParams": "",

    "center": {

        "x": -33.41057908498556,

        "y": -2.6830232144641286

    },

    "dynamicPrjCoordSyses": [{

        "distanceUnit": null,

        "projectionParam": null,

        "epsgCode": 0,

        "coordUnit": null,

        "name": null,

        "projection": null,

        "type": "PCS_ALL",

        "coordSystem": null

    }],

    "colorMode": "DEFAULT",

    "textAngleFixed": false,

    "overlapDisplayed": false,

    "userToken": {"userID": ""},

    "cacheEnabled": true,

    "dynamicProjection": false,

    "autoAvoidEffectEnabled": true,

    "customEntireBounds": null,

    "name": "世界地图",

    "bounds": {

        "top": 90,

        "left": -180,

        "bottom": -90,

        "leftBottom": {

            "x": -180,

            "y": -90

        },

        "right": 180,

        "rightTop": {

            "x": 180,

            "y": 90

        }

    },

    "backgroundStyle": {

        "fillGradientOffsetRatioX": 0,

        "markerSize": 2.4,

        "fillForeColor": {

            "red": 255,

            "green": 255,

            "blue": 255,

            "alpha": 255

        },

        "fillGradientOffsetRatioY": 0,

        "markerWidth": 0,

        "markerAngle": 0,

        "fillSymbolID": 0,

        "lineColor": {

            "red": 0,

            "green": 0,

            "blue": 0,

            "alpha": 255

        },

        "markerSymbolID": 0,

        "lineWidth": 0.1,

        "markerHeight": 0,

        "fillOpaqueRate": 100,

        "fillBackOpaque": true,

        "fillBackColor": {

            "red": 255,

            "green": 255,

            "blue": 255,

            "alpha": 255

        },

        "fillGradientMode": "NONE",

        "lineSymbolID": 0,

        "fillGradientAngle": 0

    }

}

如果希望获取动态投影到 WebMercator 的地图，则需要设置 prjCoordSys={"epsgCode":3857}，即对 World 地图资源：http://supermapiserver:8090/iserver/services/map-world/rest/maps/世界地图.rjson?prjCoordSys={"epsgCode":3857} 执行 GET 请求，返回 rjson 格式的资源表述如下：

{

    "viewBounds": {

        "top": 9037625.447473992,

        "left": -1.3477871869291998E7,

        "bottom": -1.0479620989412028E7,

        "leftBottom": {

            "x": -1.3477871869291998E7,

            "y": -1.0479620989412028E7

        },

        "right": 6039374.567594023,

        "rightTop": {

            "x": 6039374.567594023,

            "y": 9037625.447473992

        }

    },

    "viewer": {

        "leftTop": {

            "x": 0,

            "y": 0

        },

        "top": 0,

        "left": 0,

        "bottom": 256,

        "rightBottom": {

            "x": 256,

            "y": 256

        },

        "width": 256,

        "right": 256,

        "height": 256

    },

    "distanceUnit": "METER",

    "minVisibleTextSize": 0.3,

    "coordUnit": "METER",

    "scale": 3.4704349075248028E-9,

    "description": "",

    "paintBackground": true,

    "maxVisibleTextSize": 1000,

    "maxVisibleVertex": 36000,

    "clipRegionEnabled": false,

    "antialias": true,

    "textOrientationFixed": false,

    "angle": 0,

    "prjCoordSys": {

        "distanceUnit": "METER",

        "projectionParam": {

            "centralParallel": 0,

            "firstPointLongitude": 0,

            "rectifiedAngle": 0,

            "scaleFactor": 1,

            "falseNorthing": 0,

            "centralMeridian": 0,

            "secondStandardParallel": 0,

            "secondPointLongitude": 0,

            "azimuth": 0,

            "falseEasting": 0,

            "firstStandardParallel": 0,

            "projectionPlaneOriginHeight": 0

        },

        "epsgCode": 3857,

        "coordUnit": "METER",

        "name": "User Define",

        "projection": {

            "name": "SPHERE_MERCATOR",

            "type": "PRJ_SPHERE_MERCATOR"

        },

        "type": "PCS_WGS_1984_WEB_MERCATOR",

        "coordSystem": {

            "datum": {

                "name": "D_WGS_1984",

                "type": "DATUM_WGS_1984",

                "spheroid": {

                    "flatten": 0.0033528106647474805,

                    "name": "WGS_1984",

                    "axis": 6378137,

                    "type": "SPHEROID_WGS_1984"

                }

            },

            "unit": "DEGREE",

            "spatialRefType": "SPATIALREF_EARTH_LONGITUDE_LATITUDE",

            "name": "GCS_WGS_1984",

            "type": "GCS_WGS_1984",

            "primeMeridian": {

                "longitudeValue": 0,

                "name": "Greenwich",

                "type": "PRIMEMERIDIAN_GREENWICH"

            }

        }

    },

    "mapCapabilities": [

        "MapImage",

        "UTFGrid",

        "VectorTile",

        "Area",

        "CharFeatureInfoSpecs",

        "Cache",

        "Distance",

        "HighlightImage",

        "BoundsQuery",

        "ChartAttributeQuery",

        "DistanceQuery",

        "FindNearest",

        "SpatialQuery",

        "SqlQuery",

        "Symbol",

        "TempLayer",

        "TrackingLayer",

        "MVTCapabilities",

        "MBStyle"

    ],

    "minScale": 0,

    "markerAngleFixed": false,

    "overlapDisplayedOptions": {

        "allowPointWithTextDisplay": true,

        "horizontalOverlappedSpaceSize": 0,

        "allowPointOverlap": true,

        "allowThemeGraduatedSymbolOverlap": false,

        "verticalOverlappedSpaceSize": 0,

        "allowTextOverlap": false,

        "allowThemeGraphOverlap": false,

        "allowTextAndPointOverlap": true

    },

    "visibleScales": [

        1.6901635716026555E-9,

        3.3803271432053056E-9,

        6.760654286410611E-9,

        1.3521308572821222E-8,

        2.7042617145642408E-8,

        5.4085234291284816E-8,

        1.0817046858256963E-7,

        2.1634093716513927E-7,

        4.3268187433027853E-7,

        8.653637486605571E-7

    ],

    "dpi": 96,

    "visibleScalesEnabled": false,

    "customEntireBoundsEnabled": false,

    "clipRegion": {

        "center": null,

        "parts": null,

        "style": null,

        "prjCoordSys": null,

        "id": 0,

        "type": "REGION",

        "partTopo": null,

        "points": null

    },

    "maxScale": 1.0E12,

    "customParams": "",

    "center": {

        "x": -3719248.6508489875,

        "y": -720997.7709690183

    },

    "dynamicPrjCoordSyses": [{

        "distanceUnit": null,

        "projectionParam": null,

        "epsgCode": 0,

        "coordUnit": null,

        "name": null,

        "projection": null,

        "type": "PCS_ALL",

        "coordSystem": null

    }],

    "colorMode": "DEFAULT",

    "textAngleFixed": false,

    "overlapDisplayed": false,

    "userToken": {"userID": ""},

    "cacheEnabled": false,

    "dynamicProjection": true,

    "autoAvoidEffectEnabled": true,

    "customEntireBounds": null,

    "name": "世界地图",

    "bounds": {

        "top": 2.58194985135433E7,

        "left": -2.0037508342789244E7,

        "bottom": -2.5819498513543323E7,

        "leftBottom": {

            "x": -2.0037508342789244E7,

            "y": -2.5819498513543323E7

        },

        "right": 2.0037508342789244E7,

        "rightTop": {

            "x": 2.0037508342789244E7,

            "y": 2.58194985135433E7

        }

    },

    "backgroundStyle": {

        "fillGradientOffsetRatioX": 0,

        "markerSize": 2.4,

        "fillForeColor": {

            "red": 255,

            "green": 255,

            "blue": 255,

            "alpha": 255

        },

        "fillGradientOffsetRatioY": 0,

        "markerWidth": 0,

        "markerAngle": 0,

        "fillSymbolID": 0,

        "lineColor": {

            "red": 0,

            "green": 0,

            "blue": 0,

            "alpha": 255

        },

        "markerSymbolID": 0,

        "lineWidth": 0.1,

        "markerHeight": 0,

        "fillOpaqueRate": 100,

        "fillBackOpaque": true,

        "fillBackColor": {

            "red": 255,

            "green": 255,

            "blue": 255,

            "alpha": 255

        },

        "fillGradientMode": "NONE",

        "lineSymbolID": 0,

        "fillGradientAngle": 0

    }

}

HEAD 请求

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

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

请参见