Map services
Map services offer access to map and attribute content. Map services can either be cached or dynamic. A map service that fulfills requests with pre-created tiles from a cache instead of dynamically rendering part of the map is called a cached map service. A dynamic map service requires the server to render the map each time a request comes in. Map services using a tile cache can significantly improve performance while delivering maps, while dynamic map services offer more flexibility.
Map services offer the following capabilities:
- Generate map images for a specified geographic area
- Change the description of the map
- Control the output map image
- Get map legend information
- Query map features using attributes or spatial filters
- Get information regarding the cache
- Get a scale bar
WSDL syntax
http://<host name>:<port number>/<arcgis instance>/services/<ServiceName>/MapServer?wsdl
Working with map services
Getting information about the map and its layers
To access information about a map and its layers use GetServerInfo which returns MapServerInfo with an array of MapLayerInfo objects. MapServerInfo contains read-only information describing the default state of a map service, such as the name of the map, the background color or the spatial extent of the map. Read-only layer properties, such as the layer's name, the layer's attributes and whether or not the layer has labels associated with it, can be retrieved from the MapServerInfo.MapLayerInfos.
If you wish to make changes to the map or to map layers you will need to use MapDescription or LayerDescription. Use MapDescription to access map settings that can be changed such as geographic extent and spatial reference. This object provides access to information on individual layers within the map. LayerDescription provides the ability to change the visibility of a layer, to toggle the visibility of existing labels belonging to the layer and to assign an expression in order to display a specified subset of features.
Layer symbol and label
If you wish to retrieve information about how features on a layer are symbolized or labeled by the author, you will need to use QueryDefaultLayerDrawingDescriptions function. This property returns information on symbols and labels only for feature layers.
GenerateDataClasses function also helps to create renderer without downloading the entire dataset and processing them on the client application.
Exporting a map image
To export a map image from a dynamic map service use ExportMapImage. An ImageDescription contains an mageType and an ImageDisplay. Specifying the image format, such as JPG or PNG, is done using ImageType. Use ImageDisplay to specify the height and width of the image. You can also specify a transparent color using ImageDisplay. The server will restrict the maximum size an image can be. Use GetServiceConfigurationInfo to view the maximum height and width. This method contains a set of name-value pairs for properties set for the MapServer Service Configuration Restrictions.
dynamicLayers
When a mapservice has dynamicLayers enabled, it allows the following capabilities:
- reordering layers
- modifying layer symbol
- adding a new layer from a registered workspace
You can check SupportsDynamicLayers to find out whether a mapservice is dynamicLayers enabled. See help on ExportMapImage method for more information.
It is important to know that all changes made to the MapServer object are temporary. A temporary change would include changes to the MapDescription or LayerDescription. For example, you might change the geographic extent of a map (MapArea), change the visibility (Visible) or renderer (DrawingDescription) of a layer or even add a new layer on-the-fly. These changes are temporary and valid for the duration of the call (stateless). Once the call has ended the MapServer returns to it's default state and does not remember the changes made by the previous call.
Please note that all query functions e.g. QueryData(), Identify(), Find() etc. honors dynamically added layer and order of elements in LayerDescriptions array.
Information about legend elements
You can retrieve legend elements including the symbol image, labels, descriptions and headings. A common use would be to populate a table of contents. To retrieve legend information, use GetLegendInfo and MapServerLegendInfo to retrieve specific information for a particular layer.
Support time aware data
MapServer recognizes layers or tables that are time aware and publicize time capabilities as a part of MapLayerInfo or StandaloneTableInfo. MapServer also allows clients to request for image for a particular time or a span of time as well as query features that meet specific criteria and/or available at the query time.
In MapServer SOAP API, time can be represented either as TimeInstant or TimeExtent. The first represents a specific point of time while the second refers to a span of time that has start time and end time. MapServer supports all well known time zones as well as custom time zones too as TimeReference object.
MapServer time representation is based on XML schema which contains date, time (with milliseconds) and time zone offset. The value can be expressed as "yyyy-mm-ddThh:mm:ss.msZzzzzz" where T is the delimiter between date and time. The time zone is Z which means UTC or "zzzzz" which represents ±hh:mm relation to UTC. The value can contain date only portion of the date time or can be expressed as entire date-time.
All MapServer objects or functions that are time aware can be broadly grouped into 3 groups:
- Objects that advertises time capabilities - MapServer advertizes time capabilities as a part of MapLayerInfo or StandaloneTableInfo. These objects contain information such as whether the layer or table is time aware, field(s) that store time data etc.
- Objects takes time related inputs - MapDescription, LayerDescription, StandaloneTableDescription and TimeQueryFilter objects are the ones that get modified by clients and are used as inputs to either produce map image, or query features or rows. The default MapDescription also contains the default TimeReference and TimeValue for the map service which refers to the time value stored in the source map document at the time of publication.
- Time aware functions -ExportMapImage function honors time value that is passed in as a part of MapDescription and draws features for the requested time on the output image. Find, Identify and QueryData functions are also time aware and search features or rows that live with the time value chosen by a user.
Standalone table
Standalone table is a collection of fields-values but does not contain geometry field. The data source can be varied from a simple comma delimited text file to a table registered in an enterprise, workgroup, or desktop geodatabase geodatabase.
To get a list of standalone table available in the map service, use MapServerInfo.StandaloneTableInfos. To perform query operations on a table, QueryData, QueryRowIDs or QueryRowCount functions can be used.
Supported types of table |
|---|
|
Table registered with geodatabase (ArcSDE and File Geodatabase) |
|
dBase |
|
OLE DB |
|
Text files |
Querying the map
Map services offer a number of methods to perform query operations on the map. These include: Find, Identify, QueryHyperlinks, QueryFeatureCount, QueryFeatureData, QueryFeatureIDs, QueryData, QueryRowIDs, QueryRowCount and QueryRelatedRecords.
While QueryFeatureCount, QueryFeatureData and QueryFeatureIDs functions only work with layers, QueryData, QueryRowIDs, QueryRowCount and QueryRelatedRecords functions works with both layers and standalone tables.
Find returns an array of MapServerFindResult objects based on a search string. Use these objects to access properties of found features, such as the, the found value, the layer ID, the field name, the geometry of the found feature and a set of name-value pairs for the found features's field names and values.
QueryData, QueryRowIDs, QueryRowCount and QueryRelatedRecords can be used to query standalone tables and to find related rows. The new query functions can be used to query both a feature layer and standalone table.
Identify returns an array of MapServerIdentifyResult objects based on search shape. Use these objects to access properties of identified features. These include: layer ID, name, a set of name-value pairs for the field names and values of the identified object, and the geometry of the identified.
QueryFeatureCount and QueryRowCount both return the number of features that match a query. The difference between the two operations is QueryFeatureCount requires a LayerID as one of the parameters, while QueryFeatureCount2 requires a MapTableDescription instead. By passing in this object you can query against a specific sub set of the layer by applying a definition expression.
QueryFeatureID and QueryRowIDs respectively return a FIDSet (contains a set of feature IDs) or an array of feature IDs. IDs in the FIDSet are always sorted in ascending order. The result comes back from QueryRowIDs honors the sorting requested by the client for supported data sources. Another difference between the two operations is QueryFeatureIDs requires a LayerID as one of the parameters, while QueryRowIDs and QueryFeatureCount2 require a MapTableDescription instead. By passing in this object you can query against a specific sub set of the layer by applying a definition expression.
QueryFeatureData and QueryData differ not only in the required parameters, but also in what is returned and that the later one supports standalone table as well. QueryFeatureData returns a RecordSet base on a specific query and includes a LayerID in the method parameters. QueryData returns a QueryResult. This object includes the URL of the generated query result in the requested format. The result format can be specified by using QueryResultOptions. The query result can be formatted into a RecordSet or KMZ format (either as a URL to the KMZ file or a MIME object). Another property includes GeoTransformation. This is used to specify any needed geographic transformation on the results.
The server will restrict the maximum number of records that can be sent. Use GetServiceConfigurationInfo the maximum records that can be returned in a query for this particular map service. This method returns a set of name-value pairs for properties set for the MapServer service configuration restrictions. The maximum records count restriction does not affect QueryFeatureCount, QueryFeatureIds, QueryFeatureCount2, QueryFeatureIds2, QueryRowIDs or QueryRowCount.
Query related rows
MapServer provides two methods to find related rows: Identify and QueryRelatedRecords.
When a feature is identified, MapServer returns related rows from all relationship for that feature regardless of whether the related table/layer is added to the source map document or not. Users don't need to pass in any relationship information.
In contrast to that, QueryRelatedRecords function query only related table/layer that are added to the source map and a user needs to specify which relationship will be queried. The function requires one or more source ObjectID(s) and a relationship ID. It's a two step process: (1) find a list of features/rows from a layer/table that meets a criterion (QueryFilter or SpatialFilter) and (2) pass ObjectID(s) from that list and a relationship ID to QueryRelatedRecords to retrieve related rows/features for each ObjectID(s) passed in.
As an example, Layer A is related to Table B and Table C. When the MapService is published the source map document only contains Layer A and Table B, therefore MapService will only publicize the relationship between Layer A and Table B (an array of RelateInfo objects is available from MapLayerInfo or StandaloneTableInfo which can be obtained from MapServerInfo). QueryRelatedRecords cannot be used find related records from Table C (because Table C is not added to the source map document), while Identify will return related records from both Table B and Table C.
Related rows from Identify versus from QueryRelatedRecords:
|
QueryRelatedRecords |
Identify |
|---|---|
|
Related rows/features both source and destination table/layer of the relationship can be queried. |
Related records (from the relationship-source table/layer) of rows from destination table/layer cannot be queried. |
|
Client can request to include or exclude geometry in the related rows or ask to generalize or densify geometry. |
Related rows do not have geometry. |
|
Author decides which relationship will be available to the map service (need to add both source and destination layer/table in order for MapServer to publicize any relationship). |
Can't return related records from more than 1 level of relationship. |
|
Related rows from only one relationship can be obtained from one server request. |
Related rows from all relationships are packaged into an identify result. |
|
Both spatial and query filter can be used to get a list of features/rows from a layer/table and then find all related rows. |
Only takes geometry as an input to find features on a layer and get all related rows. |
Join versus Relate
Data comes from a variety of sources. Often, the data you want to display on your map is not directly stored with your geographic data. For instance, you might obtain data from other departments in your organization, purchase commercially available data, or download data from the Internet. If this information is stored in a table, such as a dBASE, INFO, or geodatabase table, you can associate it with your geographic features and display the data on your map.
There are two ways data can be linked: joins and relates. When you join two tables, you append the attributes from one onto the other based on a field common to both. Relating tables defines a relationship between two tables&emdashalso based on a common field&emdashbut doesn't append the attributes of one to the other; instead, you can access the related data when necessary.
You'll want to join two tables when the data in the tables has a one-to-one or a many-to-one relationship.
You'll want to relate two tables when the data in the tables has a one-to-many or many-to-many relationship. For example, a parcel may be owned by many owners. You may want to join a table of owners to the attribute table of a layer representing parcels. However, if you perform a join, MapServer will only find the first owner belonging to each parcels, ignoring additional owners. In this case, you should relate the tables instead of joining them.
If your data is stored in a geodatabase and has relationship classes defined, in order to have MapServer advertize that relationship, both source and destination table(s)/layer(s) need to be added to the map. In addition to the relationship stored in geodatabase, relationship can also be stored in the map. This type of relationship is useful when either source or destination table/layer or both are not in geodatabase format (e.g. shapefile, text file etc.) or they belong to two different geodatabases.
Subtypes and Domains
Subtypes are records in a table or feature class that have been grouped based on an attribute field. Subtypes are implemented by creating coded values and, therefore, are associated with fields of the data type short or long integer. These integer values each represent a feature in the subtype. For example, the following codes in a subtype named "WaterMains" could represent valid classes in a feature class for water mains:
- Transmission water mains
- Distribution water mains
Each subtype can also have its own attribute domain for a given field. Domain represents a set of or a range of values valid for a field. Domains can be of two types &endash (a) range domain or (b) coded domain.
As name suggests, a range domain sets the minimum and maximum limits of values acceptable for a field. In the above example, a range domain for water pressure can be implemented. The subtype representing 'r;transmission water' mains can have a pressure between 40 and 100 psi, while the subtype for 'r;distribution water' mains can have a pressure between 50 and 75 psi.
While a coded value domain contains a set of distinct valid values for a field. It can apply to any type of attribute &emdash text, numeric, date, and so on &emdash and specifies a valid set of values for an attribute. For example, a coded value list for a text attribute might include valid material values:
- CL - cast iron pipe
- DL - ductile iron pipe
- ACP - asbestos concrete pipe
Or a coded value list might include the numeric values representing valid diameters:
- .75 = 3/4"
- 2 = 2"
- 24 = 24"
- 30 = 30"
The coded value domain includes both the actual value that is stored in the database (for example, CDL for cast iron pipe) and a description of what the code value means (for example, cast iron pipe).
MapServer returns subtypes and domains information as a part of MapServerInfo for each layer or table that has subtypes set. MapLayerInfo and StandaloneTableInfo objects have properties to retrieve information about subtypes and domains.
The domain information obtained using Field::Domain property returns the default domain set and does not take subtypes information in account. When there is no subtype assigned to a layer or table, domain information should be retrieved from Field::Domain. On the other hand, domain information must be used from MapLayerInfo/StandaloneTableInfo's Subtypes property when subtypes are used.
MapServer functions such as Identify and Find return descriptions of subtypes or domain values instead of values saved in the database &endash in the above example, the functions will return "r;case iron pipe" instead of "r;CL". To the contrary, query functions e.g. QueryData, to return values saved in the database i.e. "r;CL" not "r;case iron pipe". Client needs to match these value with subtypes & domains to show the meaningful description when needed.
Please note that subtypes and domains are only supported by layer or tables stored in a geodatabases (ArcSDE, file or personal).
Attachments
Attachments provide a flexible way to manage additional information that is related to your features. Attachments allow you to add files to individual features and can be images, PDFs, text documents, or any other type of file. For example, if you have a feature representing a building, you could use attachments to add multiple photographs of the building taken from several angles, along with PDF files containing the building's deed and tax information.
ArcGIS Server recognizes when a layer or table supports attachments and advertises it. An attachment could be any multi-media file format e.g. a document in PDF format, a photo or even a video. As a client you may use MapLayerInfo or StandaloneTableInfo's HasAttachments property to find out that. It is a two step process to retrieve any attached data. Once you know which layer has attachments, you can use QueryAttachmentInfos to find out whether one or more features/records from a specific layer/standalonetable have attached data and if so, their meta data. Meta information includes the size of the data, MIME type and a description. Finally to retrieve the data from the server, use QueryAttachmentData function with AttachmentIDs coming from the result of QueryAttachmentInfos function. The data comes to the client as URL or as MIME.
HTMLPopup
QueryHTMLPopups is a mechanism to share HTML formatted rich information about features. Unlike other MapServer query functions where results comes back in very rudimentary format or as primary data types and it is up to the client on how to display those data, the results of this method are HTML contents where feature attributes are formatted (may be with multimedia embedded within) in a way that the author wanted. An HTML page is the result of the ArcGIS Server this method.
ArcGIS Server provides two ways to get results in HTML format &endash (a) Identify function and (b) QueryHTMLPopup function. To know whether a layer supports this functionality, use MapLayerInfo. HTMLPopupType which could be one of these three values:
|
Values |
Description |
|---|---|
|
esriServerHTMLPopupTypeNone |
The layer does not support HTMLPopup. |
|
esriServerHTMLPopupTypeAsHTMLText |
The layer supports HTMLPopup and result comes from this layer is a valid HTML page. |
|
esriServerHTMLPopupTypeAsURL |
The layer supports HTMLPopup, but instead of returning an HTML page as a result, it returns a URL. |
In order to get this content as a part of Identify result, a client needs to use one of the following two identify option constants:
- esriIdentifyVisibleWithHTMLPopup - results from all visible layers
- esriIdentifyTopOneWithHTMLPopup - results only from the top visible layer
The main difference between Identify() and QueryHTMLPopup function is that the former one uses a search shape to find features from one or more that one layers on a map while the later one takes a list of ObjectIDs for a specific layer and return the result as an array of string that represents HTML content.
Raster Data
Raster field is another field that is supported by a feature class or table in a geodatabase to store raster imagery e.g. photos, aerial image etc. for a feature. In the geodatabase model only one raster image can be stored with a feature or a record.
MapServer query functions such as QueryData ignores any raster data, if any, associated with a feature or record while returning the result back to the SOAP client.
In order to for the client to retrieve raster data associated with a feature, MapServer provides a function named QueryRasterValue. Use that function to retrieve raster images in JPEG, PNG or TIFF format as a URL or MIME data embedded within the response.
Working with cached versus dynamic map services
ArcGIS Server map services provide access to two types of visible map content: dynamic and cached. Dynamic maps are generated on-the-fly per a user request. Layer visibility, graphics, and other variables can be modified before the dynamic map is generated. Unfortunately, as the amount of content and complexity in the map increases, so does the amount of time it takes to generate the map. Alternatively, cached maps consist of pre-generated map tiles available for immediate access. Since the cost of generating the maps has already been paid, the performance penalty associated with map generation is not a factor. Working with a map cache requires knowledge of cache properties, such a location and structure, so that you are able to retrieve the appropriate cached image. In general, a map cache is stored in a nested set of directories which contain image tiles for map extents at specific scale levels, or levels of detail. The author of the map service determines these levels. The cached tiles are usually accessible via a public virtual directory or an ArcGIS Server map service tile handler.
Information about a map cache
Use IsFixedScaleMap to determine if a map service is cached. The term fixed scale map service and cached map service are used synonymously. GetCacheDescriptionInfo returns information on a cached map service in one call including its cache type, its tiling scheme (TileCacheInfo), image information (TileImageInfo) and control information (CacheControlInfo).
TileCacheInfo contains information on the tiling scheme for the cache. The tiling scheme includes the tiling origin, spatial reference, tile size in pixels and information on the Levels of Detail (LOD) at which the service is cached. LODInfos enumerate a LODInfo object which describes a scale and resolution. Using the tiling scheme information in TileCacheInfo the client can calculate the tiles that cover any rectangular extent in map space and then retrieve tiles either directly from the virtual directory, or from the tile handler or by making GetMapTile or GetLayerTile requests against the map service.
GetMapTile gets the specified tile from a map service that has a single fused cache. GetLayerTile gets the specified tile for a defined layer from a map service that has a multi-layer cache.
GetTileImageInfo returns information describing the image format for the cached tiles. TileImageInfo has two main properties CacheTileFormat and CompressionQuality. Format can have values (PNG8, PNG24, PNG32 and JPEG). If the selected format is JPEG, then the compression quality can have a value from 0 to 100. The value of format must be used in constructing the URL to the tile.
GetCacheControlInfo returns cache control information that allows clients to discover information such as if client caching is allowed.
Limitations
Map services do not expose editing capabilities. They merely provide read-only access to feature and attribute content. In order to edit, you should use Feature Service.
Methods
|
Proxy method |
Description |
|---|---|
|
Calculate the distance between two points in a map (data frame). | |
|
Calculates the scale of the specified map (data frame) at the given map extent for an image with the given size. | |
|
Generates a dynamic map image from a data frame (map) in an ArcGIS Server map service. | |
|
Generates a scale bar image for a data frame (map) in an ArcGIS Server map service. | |
|
Searches the attributes of one or more layers in a data frame, in a map service for a given search string. | |
|
Converts map coordinates to screen coordinates. | |
|
Gets the cache control information for a given map. Primarily used to determine if client caching is allowed. | |
|
Gets the cache description information for a given map. Includes cache control info, tile cache info, tile image info, and cache type info. | |
|
Gets the cache name for a given layer within a map (data frame). | |
|
Gets information on the storage of a map cache, exploded or compact. | |
|
Name of the active map (data frame) in a map service. | |
|
A set of map service properties that can be used to describe the general content of the service. | |
|
Returns the image tile from a layer cache for a specific location. | |
|
Returns legend information, such as layer name, group heading, classification labels and symbol swatches, for layers in a map. | |
|
Returns the number of maps (data frames) in a map service. | |
|
Name of the map (data frame) as indicated by the index value provided. | |
|
Gets an array of subtype information objects. | |
|
Returns the image tile from a fused map cache for a specific location. | |
|
Returns information about the present state of a map (data frame). | |
|
Returns a set of name-value pairs that contain information on map service configuration restrictions. | |
|
Returns SQL syntax information for the specified layer. | |
|
Returns the supported formats for retrieving images generated by a map service. | |
|
Get cache configuration properties for a given map. | |
|
Get information about the image format of the cache tiles. | |
|
Gets the virtual directory containing the cache tiles for a given layer within a map (data frame). | |
|
Determines if a given layer in a map (data frame) has a layer cache. | |
|
Determines if a map (data frame) has fused cache. Each map in a map service can only have one fused cache. | |
|
Returns map features and their attribute values based on a spatial search. | |
|
Determines if a map (data frame) has a cache. The cache may be a single fused map or a layer cache. | |
|
Queries and returns the multimedia data as MIME or URL. | |
|
Finds and returns descriptive information on multimedia data attached to any feature. | |
|
Returns a record set of features or rows that meet the query filter selection criteria for the specified layer or table description. | |
|
Queries and returns LayerDrawingDescription objects for a map's feature layers based on the input layer ids. | |
|
Returns the number of the features that meet the query filter selection criteria for the specified layer id. | |
|
Returns the count of the features that meet the query filter selection criteria for the specified layer description. | |
|
Returns a record set of features (geometry and attributes) that meet the query filter selection criteria for the specified layer id. | |
|
Returns a record set of features that meet the query filter selection criteria for the specified layer description. | |
|
Returns a set of feature ids that meet the query filter selection criteria for the specified layer id. | |
|
Returns a set of feature ids that meet the query filter selection criteria for the specified layer description. | |
|
Queries and returns a layer or table for the HTML formatted attributes of a feature. | |
|
Returns feature geometry and associated hyperlink URL for visible layers within a defined map extent. | |
|
Queries and returns raster images in JPEG, PNG or TIFF format as a URL or MIME data. | |
|
Returns a related-record set of features or rows that are related to the specified features or rows for the specified layer or table id. | |
|
Returns the number of the features from a table or a layer that meet the query filter selection criteria for the specified layer or table description. | |
|
Returns a set of object ids that meet the query filter selection criteria for the specified layer or table description. | |
|
Converts points from screen coordinates to map coordinates. |