Envinsa WEB MAP SERVICE REFERENCE

Transcription

1 Envinsa WEB MAP SERVICE REFERENCE

2 Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of Pitney Bowes Software Inc., One Global View, Troy, New York Pitney Bowes Software Inc. All rights reserved. MapInfo, the MapInfo logo and Envinsa are trademarks of Pitney Bowes Software Inc. and/or its affiliates. Corporate Headquarters: Phone: Fax: Sales: Government Sales: Technical Support: UK and EMEA Headquarters: Phone: Fax: Technical Support: Asia Pacific Headquarters: Phone: Fax: Technical Support: Contact information for all Pitney Bowes Software offices is located at: Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark. February 9, 2010

3 Table of Contents Chapter 1: Introduction Overview Introduction Layers and Styles WMS Servers Understanding the WMS Server Functionality How to Get Information About a WMS Server How to Retrieve a Map From a WMS Server How to Use the WMS Server GetFeatureInfo Operations Chapter 2: Web Map Service Capabilities Getting Service-Level Metadata About a WMS Inputs and Behaviors Output General Service Metadata Capabilities Layers Customizing Service Element Information Getting Maps Inputs and Behaviors Sample Request Sample Response Getting Information About Map Features Inputs and Behaviors Sample Request Output Chapter 3: Web Map Service Fundamentals WMS Server Technology HTTP GET HTTP POST Basic Authentication Layers and Styles Creating a Named Layer

4 Chapter 4: Configuration Settings Preferences

5 Introduction 1 Welcome to the Envinsa Location Platform Web Services. This guide provides descriptions and examples for the developer who is writing applications that access the Web Map Service. The Web Map Service lets an application render layers of geographic data onto a map image. The OpenGIS Consortium (OGC) Web Map Service standard (version located at defines how a client can retrieve map images over the Internet or a private intranet by submitting XML requests through HTTP. Products that can use results from an OGC compliant WMS server will work with the Envinsa OGC Web Map Service, such as MapInfo Professional and MapXtreme or other vendor software. In this section: Overview Understanding the WMS Server Functionality

6 Overview Introduction The Envinsa Web Map Service (WMS) allows software clients to reference map images over the Internet or a private intranet. The Envinsa Web Map Service implementation is based on the WMS OGC specification. Using HTTP requests, the Web Map Service provides georeference data to a client that displays this data as an image. Georeference data is information associated with maps that describe the real world extents of specific features and the projection upon which it is based. The images can be provided as GIF, JPEG, PNG, and other image formats. Layers and Styles The images rendered can be made of layers that are hierarchical an image can be served that is made up of a layer that is a collection of other layers. Since WMS renders layers, the characteristics that modify the view of layers, such as styles and coordinate systems, can also be included in the layers provided. This lets you customize images because each image can act as a separate layer within the client that is accessing these images. WMS Servers Aside from the servers provided by Pitney Bowes MapInfo and any service that you provide through your own organization, there are many public access WMS servers available on the World Wide Web. There are WMS servers for LandSat data, USGS DOQ photos, bathymetry, weather, and many other data types. Pitney Bowes MapInfo maintains a Web Map Server of many of our data products. To view these products, open the following URI in a WMS client, such as MapInfo Professional: If you are accessing maps from different sources, it is not a complicated task to combine the images into a single coherent image that your users can work with. It is important to keep the spatial information (bounding box, spatial reference system, height, and width) identical. This ensures that the different images align with each other properly. Note: Not all Web Map Servers adhere to the OGC standards and may or may not be compatible with your WMS client. Please refer to the OGC WMS specification ( for more information about developing a WMS client to the WMS specification. At the time of this manual s writing, the most current specification for WMS is 1.3. The latest OpenGIS specifications can be found at 6

7 Chapter 1: Introduction Understanding the WMS Server Functionality There are three WMS server-specific methods that provide the basis for the server implementation: GetCapabilities GetMap GetFeatureInfo Each of these methods is discussed below. Note: A basic Web Map Service classifies its georeferenced information holdings into layers and offers a number of predefined styles in which to display those layers. How to Get Information About a WMS Server When first finding a Web Map Server, it is necessary to find out the names of available layers, styles in use, spatial information in use, and other information that the server provides, in order to make a request for an image that is within the parameters of the server. The GetCapabilities request retrieves service-level metadata over the Internet or intranet, including the server name, the layer names, abstracts about the data, and valid request parameters, among other data. The following section highlights potential ways to apply this capability: Getting Service- Level Metadata About a WMS on page 9. How to Retrieve a Map From a WMS Server GetMap retrieves the geospatial information, over the Internet or an intranet, based on a specific request of the data you want and returns it as a raster image. When invoking GetMap a WMS client can specify: Layers Styles A bounding box (the area to be mapped) A coordinate reference system (also known as the spatial reference system) Output image format (JPEG, GIF, PNG. and others). Output size (height and width of the returned image) Background transparency and color The following section highlights potential ways to apply this capability: Getting Maps on page 12. How to Use the WMS Server GetFeatureInfo Operations GetFeatureInfo returns request information for a feature at a given point on the map after a GetMap has been called. This is a search-at-point operation in which, after a GetMap request, the GetFeatureInfo request supplies the X, Y pixel coordinates of the location about which you want more information. The following section highlights potential ways to apply this capability: Getting Information About Map Features on page 14. Web Map Service Reference 7

8 Web Map Service Capabilities 2 The Envinsa Web Map Service supports three capabilities which are described in detail in this section. In accordance with the Open GIS Consortium s Web Map Service Implementation Specification, The Envinsa Web Map Service provides the following operations: GetCapabilities This capability retrieves service-level metadata including the server name, the layer names, abstracts about the data, and the valid request parameters. GetMap This capability is used to request a map image using well-defined geospatial and dimensional parameters containing layers, styles, boundaries, and the spatial reference system (coordinate system of the data being retrieved). You can also specify the image format (JPEG, GIF, PNG, and others) and styles. GetFeatureInfo This capability is used to request information for a feature at a given point on the map after a GetMap has been called. All of these request types are case-sensitive. In this section: Getting Service-Level Metadata About a WMS Getting Maps Getting Information About Map Features

9 Getting Service-Level Metadata About a WMS Chapter 2: Web Map Service Capabilities Before obtaining a map from a WMS server, it is important to determine the names of available layers, their contents, their SRS (spatial reference system, or coordinate system) settings, and other information about the data. Use the GetCapabilities request to obtain this information from a server. The GetCapabilities request returns service-level metadata in XML format. This metadata is a description of the information content and valid request parameters of the service. Inputs and Behaviors The following table lists the possible request inputs: Inputs Required Description VERSION=version No Request version. Envinsa currently supports version SERVICE=WMS Yes Service type. The SERVICE attribute is always set to WMS because that is all Envinsa currently supports. REQUEST=GetCapabilities Yes Request name The request parameters are always sent as an HTTP query string. The following is a sample GetCapabilities request: WebMap?SERVICE=WMS&REQUEST=GetCapabilities Output After a successful GetCapabilities request, the service returns a GetCapabilities response which is a large XML file. The GetCapabilites.xml file contains the following information. General Service Metadata The first part of the response contains the name of the Web service (always OGC:WMS), the title of the Web service, and the URL of the service. Note: The Name is usually a single word read by a machine, while the Title is designed to be human-readable. The following code illustrates an example of this section: <Service> <Name>OGC:WMS</Name> <Title>MapInfo Corporation Map Server</Title> <OnlineResource xmlns:xlink=" xlink:type="simple" xlink:href=" </Service> Web Map Service Reference 9

10 Capabilities This section names the actual operations that are supported by the service, the output formats offered by these operations, and the URL prefix for each operation. For most WMS services this section has three parts, one for GetCapabilities, one for GetMap, and one for GetFeatureInfo. The following example illustrates the GetMap section: <GetMap> <Format>image/gif</Format> <Format>image/jpeg</Format> <Format>image/jpg</Format> <Format>image/png</Format> <DCPType> <HTTP> <Get> <OnlineResource xmlns:xlink=" xlink:type="simple" xlink:href=" WebMap?" /> </Get> </HTTP> </DCPType> </GetMap> Layers Within the Capabilities element is a Layer element for each map that can be provided by the service. WMS also allows layers to be made up of layers so some nesting of layers can also be seen in these elements. Each Layer element includes the following: Title a name of the layer that is readable by the user. Name a name of the layer that is used to reference the layer in requests. Style a predefined style that can be used with this particular layer. SRS the spatial reference system(s) that applies to this layer. If more than one SRS can be used on the layer, each one can be listed. LatLonBoundingBox a set of attributes that state the minimum bounding rectangle of the map data in the default coordinate system (EPSG:4326). These numbers are expressed in decimal degrees These values are important when making a GetMap request (see Getting Maps on page 12), as that request requires the correct values that are specific to each individual Web Map service. When layers are nested, the values set for a parent layer cascade down to subsidiary elements unless specifically set differently in the child layers. The example below shows portions of the layer element to illustrate the different settings. <Layer> <Title>MapInfo Corporation Map Server</Title> <SRS/> <LatLonBoundingBox maxx="180" miny="-90" minx="-180" maxy="90"/> <Style> <Name>BigRedStar</Name> 10

11 Chapter 2: Web Map Service Capabilities <Title>BigRedStar</Title> </Style> <Style> <Name>POITextStyle</Name> <Title>POITextStyle</Title> </Style> <Style> <Name>PositionStyle</Name> <Title>PositionStyle</Title> </Style> <Style> <Name>RouteEndPointStyle</Name> <Title>RouteEndPointStyle</Title> </Style> <Layer> <Title>FeatureLayers</Title> <SRS>EPSG:4201</SRS> <SRS>EPSG:4205</SRS>... <Layer> <Title>PUBLIC</Title> <Layer queryable="1"> <Name>uscity</Name> <Title>US Cities</Title> <LatLonBoundingBox minx=" " miny=" " maxx=" " maxy=" "/> </Layer> <Layer queryable="1"> <Name>WorldCountries</Name> <Title>WorldCountries</Title> <LatLonBoundingBox minx=" " miny=" " maxx=" " maxy=" "/> </Layer> </Layer> </Layer>... </Layer> Customizing Service Element Information To customize your WMS installation, you can supply a service.xml file that stores the Service element information you would like to have included in any GetCapabilities response from your server. This service.xml file should conform to the OGC DTD (listed in the WMS specification) and it needs to be located in the WebMap context in the WEB-INF folder. The root element of the XML file needs to be Service or the XML file is considered invalid and any GetCapabilities Web Map Service Reference 11

12 Getting Maps response lists the default information from your initial WMS installation. There are many optional elements that can be included within the Service element. However only a few are required. See the specification for details. The following is a sample service.xml file: <Service> <Name>OGC:WMS</Name> <Title>Custom Service title</title> <OnlineResource xmlns:xlink=" xlink:type="simple" xlink:href=" /WebMap/servlet/WebMap?" /> </Service> Getting Maps The primary reason to use or establish a Web Map Server is to obtain or serve maps. Use the GetMap request to obtain images from a WMS server. GetMap requests are always sent as HTTP strings and the response is a map image with well-defined geospatial and dimensional parameters in the image format specified in the request. Inputs and Behaviors When invoking GetMap a WMS query can specify: Inputs Required Description VERSION=version No Request version. Envinsa WMS only supports version SERVICE=WMS Yes Service type. This is always WMS. REQUEST=GetMap Yes Request name. For a GetMap request this is always GetMap. LAYERS=layer_list Yes The layer or layers to be included in the map image. Each layer should be separated by a comma. For example: LAYERS=Layer1,Layer2,Layer3 12

13 Chapter 2: Web Map Service Capabilities Inputs Required Description STYLES=style_list Yes Comma-separated list of one rendering style per requested layer. A style is required for each layer requested. If no style is requested, the attribute must be present but without a value. If requesting multiple layers, the styles listed should be in the same order as the layers. For example: STYLES=Style1,,Style3 In the above example the second style (for the second layer requested) is left blank, allowing the default style defined for the layer to be used. SRS=namespace:identifier Yes The coordinate reference system used in the map (numeric representation of the projection of the map, also known as the spatial reference system). If this is not specified, the default coordinate reference system, as defined in the default style of the layer, is used. This is also defined as the spatial reference system (SRS). BBOX=minx,miny,maxx,maxy Yes The area to be mapped. the bounding box is specified as the four coordinates of the corners of the box that bounds the map area to be included in the image. The BBOX coordinates are always expressed in the units of the SRS. WIDTH=output_width Yes Width in pixels of map picture. HEIGHT=output_height Yes Height in pixels of map picture. FORMAT=output_format Yes The format in which the map image is to be returned. TRANSPARENT=TRUE FALSE No The transparency and color of the background of the image. If nothing is specified, the value is FALSE. BGCOLOR=color_value No Hexadecimal red-green-blue color value for the background color (default=0xffffff). EXCEPTIONS=exception_format No The format in which exceptions are to be reported by the WMS (default=se_xml). WFS=web_feature_service_URL No URL of Web Feature Service providing features to be symbolized using Styled Layer Descriptor. Web Map Service Reference 13

14 Getting Information About Map Features Sample Request The following is a sample GetMap request: SERVICE=WMS&REQUEST=GetMap&SRS=EPSG:4326&BBOX=-100,0,90,100& WIDTH=400&HEIGHT=300&Layers=PUBLIC/WorldCountries&STYLES=PUBLIC/ PositionStyle&FORMAT=image/png Note: The code above should all be on a single line with no breaks. Due to space limitations, we cannot display the request in such a way in this document. Sample Response After a successful GetMap request, the service returns a GetMap response that is an image of the map specified by the parameters in the request. The following is the response to the above request: Getting Information About Map Features Once a GetMap request has been successfully completed the user may want further information about the features included in the map. Use the GetFeatureInfo request to get this further information from a server. A GetFeatureInfo request returns information regarding the layers in the map and the queryable attributes of each layer. This operation is optional. If GetFeatureInfo is employed, it must be issued after a GetMap request is sent, as the X/Y pixel coordinate of a point on that map is a required input of a GetFeatureInfo request. Refer to the Web Mapping Service OGC Specification for more information about this capability ( 14

15 Chapter 2: Web Map Service Capabilities Inputs and Behaviors The following table lists the possible GetFeatureInfo request inputs. Inputs Required Description VERSION=version Yes Request version. Envinsa only supports version REQUEST=GetFeatureInfo Yes Request name. For a GetFeatureInfo request this is always GetFeatureInfo. <map_request_copy> Yes Partial copy of the GetMap request parameters that generated the map for which information is desired. The entire GetMap request is included except for the VERSION and REQUEST parameters. See the sample request below. QUERY_LAYERS=layer_list Yes Comma-separated list of one or more layers to be queried. You do not need to include every layer included in the initial GetMap request. INFO_FORMAT=output_format No Return format of feature information (MIME type). FEATURE_COUNT=number No The maximum number of features about which to return information (default is FEATURE_COUNT=1). X=pixel_column Yes X-coordinate in pixels of feature (measured from the upper left corner which is 0). Y=pixel_row Yes Y-coordinate in pixels of feature (measured from the upper left corner which is 0). Sample Request The following is a sample GetFeatureInfo request: SERVICE=WMS&REQUEST=GetFeatureInfo&SRS=EPSG:4326&BBOX=-180,-180,180,180& WIDTH=100&HEIGHT=100&Layers=WorldCountries&QUERY_Layers=WorldCountries&ST YLES=& FORMAT=image/png&X=1&Y=1&FEATURE_COUNT=1 Note: The code above should all be on a single line with no breaks. Due to space limitations, we cannot display the request in such a way in this document. Output After a successful GetFeatureInfo request, the service returns a GetFeatureInfo response. A GetFeatureInfo response is an XML file. The returned file includes information about the layers in the map, the queryable attributes of those layers, and the bounding box and SRS information of the map. Web Map Service Reference 15

16 Web Map Service Fundamentals 3 The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. The Envinsa Web Map Service uses HTTP for the transfer of information. Specifically two methods are used. They are described in detail in this section. In this section: WMS Server Technology HTTP GET HTTP POST Basic Authentication Layers and Styles

17 Chapter 3: Web Map Service Fundamentals WMS Server Technology The Envinsa WMS server functions using the HTTP GET and HTTP POST methods. For a full discussion of HTTP and its methods, refer to the Internet Engineering Task Force HTTP specification ( HTTP GET The GET method retrieves whatever information (in the form of an entity) is identified by the Request-URI. If the Request-URI refers to a data-producing process, it is the produced data that is returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process. For the Web Map Service, the GET method is used to retrieve entire images from whatever server is being accessed. HTTP POST The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. POST is designed to allow a uniform method to cover the following functions: Annotation of existing resources. Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles. Providing a block of data, such as the result of submitting a form, to a data-handling process. Extending a database through an append operation. The actual function performed by the POST method is determined by the server and is usually dependent on the Request-URI. The posted entity is subordinate to that URI in the same way that a file is subordinate to a directory containing it, a news article is subordinate to a newsgroup to which it is posted, or a record is subordinate to a database. In the context of the Envinsa Web Map Service, HTTP POST is used by the server and is not directly accessible by a client. Basic Authentication Usually a Web Map service is open to the general public and needs no authentication. From time to time, a server may limit access to only authorized users. Envinsa allows you to access WMS servers that use HTTP Basic Authentication. When defining a WMS layer in the Envinsa Map Manager, you can add a username and password to your Connection URL. The format of the HTTP URL is: wms: For example: Web Map Service Reference 17

18 Layers and Styles If you do not want to include IDs or passwords in a WMS request query, you have the option to set authentication in the client by including additional information in the HTTP header on the Web page. The following is a sample HTTP header that includes basic authorization information: GET /WebMap/servlet/WebMap?SERVICE=WMS&REQUEST=GetCapabilities HTTP/1.1 Authorization: BASIC YWRtaW46aDdhU1ZEd2o3RVd5a1gzRUhNbW5Pdz09 User-Agent: Java/1.4.1 Host: :8080 Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive WMS supports optional basic authorization that is managed through the Enterprise Manager. The following Java code provides an example of how to include this information a WMS client: URL url = new URL(wmsURL); HttpURLConnection uc = (HttpURLConnection)url.openConnection(); if(secure) { uc.setusecaches(true); uc.setrequestproperty("authorization", EMEncoder.encryptBasicAuthorization("admin", EMEncoderPBE.encrypt("admin"))); } Beside Basic Authorization, the WMS also provides enterprise access control based on the Username/Role. When the HTTP header contains authorization information, the service checks the user's role as it is defined in the Enterprise Manager. If the user has an Administrator role, the user can access all resources. Otherwise, the user can only access its own enterprise resources. For non-enterprise users, they can only access public resource. The PUBLIC directory is the only available directory so is not specified. For example, if you have a named layer under the JNDI root such as "PUBLIC/WorldCountries", it is displayed as WorldCountries without the PUBLIC prefix. Layers and Styles The images rendered can be made of layers that are hierarchical an image can be served that is made up of a layer that is a collection of other layers. Since WMS renders layers, the characteristics that modify the view of layers, such as styles and coordinate systems, can also be included in the layers provided. This lets you customize images because each image can act as a separate layer within the client that is accessing these images. You can find out what map layers are available from a WMS server by submitting a GetCapabilities request and examining the GetCapabilities.xml file returned in the response. (Refer to Getting Service-Level Metadata About a WMS on page 9 for more information.) 18

19 Chapter 3: Web Map Service Fundamentals Creating a Named Layer If you have existing file-based data, such as an Oracle database or TAB files, that you want to make accessible through a WMS server, you first have to save the map data as a named layer using the Envinsa Map Manager. To create a named layer using file-based data such as TAB files: 1. Open the Envinsa Map Manager. 2. On the Map Definitions tab, click the New button to start a new map definition. 3. Click the Layer Control button to open the Layer Control dialog box. 4. In the Layer Control dialog box, click Add. The Add Layer Wizard appears. 5. To add a TAB file, select MapInfo TAB File from the list provided in the Select a Data Source panel. Click Next. 6. In the Specify MapInfo Table Information panel, click the Add button to navigate to the file location, and then select one or more files. Click Open to return to the Add Layer Wizard, then click Next to continue. 7. In the Specify Other Layer Settings panel, give the layer a name to help you identify it in the Layer Control dialog box, if desired. Note: The name you give the layer here is not related to the name used later to save it as a named layer. 8. Click the Finish button in the wizard to return to the Layer Control dialog box. Your TAB file should now appear in the Layer Theme list. 9. In the Layer Control dialog box, select the TAB file in the Layer Theme list, and click the Save button. The Save Named Layer dialog box opens. 10. In the Saved Named Layer dialog box, enter the name you want to give the layer. This is the name that will be used later to access the named layer in the WMS server. 11. Click the Save button to save the layer as a named layer. The named layer is now available to a WMS server. Web Map Service Reference 19

20 Configuration Settings 4 Using the Enterprise Manager several characteristics can be set for the behavior of the Web Map Service. This section details those preferences. In this section: Preferences

21 Chapter 4: Configuration Settings Preferences The following preferences can be set in the Enterprise Manager: Setting Required Description providerurl No The URL for the named resource s JNDI root. By default this is left empty, allowing for the service to automatically use the Named Resource component. Fill in a value for this preference if you have your data located elsewhere. epsgonly No Determines whether to return only EPSG:SRS names. If this is set to False, all names are returned, but only if the SRS has a name. Default Value Null true generateimageusing RequestedBounds No Determines whether to stretch the image; if not present, the default behavior is to use the requested bounds. Sometimes the provided image does not fill the requested bounds or the requested width and height settings have a different proportion than the requested bounds. In those cases, this preference forces the service to stretch the image to fill all the parameters. If this preference is set to True, the resulting images can show up with an inaccurate proportion. true layercontextprefix No This preference can be given a string that acts as a content prefix for named layers. This is useful for distinguishing layer names that can be confused with style names. stylecontextprefix No This preference can be given a string that acts as a content prefix for named styles. This is useful for distinguishing style names that can be confused with layer names. maxageofcapabilitiesxml Yes Determines the maximum age of the capabilities.xml file. A value of -1 means that the capabilities.xml file never expires. A positive value is interpreted as the maximum allowed age of the file in hours. When the server is initialized, it checks the age of the file, and if it has become outdated, it regenerates a new version of the file. If the maximum age is set to -1, be sure to restart the service after changing anything with the data so that the GetCapabilities.xml file is accurate. Null Null 1 Web Map Service Reference 21

22 Setting Required Description hostmachinename No Determines the value of the machine name in the capabilities.xml. If this value is not specified, the capabilities.xml document uses the IP address of the server machine. It is strongly suggested that this preference be specified. disablefeatureinfo No Determines whether the GetFeature operation is available. Set this preference to False to disable the operation. This is useful if the metadata of the information needs to be kept private. serviceurl No This preference sets the return string for the end point of the servlet. The form should be IP:servlet port/webmap/servlet/webmap?. You can also use this preference to set the proxy URL to override the default xlink:href attribute. The form is as follows: antialiasing No Sets the rendering preference between speed and quality. By default (false) the rendering preference is speed. When set to true, redering quality (sharper, more detailed images) will be generated. Default Value Null false Null false 22