Description

Map services offer access to the contents of a map hosted on a server. Map services can expose different levels of capabilities. When a map service is hosted on ArcGIS Online or Portal for ArcGIS, it exposes a set of tiled images that are used by the client for rapid map navigation. When a map service is hosted on an ArcGIS for Server site, it exposes additional functionality, such as dynamic drawing, query, and search. With ArcGIS for Server, further web services may be available through the map service root URL that allow network analysis, vector feature editing, and so forth.

The REST API Map Service resource works only with the default data frame of your published map document. This resource provides basic information about the map, including the layers that it contains, whether or not the map is cached, its spatial reference, initial and full extents, map units, and copyright text. It also provides some metadata associated with the service, such as its service description, its author, and keywords. If the map is cached, additional information about its tiling scheme, such as the origin of the cached tiles, the levels of detail, and tile size, is included.

Map services do not expose editing capabilities. They provide read-only access to feature and attribute content.

Map services hosted by ArcGIS Online and Portal for ArcGIS

Map services hosted by ArcGIS Online or Portal for ArcGIS can only return tiles from the server's cache; they cannot draw images dynamically, nor do they allow query of the individual features behind the map. You can support queries and informational pop-up windows in your applications by using feature services in conjunction with your map services.

Accordingly, some of the resources, operations, and properties mentioned in this section of the documentation do not apply to map services hosted by ArcGIS Online or Portal for ArcGIS.

Map services hosted by ArcGIS for Server

Map services hosted by ArcGIS for Server support a larger set of operations:

Export map—Used to export a map image from a dynamic map service. The resulting map can be used for display and be in a different projection from the original data source. When generating a map image, map services are not able to change feature rendering for an existing layer, add a dynamic layer, or change the layer draw order.

Identify—Returns information about features in one or more layers based on where a user clicks on the map.

Find—Returns information about features in one or more fields in one or more layers based on a keyword.

Generate KML—Generates a KML document wrapped in a KMZ file. The document contains a network link to the KML service endpoint with specified properties and parameters. This operation is valid on services that have not been restricted by using a token service.

Query on a Layer/Table—Returns a subset of features in a layer or records in a table based on query criteria.

New at 10.4

GeoJSON is supported as an output format of the map service layer query operation.

The Query operation supports expressions in addition to field names for orderByFields and groupByFieldsForStatistics.

New at 10.3

Map Service will return resampling:true|false, indicating whether clients should resample tiles for areas where tiles are unavailable. This property is not enabled by default; you can add it using the ArcGIS Server Administrator Directory.

New at 10.2

Standardized SQL queries are the default way to specify a where clause or definition expression. The map service Layer and Dynamic Layer resources now report a property useStandardizedQueries to indicate the support for standardized queries.

Query operations on Layer and Dynamic Layer now support specifying a gdbVersion parameter in conjunction with the outStatistics parameter.

The Renderer object supports two new optional properties: rotationType that controls the origin and direction of rotation, and rotationExpression, which is a constant value or an expression that derives the angle of rotation based on the feature attribute value. When an attribute name is specified in rotationExpression, it is enclosed within square brackets, for example: [Rotation].

The Map Service resource lists two new properties: exportTilesAllowed, a Boolean flag that indicates whether clients can export cache tiles, and maxExportTilesCount that specifies the maximum number of tiles that can be exported to a cache dataset or a tile package.

The Map Service resource lists a new property supportedExtensions, a comma-separated list of extensions supported by the map service.

New at 10.1 SP1

Query operations on Layer and Dynamic Layer support a new parameter called returnDistinctValues that accepts a Boolean value. When true, query results will contain distinct values based on the fields specified in the outFields parameter.

Query operations on Layer and Dynamic Layer support the geometry parameter to be
used in conjunction with the outStatistics parameter.

The Legend resource returns the height and width of the legend symbol.

New at 10.1

The Map Service resource supports a new parameter, returnUpdates, that accepts a Boolean value. Pass this parameter to retrieve updated information from the map service.

The Map Service resource has new input parameters, option and outSR, to support viewing of a map service footprint in arcgis.com.

Support for dynamic layers has been added to map service. This allows per request modification of renderer, joins, geodatabase version, or layer order
for existing map service layers. If the map service has registered
workspaces, dynamic layers also allow per request addition of
layers based on the data from the registered workspaces. Use
the supportsDynamicLayers property on the Map Service
resource to determine if the service supports dynamic layers.

The Map Service resource contains maxRecordCount, maxImageHeight, and maxImageWidth properties. maxRecordCount represents the maximum number of records that can be returned by query, find, and identify operations. maxImageHeight and maxImageWidth represent the maximum image height and width, in pixels, the map service will export.

The Map Service resource includes the tileServers property, which advertises multiple subdomains on a map service endpoint. This allows the tile requests to be split across the tile servers specified in this property, for example, http://maps1.myserver.com and http://maps2.myserver.com.

The Map Service resource includes supportedQueryFormats. This value indicates the supported output formats for a query operation.

The Map Service resource includes these new properties under timeInfo: timeRelation, defaultTimeInterval, defaultTimeIntervalUnits, defaultTimeWindow, and hasLiveData.

timeRelation indicates how the start and end time of the time slider extent are processed: esriTimeRelationOverlaps when start and end time of the time slider are included, esriTimeRelationOverlapsStartWithinEnd when start time is included and end time is excluded, and esriTimeRelationAfterStartOverlapsEnd when start time is excluded and end time is included.

defaultTimeInterval and defaultTimeIntervalUnits indicate the initial time slider step size. The allowed units include the following:

esriTimeUnitsCenturies

esriTimeUnitsDays

esriTimeUnitsDecades

esriTimeUnitsHours

esriTimeUnitsMilliseconds

esriTimeUnitsMinutes

esriTimeUnitsMonths

esriTimeUnitsSeconds

esriTimeUnitsWeeks

esriTimeUnitsYears

esriTimeUnitsUnknown

defaultTimeWindow indicates the time slider window size.

hasLiveData returns a Boolean value. If true, export and identify operations will default the value for the time parameter to be [<current server time - defaultTimeWindow>, <current server time>].

The Map Service resource includes minScale and maxScale properties. For a cached map service, these values represent the minimum and maximum map scales at which the administrator has
allowed the tiles to be built. In the case of a dynamic map service,
these values are calculated as a union of minimum and maximum
scales of all the map layers.

The Map Service resource includes hasVersionedData if any of the map layers data is versioned. When true, map service operations accept the gdbVersion parameter to switch the geodatabase version.

New at 10.0 SP1

The Map Service resource includes scale information (minScale and maxScale) for layers.

New at 10.0

At 10 and later, in addition to layers, map services can also publish
stand-alone tables. The response includes a new tables
property that contains some basic information about tables. The
child layer resource is now a Layer/Table resource in that it represents either a layer or
a table depending on the ID that was specified.

Support for time-aware map services was added at 10. If the map supports
querying and exporting maps based on time, the response will include
a timeInfo property that includes information such as
the map's time extent and the map's native time reference. However,
the REST API always encodes time in UTC (milliseconds
from epoch).

Resource hierarchy

Request parameters

Parameter

Details

f

Description: The response format. The default response format is html.

Values: html | json | kmz | lyr | nmf | jsapi | ve | gmaps

returnUpdates

This parameter was added at 10.1.

Description: If value is true, returns updated time extent. If the service is not time aware, returns an empty response.

Values: true | false

option

This parameter was added at 10.1.

Description: If option is footprints, the footprint of the map service is returned as a feature collection. This feature collection can be viewed in an arcgis.com map. This is supported when f=json only.

Values: footprints

outSR

This parameter was added at 10.1.

Description: The spatial reference of the geometry returned in footprints. This parameter is supported only when option=footprints is specified.

The spatial reference should be specified as a well-known ID.

If outSR is not specified, the geometry is returned in GCS_WGS_1984.

Example usage

Example: URL for the "ESRI_StateCityHighway_USA" map service on
sampleserver1.