MapInfo Spatial Server Map Tiling Service - Product Documentation ...

MapInfo Spatial Server
Version 1.0
Map Tiling Service Guide

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 12180-8399.
© 2012 Pitney Bowes Software Inc. All rights reserved. Pitney Bowes Software Inc. is a wholly-owned subsidiary
of Pitney Bowes Inc. Pitney Bowes, the Corporate logo, MapInfo, Group 1 Software, and MapInfo Professional
are [registered] trademarks of Pitney Bowes Inc. or a subsidiary. All other trademarks are the property of their
respective owners.
United States:
Phone: 518.285.6000
Fax: 518.285.6070
Sales: 800.327.8627
Government Sales: 800.619.2333
Technical Support: 518.285.7283
Technical Support Fax: 518.285.7575
www.pb.com/software
Canada:
Phone: 416.594.5200
Fax: 416.594.5201
Sales: 800.268.3282
Technical Support:.518.285.7283
Technical Support Fax: 518.285.7575
www.pb.com/software
Europe/United Kingdom:
Phone: +44.1753.848.200
Fax: +44.1753.621.140
Technical Support: +44.1753.848.229
www.pitneybowes.co.uk/software
Asia Pacific/Australia:
Phone: +61.2.9437.6255
Fax: +61.2.9439.1773
Technical Support: 1.800.648.899
www.pitneybowes.com.au/software
Contact information for all Pitney Bowes offices is located at: www.pb.com/contact-us.
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.
30 / 04 / 2012

Contents
Chapter 1: Introduction..............................................................................................5
About the Map Tiling Service.............................................................................................6
Supported Data................................................................................................................6
Named Map Modifications...............................................................................................6
Chapter 2: Managing Map Tiling Resources and Configuration............................7
Accessing and Modifying the Configuration File.............................................................8
Global Configuration Parameters.....................................................................................8
Uploading and Accessing Resources in the Repository................................................11
Reload the Service Configuration using JMX Console..................................................13
Adding and Modifying Named Tiles.................................................................................14
Defining Named Tiles.....................................................................................................14
Chapter 3: Map Tiling REST Interface.....................................................................19
What Is the Map Tiling REST Interface?..........................................................................20
REST URL...........................................................................................................................20
Methods..............................................................................................................................20
MapList...........................................................................................................................20
Description.....................................................................................................................21
Tile..................................................................................................................................22
Objects...............................................................................................................................24
MapDescription..............................................................................................................24
Chapter 4: Legacy Map Tiling Interface..................................................................27
What Is the Legacy Map Tiling Interface?.......................................................................28
URL.....................................................................................................................................28
Methods..............................................................................................................................28
getMaps.........................................................................................................................28

4
getDescription................................................................................................................29
getLevelDescription........................................................................................................30
getTile.............................................................................................................................31
getTileBounds................................................................................................................33
convertScreenToMapCoord...........................................................................................34
convertScreenToTileCoord.............................................................................................36
convertMapToTileCoord.................................................................................................37
convertMapToVirtualPixelCoord.....................................................................................38
Objects...............................................................................................................................40
MapDescription..............................................................................................................40
LevelDescription.............................................................................................................42
MapCoordinate...............................................................................................................43
TileCoordinate................................................................................................................43
VirtualPixelCoordinate....................................................................................................44
Appendix A: Common Data Types..........................................................................45
Request URL Data Types..................................................................................................46
Response JSON Data Types.............................................................................................47
Primitive Types...............................................................................................................47
Object Types..................................................................................................................47
Appendix B: Errors...................................................................................................49
Handling Errors.................................................................................................................50
Error Object........................................................................................................................50
Error Codes........................................................................................................................50
Appendix C: How Pixels, Tiles, and Map Coordinates are Transformed.............53
Transforming a Pixel to a Map Coordinate.....................................................................54
Transforming a Pixel to a Tile Coordinate.......................................................................54
Transforming a Map Coordinate to a Tile Coordinate....................................................55
MapInfo Spatial Server 1.0

Introduction
The Map Tiling Service generates map tiles that can be combined to form larger
map images. These tiles can be cached by your own enterprise caching solution
to reduce the waiting times as users view, pan, and zoom maps.
This guide provides information on how to configure the Map Tiling Service, create
named tiles, and how to use the service's accompanying interfaces to access the
service from within your web applications.
In this section:
• About the Map Tiling Service . . . . . . . . . . . . . . . . . . . . . . . .6
1

About the Map Tiling Service
About the Map Tiling Service
The Map Tiling Service dynamically generates subsets of a map on a per-request basis. This subset is
called a tile. The tiles generated from the Map Tiling Service can be used individually, or combined to
form larger maps, in applications for seamless map interaction. This service provides fast, simple, lightweight
map rendering where more complex map rendering can be performed using the Presentation
Service.
The Map Tiling Service allows the hosting of multiple maps that can be used to generate the tiles. These
named maps are located in one or more map repositories. Each map hosted by the Map Tiling Service
can have a specific configuration that defines how the map will be used to create tiles.
The Map Tiling Service has two interfaces. Both are web based HTTP interfaces, however, one is a
REST interface, and the other is a name/value pair interface:
• REST - Referred to as the Map Tiling REST interface, this API is a simplified web interface that has
methods for getting the name of maps, describing maps, and getting tiles. For details of this REST
interface, see Map Tiling REST Interface on page 19 for more information.
• Name/Value - Referred to as the Legacy Map Tiling interface, this API provides more complex methods
that include the REST methods as well as methods for getting the bounds of maps, level descriptions
tile sets, and numerous conversion methods between pixel, tile, and screen coordinates.
Note:
This is a legacy interface, and should only be used to support PBBI backwards compatable
applications. For all new applications, use the REST interface.
For details of this interface, see Legacy Map Tiling Interface on page 27 for more information.
Supported Data
Both vector and raster data can be hosted by the Map Tiling Service.
Named Map Modifications
6
The Map Tiling Service is designed to host your maps without modification. However, due to the dynamic
nature of tile generation, the Map Tiling Service does make minor modifications to the map after it is
loaded into the server. These changes relate to the rendering of labels, and are as follows:
• Duplication of labels is not allowed.
• Geometry calculation mode is set to STATIC.
• Partial labels are allowed.
A special category of layers relate to the display of highway shields. To allow the accurate display of
highway shield layers the following label properties are set:
• Duplication of labels is allowed.
• Geometry calculation mode is set to STATIC.
• Partial labels are allowed.
These modifications are stored in the Map Tiling Service memory and in no way change the source of
the maps hosted by the Map Tiling Service stored in the repository.
MapInfo Spatial Server 1.0

Managing Map Tiling
Resources and
Configuration
This section describes how to configure and add resources to the Map Tiling
Service. The Map Tiling Service is installed and pre-configured with the configuration
file (named configuration) located in the repository. The Map Tiling Service
uses the standard XML service configuration similar to the other MapInfo Spatial
Server services.
The named Map Tiling Service configuration file MapTilingConfiguration
is located in the Configuration directory under the root repository. For example,
a default installation will place the Map Tiling Service configuration file at http://localhost:8080/RepositoryService/repository/default/Configuration/MapTilingConfiguration
You can use your standard WebDAV protocol tools (e.g., Windows WebFolders,
DAVExplorer, etc.) to copy the configuration file from the repository, and then
upload the modified configuration file back. Once uploaded, you must use the
MapInfo Spatial Server JMX Console to invoke the new configuration for the
service.
Note:
You must be on the local machine hosting MapInfo Spatial Server to access
and make changes to resources in the repository.
In this section:
• Accessing and Modifying the Configuration File . . . . . . .8
• Adding and Modifying Named Tiles . . . . . . . . . . . . . . . . .14
2

Accessing and Modifying the Configuration File
Accessing and Modifying the Configuration File
The named Map Tiling Service configuration file MapTilingConfigurationis located in the Configuration
directory under the root repository. For example, a default installation will place the Map Tiling
Service configuration file at http://localhost:8080/RepositoryService/repository/default/Configuration/Map-
TilingConfiguration
To configure the Map Tiling Service, perform the following:
1. You must be located on the local machine hosting MapInfo Spatial Server and the repository.
2. Use a standard WebDAV protocol tool to access the repository (e.g., Windows WebFolders, DAVExplorer,
etc.) and copy the configuration file from the repository to a directory on your local machine.
The Map Tiling Service configuration file is located at http://localhost:8080/RepositoryService/repository/default/Configuration/MapTilingConfiguration
For examples of using standard WebDAV tools, see Accessing the Repository using WebDAV
3. Make changes to the local MapTilingConfiguration file. For parameter descriptions for the configuration
file, see Global Configuration Parameters on page 8.
4. Upload the modified configuration file back to the same location (and name) in the repository using
your WebDAV tool.
5. Use the MapInfo Spatial Server JMX Console to invoke the new configuration for the service. For
instruction on how to reload the configuration using the JMX Console, see Reload the Service
Configuration using JMX Console on page 13
Global Configuration Parameters
8
The Map Tiling Service configuration consists of a set of global parameters that define how tiles are
generated. These parameters are used if optional parameters defined in the named tiles are not specified.
If a named tile has defined these parameters, then the parameters in the global configuration will be
overwritten.
The following are global configuration paramters:
Parameter
RepositoryURL
ExpirationDate
Type
string
string
Required
yes
no
Description
The URL defines the location of your local repository
where resource are stored that are accessed
by the Map Tiling service. This URL should point
to the Repository Service rmi, for example: http://localhost:8080/RepositoryService/rmi
Note:
In most instances, this URL should not be
changed.
The date on which the client should delete the map
tile from the cache, and request a new copy from
the server. The ExpirationDate value must be
specified as a W3C formatted date string (for example,
2013-12-31).
MapInfo Spatial Server 1.0

Parameter
MimeList
MapResolution
MapRendering
RenderLabels
PadFactor
Type
string
integer
string
boolean
integer
Required
no
no
no
no
no
Description
Note:
The ExpirationDate parameter has effect
only when using external caching software
such as Squid or Apache.
The available types of tiles generated by the tile
server for named tiles when the MimeList is not
specified.
The resolution of the tile images in dots per inch
(the number of individual dots that can be placed
within the span of one linear inch). The minimum
dpi you can define is 72, anything less would render
a poor quality image. If a value less than 72 is
defined, the service will throw an exception.
The rendering quality (anti-alias) of the tile images
generated. You can specify either Speed or Quality.
If MapRendering is not specified in either the
global configuration or in a named tile, the default
rendering quality is Speed.
Tells the service not to render LabelLayers when
generating a tile. The value is case-insensitive. If
RenderLabels is not specified in either the global
configuration or in a named tile, the default is 'true'.
Used to prevent the clipping of labels when a label
crosses a tile boundary. The PadFactor controls
the amount of space is rendered around the requested
tile with 0 meaning no padding, 1 meaning
padding of 1 tile around the requested tile and so
on. If PadFactor is not specified in either the
global configuration or in a named tile, the default
is 1.0.
Internally, the Map Tiling service draws tiles to an offscreen bitmap (OSBM) (e.g., BufferedImage). To
help speed up rendering of tiles by reducing garbage collection pauses, pools of offscreen bitmaps may
be used to avoid constantly creating new ones. The OSBMPooling configuration controls how the offscreen
bitmaps are created in memory.
Note:
If the OSBM pooling section of the configuration is removed, then pooling will not be enabled.
The following are OSBM configuration paramters:
Parameter
MaxActive
Map Tiling Service Guide
Type
integer
Chapter 2: Managing Map Tiling Resources and Configuration
Required
no
Description
Controls the maximum number of offscreen bitmaps
(per tile dimension) that can be allocated by the
pool (checked out to client threads, or idle in the
pool) at one time. When non-positive, there is no
limit to the number of objects per key. When this
value is reached, the keyed pool is said to be ex-
9

Global Configuration Parameters
10
Parameter
MinIdle
MaxIdle
MaxTotal
ExhaustedAction
Type
integer
integer
integer
string
Required
no
no
no
no
Description
hausted. The default setting for this parameter is
8.
The minimum number of idle offscreen bitmaps
(per tile dimension) that should always be available.
If this parameter is set to a positive number and
TimeBetweenEvictionRunsMills is greater
than zero, each time the idle object eviction thread
runs, it will try to create enough idle instances so
that there will be this number of idle instances
available under each key. The default setting for
this parameter is 0.
The maximum number of offscreen bitmap that can
sit idle in the pool (per tile dimension) at any time.
When negative, there is no limit to the number of
objects that may be idle per key. The default setting
for this parameter is 8.
The global limit on the number of objects that can
be in circulation (active or idle) within the combined
set of pools. When non-positive, there is no limit to
the total number of objects in circulation. When
MaxTotal is exceeded, all keyed pools are exhausted.
When MaxTotal is set to a positive value
and an offscreen bitmap is requested when at the
limit with no idle instances available, an attempt is
made to create room by clearing the oldest fifteen
percent (15%) of the elements from the keyed
pools. The default setting for this parameter is -1
(no limit).
The behavior when the pool of offscreen bitmaps
is exhausted. The options are fail, grow, or block.
Fail will throw an exception when an offscreen bitmap
is requested when the pool is exhausted.
Grow, the default, will create a new offscreen bitmap
and return it, making MaxActive meaningless.
Block will stop the process until a new or idle
object is available.
Optionally, one may configure the pool to examine
and possibly evict objects as they sit idle in the pool
and to ensure that a minimum number of idle objects
is maintained for each key. This is performed
by an idle object eviction thread, which runs asynchronously.
Caution should be used when configuring
this optional feature.
Eviction runs require an exclusive synchronization
lock on the pool. If they run too frequently or incur
excessive latency when creating, destroying or
validating object instances, performance issues
MapInfo Spatial Server 1.0

Parameter
MinEvictableIdle-
TimeMills
TimeBetweenEvictionRunsMills
Type
integer
integer
Required
no
no
Description
Uploading and Accessing Resources in the Repository
may result. The idle object eviction thread may be
configured using the MinEvictableIdleTime-
Mills and TimeBetweenEvictionRunsMills
parameters.
The minimum amount of time that an offscreen
bitmap may sit idle in the pool before it is eligible
for eviction due to idle time. When non-positive, no
object will be dropped from the pool due to idle time
alone. This parameter has no effect unless TimeBetweenEvictionRunsMillis
is greater than
zero. The default setting for this parameter is 30
minutes.
How long the eviction thread should sleep before
examining idle offscreen bitmaps. When non-posit-
ive, no eviction thread will be launched. The default
setting for this parameter is -1 (i.e., by default, idle
object eviction is disabled).
Named resource files are stored in the repository. These files are located at http://localhost:8080/RepositoryService/repository/default/
under a particular folder. For example:
• NamedLayers
• NamedMaps
• NamedStyles
• NamedTables
• NamedTiles
You can access these files using two methods: the NamedResource service or manually using a WebDAV
compliant tool. This section describes the manual method. For more information on using the
NamedResource service, see the NamedResource Service SOAP Reference.
To access resources manually, you must use a WebDAV protocol tool to access the JCR repository.
There are many tools available to upload and access resources in the repository using the WebDAV.
We have provided two examples:
Using WebFolders to Access the Repository Resources
To add or modify a resource, you must copy the resource to or from the repository using a WebDAV
tool. Using WebFolders is an easy way to access the repository and the resources contained in the repository.
Note:
WebFolders is for Windows machines only. To access the repository, you must be on the same
machine where MapInfo Spatial Server and the repository are installed.
To configure a WebFolder:
Map Tiling Service Guide
Chapter 2: Managing Map Tiling Resources and Configuration
11

Uploading and Accessing Resources in the Repository
12
1. Using the Windows file explore, for the method appropriate for your version of Windows, select Map
Network Drive...
2. In the pop-up window, click on the link 'sign up for online storage or connect to a
network server' or you may have a link that mentions'Connect to a website...'.
3. Click the Next and select Choose another network location. Click Next.
4. In the Internet or network addressfield add the repository URL http://localhost:8080/RepositoryService/repository/default/.
Click Next.
5. If you are asked for cridentials, use the username and password Admin/Admin
6. Give this connection a name. For example, Spatial Server Repository. Click Next.
Once finished, you will have a folder connection to the contents of the repository under your network
places.
The WebFolder connection to the repository can be used like any other windows explorer folder, where
files can be copied from the repository, modified, and copied back to the same location in the repository.
Using DAVExplorer to Access the Repository Resources
To add or modify a resource, you must copy the resource to or from the repository using a WebDAV
tool. Using DavExplorer is an easy way to access the repository and the resources contained in the repository.
DAVExplorer is a freely available WebDAV client application. This software is available from
http://www.davexplorer.org.
Note:
DavExplorer is for Windows machines only. To access the repository, you must be on the same
machine where MapInfo Spatial Server and the repository are installed.
To get or add resources from the repository using DAVExplorer, use the following instructions:
Getting Resources From the Repository Using DAVExplorer
Use the following steps to get resources from the repository using DAV Explorer:
1. Open DAVExplorer.
2. In DAVExplorer, enter the URL of the MapInfo Spatial Server repository and click the Connect button.
For example, enter localhost:8080/RepositoryService/repository/default/. (Note
that DAVExplorer prepends http:// automatically.)
If prompted, enter the admin/admin login name and password required to connect to the repository.
Once you are connected to the repository, a node for the repository appears in the treeview pane
on the left.
3. In the treeview pane on the left, expand the nodes under the repository node until you see the node
that contains the type of resource you want to get.
For example, if the named resource you want to get is a configuration, expand the repository nodes
until you see the Configuration node. Click on the node to select it. The named configuration resources
in the repository are then listed in the right pane.
4. In the right pane, click on the resource you want to get.
You may click on any of the fields of the named resource to select it.
5. On the File menu, select Get File.
The Save As dialog box opens.
MapInfo Spatial Server 1.0

6. In the Save As dialog box, enter a name for the named resource definition file and select the directory
in which you want to save it, then click the Save button.
The selected named resource definition file is saved to the selected file location.
Note:
You should always save the resource as the same name as it appears in the repository. By
using this technique, you will never have a conflict when adding the resource back to the repository.
Adding Resources to the Repository Using DAVExplorer
Use the following steps to add resources to the repository using DAVExplorer:
1. Open DAVExplorer.
2. In DAVExplorer, enter the URL of the MapInfo Spatial Server repository and click the Connect button.
For example, enter localhost:8080/RepositoryService/repository/default/. (Note
that DAVExplorer prepends http:// automatically.)
If prompted, enter the admin/admin login name and password required to connect to the repository.
Once you are connected to the repository, a node for the repository appears in the treeview pane
on the left.
3. In the treeview pane on the left, expand the nodes under the repository node until you see the node
that corresponds to the type of resource you are adding.
For example, if you are adding a configuration resource, expand the repository nodes until you see
the Configuration node. Click on the node to select it.
4. On the File menu, select Write File.
The Write File dialog box opens.
5. In the Write File dialog box, select the definition file of the resource you want to add to the repository,
then click the Open button.
The selected resource is added to the repository.
Reload the Service Configuration using JMX Console
Once you have modified a service configuration, you must reload the configuration in the repository using
the JMX Console. The JMX console allows you to reload and administer a service, without having to
restart the application container.
To reload the service configuration:
1. Access the JMX Console using the following URL: http://localhost:8080/jmx-console/
2. Under the Domain: EnterpriseMapping section, select the administration link for the service.
For example, EnterpriseMapping:name=Administration,type=WMS Service.
3. Click the Invoke button for the reloadConfiguration operation.
You will get a message on the status of the invocation.
Map Tiling Service Guide
Chapter 2: Managing Map Tiling Resources and Configuration
13

Adding and Modifying Named Tiles
Adding and Modifying Named Tiles
The Map Tiling Service uses named tiles to render maps. The named tiles are stored in the repository
located in the NamedTiles directory under the root repository. For example, a default installation will
place the named tile definition files at http://localhost:8080/RepositoryService/repository/default/NamedTiles
To add or modify named tiles in the repository, perform the following:
1. You must be located on the local machine hosting MapInfo Spatial Server and the repository.
2. Use a standard WebDAV protocol tool to access the repository (e.g., Windows WebFolders, DAVExplorer,
etc.) and either add or copy the named tiles to or from the repository.
For examples of using standard WebDAV tools, see Accessing the Repository using WebDAV
Named tiles do not have a file extention, only a name. For a description of the parameters to define
named tiles, see:
Defining Named Tiles
14
Named tiles are stored in the repository, and define how an individual hosted named map is used by the
Map Tiling Service. For each map you want to expose through the Map Tiling Service you must have
an equivalent named tile. In the named tile file, the NamedTile element contains the parameters that
define the named tile, each of which contains some or all of the following list of child elements:
Parameter
DisplayName
Description
ResourceLocation
Projection
Type
string
string
string
string
Required
yes
yes
yes
yes
Description
The alias of the named map stored in the map repository.
This alias can be different than the actual
name of the named map, and will be used in the
tiling service requests to call the named tile.
The metadata description of the named map. This
information is presented to the user when a getDescription
call is sent to the Map Tiling Service.
The directory and name of the actual named map
in the repository, from the repository base. For ex-
ample, if the named map is located at http://localhost:8080/RepositoryService/repository/default/NamedMaps/World,
then you would define
the ResourceLocation as /NamedMaps/World.
Note:
You must specify the starting '/'
The coordinate system projection to host the named
map. The Map Tiling Service will transform the
named map into the projection defined. The projection
is defined using the EPSG format.
MapInfo Spatial Server 1.0

Parameter
MinimumLevel
MaximumLevel
TileWidth
Bounds
MimeList
ExpirationDate
MapResolution
MapRendering
RenderLabels
PadFactor
Map Tiling Service Guide
Type
integer
integer
integer
string
string
string
integer
string
boolean
integer
Chapter 2: Managing Map Tiling Resources and Configuration
Required
yes
yes
yes
yes
no
no
no
no
no
no
Description
The minimum zoom level to host the map. Must be
greater than zero. See What Is Level? on page
16 for information to help define the level.
The maximum zoom level to host the map. Must
be greater than zero. See What Is Level? on page
16 for information to help define the level.
Width of a tile in pixels. Must be greater than or
equal to 16 and must be a number that can be
calculated from a 2 n equation (for example 2 4 =16,
2 5 =32, 2 8 =256).
The bounds of the map. Coordinates are comma
separated and in the coordinate system specified
by the projection option.
The available types of tiles generated by the tile
server for this map only.
The date on which the client should delete the map
tile from the cache, and request a new copy from
the server. The ExpirationDate value must be
specified as a W3C formatted date string.
Note:
The ExpirationDate parameter has effect
only when using external caching software
such as Squid or Apache.
The resolution of the tile images in dots per inch
(the number of individual dots that can be placed
within the span of one linear inch). If not specified,
the GlobalMapResolution is used. The minimum
dpi you can define is 72, anything less would render
a poor quality image. If a value less than 72 is
defined, the service will throw an exception.
The rendering quality (anti-alias) of the tile images
generated. You can specify either Speed or Quality.
If a MapRendering preference is not specified,
the global preference in the configuration will be
used to determine the maps rendering quality. If
neither is specified, the default rendering quality is
Speed.
Tells the service not to render LabelLayers when
generating a tile. The value is case-insensitive. If
a RenderLabels preference is not specified, the
global preference in the configuration will be used.
If neither is specified, the default is 'true'.
Used to prevent the clipping of labels when a label
crosses a tile boundary. The PadFactor controls
the amount of space is rendered around the reques-
15

Defining Named Tiles
16
Parameter
Type
Required
The following is an example named tile definition:
Description
ted tile with 0 meaning no padding, 1 meaning
padding of 1 tile around the requested tile and so
on. If a PadFactor preference is not specified, the
global preference in the configuration will be used.
If neither is specified, the default is 1.0.
World
Map Of The World
/NamedMaps/WorldMap
epsg:3857
1
20
256
-20037508.34,-20037508.34,20037508.34,20037508.34
image/png
image/jpeg
image/gif
2019-12-31
96
Speed
false
1.0
What Is Level?
The level, in combination with the tile width, tile height, and bounds of the named map, determines the
zoom level of the tiles to be returned. The level shows how close the map image is to the Earth. Level
1 is the furthest away and is composed of one tile that the entire map will be drawn into. Level 2 is
composed of 4 tiles, 2 across and 2 down. Each tile is a quarter of the entire map. Level 3 is composed
of 16 tiles, 4 across and 4 down, and so on. The higher the level specified, the closer to the Earth the
map image appears. For example, levels 1 to 3 usually show global or hemispheric detail, levels 4 to 15
show county/state/province level of detail and some larger cities, levels greater that 15 show street level
views.
What the levels actually display is dependant on the named map hosted by the Map Tile Service. For
example, a level of 1 for a world map would be zoomed out to show the entire world. However, if you
have a named map of only a city (for example, New York, Toronto, or London), a level of 1 would be
zoomed out to show a street level map.
How Tile Height Is Calculated
The tile height is calculated from the map bounds and the tile width to produce a tile that has the same
aspect ratio as the bounds.
The tile height is calculated using the following equation:
tileHeight = (boundsHeight ÷ boundsWidth) × tileWidth
MapInfo Spatial Server 1.0

There is one restriction when defining a map: the resultant tile height must be a whole number (integer).
Since tile height and tile width are calculated in pixels, it is impossible for a user to display these values
as fractions of a pixel.
For example, a map with a bounds of (-180, -90, 180, 90) in WGS84 has an aspect ratio (width to height)
of 2:1. So the tileHeight calculation is half the tileWidth. If you defined the tileWidth parameter
to be 256 then the tileHeight would be 128. This is an acceptable tileHeight value. However, if
you have defined a map with the bounds of (-180, -90, 90, 0) in WGS84, that would create an aspect
ratio of 3:1. Calculating the tileHeight based on a tileWidth of 256 would result in a tileHeight
of 85.3333333. This is not an acceptable tileHeight value, and will not be displayed by the Map Tiling
Service. If a map hosted by the Map Tiling Service is configured with tileWidth and bounds parameter
settings that result in an invalid tileHeight calculation, then the map will not appear in the list of
available maps returned by a call to the getMaps method in the Map Tiling Interface.
Map Tiling Service Guide
Chapter 2: Managing Map Tiling Resources and Configuration
17

Map Tiling REST Interface
This chapter describes the Map Tiling REST Interface for the Map Tiling Service.
You can use this interface in your application code to access the Map Tiling Service.
In this section:
• What Is the Map Tiling REST Interface? . . . . . . . . . . . . . .20
• REST URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
• Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
• Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
3

What Is the Map Tiling REST Interface?
What Is the Map Tiling REST Interface?
The Map Tiling REST Interface is a web RESTfull interface for quickly accessing the Map Tiling Service
from within your web applications. The Map Tiling Service generates tiles that can be combined to form
larger map images. These tiles can be cached by the service or by other web caching solutions to reduce
the waiting times as users view, pan, and zoom Envinsa maps.
The Map Tiling Service provides functionality for clients to determine the maps that are available, the
ability to query the metadata of each map, and return a map comprised of tiles.
REST URL
The URL of a REST Map Tiling Interface request has the following form:
http://host[:port]/rest/EnterpriseMapping/MapTilingService/paramValue1/paramValue2/methodName.json
Methods
MapList
20
This section describes the methods that are available in the Map Tiling REST Interface.
Description
Returns the list of available named tiles for the Map Tiling Service. Only the tiles listed in the response
can have tiles generated.
Note:
Before sending any requests to the Map Tiling Service, it is good practice to send a MapList
request to determine the available tiles of the service.
HTTP GET URL Format
The following format is used for HTTP GET requests:
HTTP GET /mapList.json
Parameters
The mapList method does not have any input parameters. You only need to specify mapList.json as the
REST parameter.
MapInfo Spatial Server 1.0

Example
http://localhost:8080/rest/EnterpriseMapping/MapTilingService/mapList.json
The following example shows the format of the JSON object returned in the response:
{"Response":["/NamedTiles/WorldTile","/NamedTiles/UKCountriesTile"]}
Returns
An array of String values returned in a JSON response object. This is the list of available named maps
for the Map Tiling Service.
Description
Description
Returns the metadata of a specified named tile for the Map Tiling Service.
HTTP GET URL Format
The following format is used for HTTP GET requests:
HTTP GET /{mapname}/description.json
Parameters
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
mapname
Example
Type
String
Required
yes
Description
The name of the named tile to return the metadata
for. You must specify the path inside the repository
where the named tile is located.
http://localhost:8080/rest/EnterpriseMapping/MapTilingService/NamedTiles/WorldTile/description.json
The following example shows the format of the JSON object returned in the response:
{"Response":{"numberOfLevels":20,"coordSys":"epsg:41001","description":"Map
Of The World","mapName":"World","tileWidth":256,"tile-
Height":256,"bounds":{"maxX":2.0E7,"maxY":2.0E7,"minX":-2.0E7,"minY":-
2.0E7},"outputTypes":["image/png","image/jpeg","image/gif"],"mapResolution":110,"mapRendering":"SPEED"}}
Map Tiling Service Guide
Chapter 3: Map Tiling REST Interface
21

Tile
Tile
22
Returns
A MapDescription object. See MapDescription on page 24.
Description
Returns generated map tiles from the Map Tiling Service based on the input parameters specified.
HTTP GET URL Format
The following format is used for HTTP GET requests:
HTTP GET /{mapname}/{level}/{x}:{y}/tile.{image type}
Parameters
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
mapname
level
Type
String
Integer
Required
yes
yes
Description
The name of the named tile to generate the tile
from. You must specify the location inside the repository
where the named tile is located.
Determines the zoom level of the tile to be returned.
The level shows how close the map image is to the
Earth. Level 1 is the furthest away and is composed
of one tile that the entire map will be drawn into.
Level 2 is composed of 4 tiles, 2 across and 2
down. Each tile is a quarter of the entire map. Level
3 is composed of 16 tiles, 4 across and 4 down,
and so on. The higher the level specified, the closer
to the Earth the map image appears. For example,
levels 1 to 3 usually show global or hemispheric
detail, levels 4 to 15 show county/state/province
level of detail and some larger cities, levels greater
that 15 show street level views.
What the levels actually display is dependant on
the named map published to the Map Tile Service.
For example, if you published a map of New York,
Toronto, or London then level 1 would be a street
level map of Toronto while high levels would be
more detailed.
This parameter must be set to a value greater than
or equal to the minLevel value and less than or
equal to the maxLevel value for the named map.
MapInfo Spatial Server 1.0

Parameter
x
y
.{image type}
Returns
A map image.
Type
Integer
Integer
Image Mime
Required
yes
yes
yes
Description
A JSON error will be returned if one of the following conditions are met:
• The mapname parameter is not specified.
Specifies the column of the tile, based on the
level parameter specified.
• The name specified is not an available named map on the Tiling Service.
Specifies the row of the tile, based on the level
parameter specified.
Specifies the response image format. Must be png,
gif, or jpeg.
• The level parameter is less than the minlevel defined in the metadata for the specified map.
• The level parameter is greater than the maxlevel defined in the metadata for the specified map.
• The x parameter is less than 1.
• The x parameter is greater than what the level dictates the map can provide.
• The y parameter is less than 1
• The y parameter is greater than what the level dictates the map can provide.
Example
http://localhost:8080/rest/EnterpriseMapping/MapTilingService/NamedTiles/WorldTile/2/1:1/tile.png
The following example shows the image output returned in the response:
Map Tiling Service Guide
Chapter 3: Map Tiling REST Interface
23

Objects
Objects
This section describes the JSON objects that are returned in the response to a Map Tiling REST Interface
request.
MapDescription
24
A MapDescription object defines the metadata for a named map.
Fields
A MapDescription object contains the following fields:
Field Name
numberOfLevels
Type
Integer
Description
The maximum number of levels (zoom in) that you
can request for the map. Level 1 is the furthest
away and is composed of one tile that the entire
map will be drawn into. Level 2 is composed of 4
tiles, 2 across and 2 down. Each tile is a quarter of
the entire map. Level 3 is composed of 16 tiles, 4
across and 4 down, and so on. The higher the level
MapInfo Spatial Server 1.0

Field Name
coordSys
description
name
tileWidth
tileHeight
bounds
outputTypes
Example
{
}
Type
CoordSys
String
String
Integer
Integer
Bounds object
Array of Strings
"numberOfLevels": 20,
"coordSys": "epsg:41001",
"description": "Map of the World",
"name": "World",
"tileWidth": 256,
"tileHeight": 256,
"bounds":{
"minX": -3.756380109844111E7,
"minY": -4.497601034176671E7,
"maxX": 3.773376466605809E7
"maxY": 4.49763662218225E7,
},
"outputTypes":
[
"png"
"jpeg"
"gif"
]
Map Tiling Service Guide
Description
Chapter 3: Map Tiling REST Interface
specified, the closer to the Earth the map image
appears (zoom in).
The coordinate system of the projection defining
the map tiles.
A textural description of the named map.
The name of the named map.
The width of the tiles in pixels.
The height of the tiles in pixels.
The geographical extent of the map's bounding box
in the map's projection as specified by the coord-
Sys field. See Bounds on page 48.
The list of supported tile image formats that can be
rendered for the map.
25

Legacy Map Tiling Interface
This chapter describes the Legacy Map Tiling Interface for the Map Tiling Service.
You can use this interface in your application code to access the Map Tiling Service.
In this section:
• What Is the Legacy Map Tiling Interface? . . . . . . . . . . . .28
• URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
• Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
• Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
4

What Is the Legacy Map Tiling Interface?
What Is the Legacy Map Tiling Interface?
The Legacy Map Tiling Interface is a programming interface for accessing the Map Tiling Service from
within your web applications.
Note:
URL
The Legacy Map Tiling interface is for backwards compatability only. This interface should not
be used to create new application using map tiling.
The URL of a Map Tiling Interface request has the following form:
http://host[:port]/rest/EnterpriseMapping/LegacyMapTilingService/methodName?paramName=paramValue
Methods
getMaps
28
This section describes the methods that are available in the Map Tiling Interface.
Description
Returns the list of available named named tiles for the Map Tiling Service. Only the tiles listed in the response
can have tiles generated.
Note:
Parameters
Before sending any requests to the Map Tiling Service, it is good practice to send a getMaps
request to determine the available tiles of the service.
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
output
Returns
Type
String
Required
yes
Description
Specifies the response format. Must be json.
An array of String values. This is the list of available named tiles for the Map Tiling Service.
When an array of tile name values is returned in the EnvinsaResponse JSON object, the array is always
located in a JSON field named maps.
MapInfo Spatial Server 1.0

Example
http://localhost:8080/rest/EnterpriseMapping/LegacyMapTilingService/getMaps?
output=json
The following example shows the format of the JSON object returned in the response:
{
}
getDescription
"EnvinsaResponse":
{
"type": "MapTilingResponse",
"maps":
[
"World",
"High"
]
}
Description
Returns the metadata of a specified named tile for the Map Tiling Service.
Parameters
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
name
output
Returns
Type
String
String
Required
yes
yes
Description
A MapDescription object. See MapDescription on page 40.
Example
The name of the named tile to return the metadata
for. You must specify the location of the named tile
in the repository.
Specifies the response format. Must be json.
http://localhost:8080/rest/EnterpriseMapping/LegacyMapTilingService/getDescription?
name=/NamedTiles/WorldTile
&output=json
Map Tiling Service Guide
Chapter 4: Legacy Map Tiling Interface
29

getLevelDescription
getLevelDescription
30
Description
Returns the number of map tiles across (on the x axis) and the number of map tiles down (on the y axis),
and the width and height in virtual pixels of the map image created in memory, for a specified map zoom
level.
Parameters
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
name
level
output
Returns
Type
String
Integer
String
Required
yes
yes
yes
Description
A LevelDescription object. See LevelDescription on page 42.
Example
Specifies the name of the named tile for which the
level description is to be returned. You must specify
the location of the named tile in the repository.
Specifies the zoom level for which the description
is to be returned.
This parameter must be set to a value greater than
or equal to the minLevel value and less than or
equal to the maxLevel value for the named map.
You can determine these values by calling the
getDescription method and examining the returned
MapDescription object. For more information, see
getDescription on page 29 and MapDescription
on page 40.
Specifies the response format. Must be json.
http://localhost:8080/rest/EnterpriseMapping/LegacyMapTilingService/getLevel-
Description?
name=/NamedTiles/WorldTile
&level=4
&output=json
MapInfo Spatial Server 1.0

getTile
Description
Returns generated map tiles from the Map Tiling Service based on the input parameters specified.
Parameters
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
name
level
col
Map Tiling Service Guide
Type
String
Integer
Integer
Required
yes
yes
yes
Description
Chapter 4: Legacy Map Tiling Interface
Specifies the name of the named tile from which
the tile is generated. You must specify the location
in the repository for the named tile.
Determines the zoom level of the tile to be returned.
The level shows how close the map image is to the
Earth. Level 1 is the furthest away and is composed
of one tile that the entire map will be drawn into.
Level 2 is composed of 4 tiles, 2 across and 2
down. Each tile is a quarter of the entire map. Level
3 is composed of 16 tiles, 4 across and 4 down,
and so on. The higher the level specified, the closer
to the Earth the map image appears. For example,
levels 1 to 3 usually show global or hemispheric
detail, levels 4 to 15 show county/state/province
level of detail and some larger cities, levels greater
that 15 show street level views.
What the levels actually display is dependant on
the named map published to the Map Tile Service.
For example, the levels demonstrated above are
for Envinsa's High named map. If you published a
map of New York, Toronto, or London then level 1
would be a street level map of Toronto while high
levels would be more detailed.
This parameter must be set to a value greater than
or equal to the minLevel value and less than or
equal to the maxLevel value for the named map.
You can determine these values by calling the
getDescription method and examining the returned
MapDescription object. For more information, see
getDescription on page 29 and MapDescription
on page 40.
Specifies the column of the tile, based on the
level parameter specified.
31

getTile
32
Parameter
row
output
Returns
A map image.
Type
Integer
String
Required
yes
yes
Description
A JSON error will be returned if one of the following conditions are met:
• The name parameter is not specified.
• The name specified is not an available named map on the Tiling Service.
Specifies the row of the tile, based on the level
parameter specified.
Specifies the response image format. Must be png,
gif, or jpg.
• The level parameter is less than the minlevel defined in the metadata for the specified map.
• The level parameter is greater than the maxlevel defined in the metadata for the specified map.
• The col parameter is less than 1.
• The col parameter is greater than what the level dictates the map can provide.
• The row parameter is less than 1
• The row parameter is greater than what the level dictates the map can provide.
Example
http://localhost:8080/rest/EnterpriseMapping/LegacyMapTilingService/getTile?
name=/NamedTiles/WorldTile
&level=2
&col=1
&row=1
&dpi=96
&output=png
The following example shows the image output returned in the response:
MapInfo Spatial Server 1.0

getTileBounds
Description
Returns the geographic bounds of a specified map tile. The bounds are expressed in terms of the map's
coordinate system.
Parameters
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
name
level
Map Tiling Service Guide
Type
String
Integer
Required
yes
yes
Description
Chapter 4: Legacy Map Tiling Interface
Specifies the name of the named tile from which
the tile is generated. You must specify the location
in the repository for the named tile.
Specifies the zoom level of the tile whose bounds
are to be returned.
This parameter must be set to a value greater than
or equal to the minLevel value and less than or
equal to the maxLevel value for the named map.
You can determine these values by calling the
getDescription method and examining the returned
MapDescription object. For more information, see
33

convertScreenToMapCoord
Parameter
row
col
output
Returns
Type
Integer
Integer
String
Required
yes
yes
yes
Description
getDescription on page 29 and MapDescription
on page 40.
Specifies the grid row number of the map tile whose
bounds are to be returned.
Specifies the grid column number of the map tile
whose bounds are to be returned.
Specifies the response format. Must be json.
A Bounds object located in a JSON field named tileBounds. See Bounds on page 48.
Example
http://localhost:8080/rest/EnterpriseMapping/LegacyMapTilingService/getTile-
Bounds?
name=/NamedTiles/WorldTile
&level=4
&row=1
&col=1
&output=json
convertScreenToMapCoord
34
Description
Converts a specified set of screen pixel coordinates to coordinates in the map's coordinate system, and
returns them.
Parameters
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
name
Type
String
Required
yes
Description
Specifies the name of the named map for which
you are converting coordinates.
MapInfo Spatial Server 1.0

Parameter
level
screenX
screenY
view
output
Example
Type
Integer
Integer
Integer
Bounds
String
Required
yes
yes
yes
yes
yes
Description
Specifies the map zoom level.
This parameter must be set to a value greater than
or equal to the minLevel value and less than or
equal to the maxLevel value for the named map.
You can determine these values by calling the
getDescription method and examining the returned
MapDescription object. For more information, see
getDescription on page 29 and MapDescription
on page 40.
Specifies the x coordinate value of the point in the
view to be converted. This point is specified from
the upper left corner of the view in pixels.
Specifies the y coordinate value of the point in the
view to be converted. This point is specified from
the upper left corner of the view in pixels.
Specifies the geographic bounds of the view that
displays the map, expressed in terms of the map's
coordinate system.
Specifies the response format. Must be json.
http://localhost:8080/rest/EnterpriseMapping/LegacyMapTilingService/convertScreenToMapCoord?
name=/NamedTiles/WorldTile
&level=4
&screenX=100
&screenY=100
&view=-20000000,20000000,20000000,-20000000
&output=json
The above example will return the following JSON response object:
{"EnvinsaResponse":{"mapCoord":{"coordSys":"epsg:41001","point":{"x":-
1.8045920859794818E7,"y":1.8045920859794818E7}},"type":"MapTilingResponse"}}
Returns
A MapCoordinate object as seen in the above sample. See MapCoordinate on page 43.
Map Tiling Service Guide
Chapter 4: Legacy Map Tiling Interface
35

convertScreenToTileCoord
convertScreenToTileCoord
36
Description
Returns the row and column number of the map tile in which a specified screen pixel lies.
Parameters
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
name
level
screenX
screenY
view
output
Example
Type
String
Integer
Integer
Integer
Bounds
String
Required
yes
yes
yes
yes
yes
yes
Description
Specifies the name of the named map.
Specifies the map zoom level.
This parameter must be set to a value greater than
or equal to the minLevel value and less than or
equal to the maxLevel value for the named map.
You can determine these values by calling the
getDescription method and examining the returned
MapDescription object. For more information, see
getDescription on page 29 and MapDescription
on page 40.
Specifies the x coordinate value of the point in the
view used to select the tile. This point is specified
from the upper left corner of the view in pixels.
Specifies the y coordinate value of the point in the
view used to select the tile. This point is specified
from the upper left corner of the view in pixels.
Specifies the geographic bounds of the view that
displays the map, expressed in terms of the map's
coordinate system.
Specifies the response format. Must be json.
http://localhost:8080/rest/EnterpriseMapping/LegacyMapTilingService/convertScreenToTileCoord?
MapInfo Spatial Server 1.0

name=/NamedTiles/WorldTile
&level=4
&screenX=100
&screenY=100
&view=-20000000,20000000,20000000,-20000000
&output=json
The above example will return the following JSON response object:
{"EnvinsaResponse":{"tileCoord":{"column":1,"row":1},"type":"MapTilingResponse"}}
Returns
A TileCoordinate object as seen in the above sample. See TileCoordinate on page 43.
convertMapToTileCoord
Description
Returns the row and column number of the map tile in which a specified set of map coordinates lies.
Parameters
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
worldX
worldY
Map Tiling Service Guide
Type
Float
Float
Required
yes
yes
Description
Chapter 4: Legacy Map Tiling Interface
Specifies the x coordinate of the map's point location.
The map location is specified in terms of the units
of the map coordinate system (for example, degrees
or meters). You can determine the coordinate
system of the map by calling the convertScreen-
ToMapCoord method and examining the returned
MapCoordinate object. For more information, see
convertScreenToMapCoord on page 34 and
MapCoordinate on page 43.
Specifies the y coordinate of the map's point location.
The map location is specified in terms of the units
of the map coordinate system (for example, degrees
or meters). You can determine the coordinate
system of the map by calling the convertScreen-
ToMapCoord method and examining the returned
MapCoordinate object. For more information, see
37

convertMapToVirtualPixelCoord
Parameter
level
name
output
Example
Type
Integer
String
String
Required
yes
yes
yes
Description
convertScreenToMapCoord on page 34 and
MapCoordinate on page 43.
Specifies the map zoom level.
This parameter must be set to a value greater than
or equal to the minLevel value and less than or
equal to the maxLevel value for the named map.
You can determine these values by calling the
getDescription method and examining the returned
MapDescription object. For more information, see
getDescription on page 29 and MapDescription
on page 40.
Specifies the name of the named map from which
the map tiles are generated.
Specifies the response format. Must be json.
http://localhost:8080/rest/EnterpriseMapping/LegacyMapTilingService/convert-
MapToTileCoord?
name=/NamedTiles/WorldTile
&level=4
&worldX=-79.377366
&worldY=43.64713
&output=json
The above example will return the following JSON response object:
{"EnvinsaResponse":{"tileCoord":{"column":4,"row":4},"type":"MapTilingResponse"}}
Returns
A TileCoordinate object as seen in the above example. See TileCoordinate on page 43.
convertMapToVirtualPixelCoord
38
Description
Converts a specified set of map coordinates to coordinates in the virtual pixel space of the entire map
image, and returns them.
Note:
Do not confuse coordinates in the virtual pixel space of the entire map image with normal screen
pixel coordinates. Normal screen pixel coordinates always start with (0, 0) at the top left corner
MapInfo Spatial Server 1.0

Parameters
of the screen, regardless of what section of the entire map image is currently displayed in the
screen. In contrast, the virtual pixel space of the map image is constant at any particular zoom
level, regardless of what part of the map is currently displayed in the screen. So, for example, if
a map image is set to zoom level 3, the map image is composed of 4 tiles across and 4 tiles
down. If each tile has dimensions of 512 by 256 pixels, then the dimensions of the entire map
image are 2048 by 1024 pixels. This is referred to as the virtual pixel space of the map image,
because only a subsection of the entire image may be displayed in the screen at any one time.
For information on the parameter types listed below, see Request URL Data Types on page 46.
Parameter
worldX
worldY
level
Map Tiling Service Guide
Type
Float
Float
Integer
Required
yes
yes
yes
Description
Chapter 4: Legacy Map Tiling Interface
Specifies the x coordinate of the map's point location.
The map location is specified in terms of the units
of the map coordinate system (for example, degrees
or meters). You can determine the coordinate
system of the map by calling the convertScreen-
ToMapCoord method and examining the returned
MapCoordinate object. For more information, see
convertScreenToMapCoord on page 34 and
MapCoordinate on page 43.
Specifies the y coordinate of the map's point location.
The map location is specified in terms of the units
of the map coordinate system (for example, degrees
or meters). You can determine the coordinate
system of the map by calling the convertScreen-
ToMapCoord method and examining the returned
MapCoordinate object. For more information, see
convertScreenToMapCoord on page 34 and
MapCoordinate on page 43.
Specifies the map zoom level.
This parameter must be set to a value greater than
or equal to the minLevel value and less than or
equal to the maxLevel value for the named map.
You can determine these values by calling the
getDescription method and examining the returned
MapDescription object. For more information, see
getDescription on page 29 and MapDescription
on page 40.
39

Objects
Parameter
name
output
Example
Type
String
String
Required
yes
yes
Description
Specifies the name of the named map from which
the map tiles are generated.
Specifies the response format. Must be json.
http://localhost:8080/rest/EnterpriseMapping/LegacyMapTilingService/convert-
MapToVirtualPixelCoord?
name=/NamedTiles/WorldTile
&level=4
&worldX=-79.377366
&worldY=43.64713
&output=json
The above example will return the following JSON response object:
{"EnvinsaResponse":{"type":"MapTilingResponse","virtualPixelCoord":{"virtualX":1023,"virtualY":1023}}}
Returns
A VirtualPixelCoordinate object as seen in the above example. See VirtualPixelCoordinate on page
44.
Objects
This section describes the JSON objects that are returned in the response to a Map Tiling Interface request.
MapDescription
40
A MapDescription object defines the metadata for a named map.
When a MapDescription object is returned in an EnvinsaResponse JSON object, the MapDescription
object is always located in a JSON field named description.
Fields
A MapDescription object contains the following fields:
Field Name
maxLevel
Type
Integer
Description
The maximum level (zoom in) that you can request
for the map. Level 1 is the furthest away and is
MapInfo Spatial Server 1.0

Field Name
minLevel
coordSys
description
name
tileWidth
tileHeight
bounds
outputTypes
Example
{
Type
Integer
CoordSys
String
String
Integer
Integer
Bounds object
Array of Strings
"maxLevel": 20,
"coordSys": "epsg:41001",
"minLevel": 1,
"description": "Map of the World",
"name": "World",
"tileWidth": 256,
"tileHeight": 256,
"bounds":
{
"minX": -3.756380109844111E7,
"minY": -4.497601034176671E7,
"maxX": 3.773376466605809E7
"maxY": 4.49763662218225E7,
},
Map Tiling Service Guide
Description
Chapter 4: Legacy Map Tiling Interface
composed of one tile that the entire map will be
drawn into. Level 2 is composed of 4 tiles, 2 across
and 2 down. Each tile is a quarter of the entire map.
Level 3 is composed of 16 tiles, 4 across and 4
down, and so on. The higher the level specified,
the closer to the Earth the map image appears
(zoom in). The maximum zoom level is set in the
MaximumLevel configuration parameter for the
Map Tiling Service. See Configuring the Map
Tiling Service for more information.
The minimum level (zoom out) that you can request
for the map. The minimum zoom level is set in the
MinimumLevel configuration parameter for the
Map Tiling Service. See Configuring the Map
Tiling Service for more information.
The coordinate system of the projection defining
the map tiles.
A textural description of the named map.
The name of the named map.
The width of the tiles in pixels.
The height of the tiles in pixels.
The geographical extent of the map's bounding box
in the map's projection as specified by the coord-
Sys field. See Bounds on page 48.
The list of supported tile image formats that can be
rendered for the map.
41

LevelDescription
}
"outputTypes":
[
"png"
"gif"
"jpeg"
]
LevelDescription
42
A LevelDescription object contains information about the number of map tiles on the horizontal and
vertical axes, and the width and height in virtual pixels of the map image created in memory, for a given
map zoom level.
When a LevelDescription object is returned in an EnvinsaResponse JSON object, the LevelDescription
object is always located in a JSON field named levelDescription.
Fields
A LevelDescription object contains the following fields:
Field Name
tileAcross
tileDown
virtualImageHeight
virtualImageWidth
Type
Integer
Integer
Integer
Integer
Description
The number of map tiles on the horizontal axis in
this zoom level.
The number of map tiles on the vertical axis in this
zoom level.
The height of the map image created in memory,
measured in the virtual pixel space of the entire
map image. (See note below.)
The width of the map image created in memory,
measured in the virtual pixel space of the entire
map image. (See note below.)
Note: Do not confuse coordinates in the virtual pixel space of the entire map image with normal screen
pixel coordinates. Normal screen pixel coordinates always start with (0, 0) at the top left corner
of the screen, regardless of what section of the entire map image is currently displayed in the
screen. In contrast, the virtual pixel space of the map image is constant at any particular zoom
level, regardless of what part of the map is currently displayed in the screen. So, for example, if
a map image is set to zoom level 3, the map image is composed of 4 tiles across and 4 tiles
down. If each tile has dimensions of 512 by 256 pixels, then the dimensions of the entire map
image are 2048 by 1024 pixels. This is referred to as the virtual pixel space of the map image,
because only a subsection of the entire image may be displayed in the screen at any one time.
Example
{
"tileAcross": 2,
MapInfo Spatial Server 1.0

}
MapCoordinate
"tileDown": 2,
"virtualImageHeight": 512,
"virtualImageWidth": 512
A MapCoordinate object contains the map coordinates for a location, and the coordinate system in which
they are expressed.
When a MapCoordinate object is returned in an EnvinsaResponse JSON object, the MapCoordinate
object is always located in a JSON field named mapCoord.
Fields
A MapCoordinate object contains the following fields:
Field Name
point
coordSys
Example
{
}
TileCoordinate
Type
"point":
{
"x": -79.377366
"y": 43.64713,
},
coordSys": "epsg:4326"
Point object
CoordSys
Description
The point location expressed as map coordinates.
See Point on page 47.
The coordinate system of the location points.
A TileCoordinate object contains the row and column number of a map tile.
When a TileCoordinate object is returned in an EnvinsaResponse JSON object, the TileCoordinate object
is always located in a JSON field named tileCoord.
Fields
A TileCoordinate object contains the following fields:
Field Name
row
Map Tiling Service Guide
Type
Integer
Description
Chapter 4: Legacy Map Tiling Interface
The row number of the map tile. Row numbering
starts at the left, at number 1.
43

VirtualPixelCoordinate
Field Name
column
Example
{
}
"row": 1,
"column": 8
VirtualPixelCoordinate
44
Type
Integer
Description
The column number of the map tile. Column numbering
starts at the top, at number 1.
A VirtualPixelCoordinate object contains the x and y coordinates of a pixel in the virtual pixel space of
the entire map image.
Note: Do not confuse coordinates in the virtual pixel space of the entire map image with normal screen
pixel coordinates. Normal screen pixel coordinates always start with (0, 0) at the top left corner
of the screen, regardless of what section of the entire map image is currently displayed in the
screen. In contrast, the virtual pixel space of the map image is constant at any particular zoom
level, regardless of what part of the map is currently displayed in the screen. So, for example, if
a map image is set to zoom level 3, the map image is composed of 4 tiles across and 4 tiles
down. If each tile has dimensions of 512 by 256 pixels, then the dimensions of the entire map
image are 2048 by 1024 pixels. This is referred to as the virtual pixel space of the map image,
because only a subsection of the entire image may be displayed in the screen at any one time.
When a VirtualPixelCoordinate object is returned in an EnvinsaResponse JSON object, the VirtualPixel-
Coordinate object is always located in a JSON field named virtualPixelCoord.
Fields
A VirtualPixelCoordinate object contains the following fields:
Field Name
virtualX
virtualY
Example
{
}
"virtualX": 256,
"virtualY": 300
Type
Integer
Integer
Description
The x coordinate of the virtual pixel. The x coordinate
numbering starts at the left edge of the left-most
tile of the map image, at number 0.
The y coordinate of the virtual pixel. The y coordinate
numbering starts at the top edge of the top-most
tile of the map image, at number 0.
MapInfo Spatial Server 1.0

Common Data Types
This appendix describes the data types that can be passed as URL parameters
to a Map Tiling Interface method, and which may be contained in the returned
JSON object.
In this section:
• Request URL Data Types . . . . . . . . . . . . . . . . . . . . . . . . . .46
• Response JSON Data Types . . . . . . . . . . . . . . . . . . . . . . .47
A

Request URL Data Types
Request URL Data Types
46
The following table lists the common data types for URL parameters to a service method.
Although the method parameters (like all URL parameters) are essentially just strings, this table shows
how the various types of data must be formatted in the URL of the method call.
Note:
Name
Bounds
CoordSys
Country
Float
Integer
Language
LinearUnit
Point
Polygon
Rectangle
String
The 'value' portion of a method parameter 'name=value' pair is case sensitive.
Description
A comma-separated array of
four numbers of type Float.
A geographical coordinate
system.
An ISO country code.
A floating point number.
An integer number.
The language used for the
service method response.
A unit of measure for distance.
A point in 2D geometry.
A polygon geometry.
A rectangle geometry.
A string of characters that is
not required to be formatted
as one of the other data types
Format
float,float,float,float
EPSG format
2 or 3 character ISO
country code
[sign]integer.integer
[sign]integer
[ISO language
code]_[ISO country
code]
One of the following values:
M, DM, KM, FT,
YD, or MI.
Example
view=-180,-90,180,90
coordsys=EPSG:4269
country=CA
radius=6.25
maxCandidates=10
language=en_CA
distanceUnit=KM
An x and y value pair point=3.57%20-1.89
separated by a space.
Both x and y are Float
values. In the service request
URL, the space
separator is encoded as
'%20'.
An array of Points.
Points in the array are
separated by a comma
character.
An array of two Points.
The two Points in the array
are separated by a
comma character.
Any string of valid URLencoded
characters.
polygon=1.23%202.34,
3.45%204.56, ... ,
5.67%206.78
rectangle=1.23%202.34,
3.45%204.56
city=New%20York
MapInfo Spatial Server 1.0

Name
Description
in this table. An arbitrary
string value.
Format
Response JSON Data Types
Example
This section lists the common data types contained in the JSON objects that are returned in the response
to a service method request.
Note: Note that the data types listed below are distinct from JSON data types. The native JSON data
types are Number, String, Boolean, Array, Object, and null. The purpose of this table is to indicate
how the various Envinsa data types are formatted in the JSON fields, so you can handle them
correctly in your application code.
Primitive Types
The following table lists the primitive (non-object) data types that may be contained in the JSON response
objects.
Name
CoordSys
LinearUnit
Country
Object Types
Description
A geographical coordinate
system.
A unit of measure for distance.
An ISO country code.
Format
EPSG format
One of the following values:
M, DM, KM, FT,
YD, or MI.
2 or 3 character ISO
country code
Example
"coordSys": "EPSG:4269"
"distanceUnit": "M"
"country": "CAN"
This section describes the object data types that may be contained in the JSON response objects.
Point
A Point object represents a point in the 2D geometry of a geographic coordinate system.
Fields
A Point object contains the following fields:
Field Name
x
y
Map Tiling Service Guide
Type
Float
Float
Description
The x value of the point.
The y value of the point.
Appendix A: Common Data Types
47

Object Types
48
Example
{
}
"y": 43.64713,
"x": -79.377366
Bounds
A Bounds object defines the geographical extent of a map.
Fields
A Bounds object contains the following fields:
Field Name
minX
minY
maxX
maxY
Example
{
}
Type
Float
Float
Float
Float
"minX": -3.756380109844111E7,
"minY": -4.497601034176671E7,
"maxX": 3.773376466605809E7,
"maxY": 4.49763662218225E7
Description
The x value of the lower left point.
The y value of the lower left point.
The x value of the upper right point.
The y value of the upper right point.
MapInfo Spatial Server 1.0

Errors
This appendix describes the error codes that may be returned by the Envinsa
REST Interfaces, and the Error object in which the codes are returned.
In this section:
• Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
• Error Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
• Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
B

Handling Errors
Handling Errors
When making requests to the Envinsa REST Interfaces, errors may occur for a variety of reasons. When
they do occur, the interfaces return an Error object.
Before processing the response from an interface, your client application must first check whether the
returned JSON object is an Error object. If it is, your application can examine the contents of the object
to determine what type of error occurred, and then call the appropriate error handling code.
Error Object
An Error object can be identified by its type field, which is set to the String value Error. It has an error
field that contains the error details as an object. The object has the following fields:
Field Name
code
message
Type
String
String
Description
The error code.
The error message.
The following example illustrates the general form of an Error object:
{
}
"EnvinsaResponse":
{
"type": "Error",
"error":
{
"code": "8001",
"message": "Missing input parameter : point"
}
}
In the above example, the Error object contains an error code of 8001 and an error message of Missing
input parameter : point.
Error Codes
50
The following table lists the codes and messages for errors that may be generated by the Envinsa REST
Interfaces.
Note:
Errors that are generated by the Envinsa Web Services do not have an error number.
MapInfo Spatial Server 1.0

Code
8000
8001
8002
Message
Map Tiling Service Guide
Service error : message
Invalid parameter : message
Missing parameter : message
Description
Appendix B: Errors
A general error has occurred. The nature of the
error is indicated in the message text.
The request URL contained an invalid method
parameter value.
The request URL did not contain a required method
parameter.
51

How Pixels, Tiles, and Map
Coordinates are
Transformed
The following sections provide background information on the underlying process
used by the Map Tiling Interface methods to perform transformations between
pixels, tiles and coordinate systems. These transformations enable applications
to return, pan, zoom, and display the appropriate tile.
The Map Tiling Interface methods convertScreenToMapCoord, convertScreenToTileCoord,
convertMapToVirtualPixelCoord and convertMapToTileCoord
provide a much easier way to perform the transformations
described in the following sections. For information on these methods, see convertScreenToMapCoord
on page 34, convertScreenToTileCoord on page 36,
convertMapToVirtualPixelCoord on page 38 and convertMapToTileCoord on
page 37.
In this section:
• Transforming a Pixel to a Map Coordinate . . . . . . . . . . . .54
• Transforming a Pixel to a Tile Coordinate . . . . . . . . . . . .54
• Transforming a Map Coordinate to a Tile Coordinate . . .55
C

Transforming a Pixel to a Map Coordinate
Transforming a Pixel to a Map Coordinate
To pan or zoom a map based on tiles from the Map Tiling Service the client must have the ability to
convert a pixel to a location on the Earth. To do this the client must create an affine transform that when
given a coordinate in pixels returns a coordinate in the projection of the tiles. You need to know the
projection of the tiles, the bounds of the map being tiled, and the dimensions of a tile. Given this information
you must do the following:
1. Calculate the maximum number of tiles across that represents the map.
2. Calculate the maximum number of tiles down that represents the map.
3. Calculate the maximum number of pixels across that represents the map.
4. Calculate the maximum number of pixels down that represents the map.
5. Create an affine transform based on the bounds of the map and the bounds of the map in pixels.
6. Feed your location in pixels into the affine transform. The result will be a location on the earth in the
projection of the map.
To perform these steps, and transform a pixel into your map's coordinate system:
1. Calculate the maximum number of tiles across the map using the following equation: tilesAcross
= 2 level
2. Calculate the maximum number of tiles down the map using the following equation: tilesDown =
2 level
3. Calculate the number of pixels across the entire map using the following equation: pixelsAcross
= tileWidth × tileAcross
4. Calculate the number of pixels down the entire map using the following equation: pixelsDown =
tileHeight × tileDown
5. Given the bounds of the map in the map's projection and the bounds of the map in pixels an affine
transform from pixels to map coordinates can be constructed. The pixel coordinate passed must be
in the map's pixel space. It may not be enough to directly feed a pixel coordinate from a mouse location
on the screen. For instance, you may have to convert the mouse location to a location in the
map's pixel space. This involves keeping track of the location in map pixels space of the upper righthand
corner of the image control and offsetting the mouse location with that location.
The getDescription method provides all the information needed to construct the affine transform like
tileWidth, tileHeight, map projection, and map bounds. See getDescription on page 29.
Transforming a Pixel to a Tile Coordinate
54
To perform pan and zoom, and locate items in a particular map tile, you need to be able to determine
which tile a pixel is in. To do this the client must be able to calculate the column and row or the tile when
given a coordinate in pixels. To perform this step, and transform a pixel into a tile coordinate, you can
use the following calculations:
MapInfo Spatial Server 1.0

1. Calculate the tile column:
col = (pixelX ÷ tileWidth) + 1
2. Calculate the tile row:
row = (pixelY ÷ tileHeight) + 1
It is important to remember that the pixel location is relative to the map's pixel space and not the screen
space. It may not be enough to directly feed a pixel coordinate from a mouse location on the screen.
For instance, you may have to convert the mouse location to a location in the map's pixel space. This
involves keeping track of the location in map pixels space of the upper right-hand corner of the image
control and offsetting the mouse location with that location.
Transforming a Map Coordinate to a Tile Coordinate
Using the information specified in the section Transforming a Pixel to a Map Coordinate on page 54,
instead, reverse the affine transform and create a transform that goes from map coordinates to pixels.
Feed a coordinate in the map's projection into the affine transform and the result is a coordinate in the
map's pixel space. Next, apply the steps from the section Transforming a Pixel to a Tile Coordinate
on page 54 to convert the pixels from map space to a tile coordinate.
Map Tiling Service Guide
Appendix C: How Pixels, Tiles, and Map Coordinates are Transformed
55