xmap

XMap Operations

SOAP/JSON

Synchronous API

since 2.0
Operation Name Request Type Response Type Since Description
renderMap MapRequest MapResponse 2.0 Render image(s) of a map and return information on drawn Feature Layer data.
REST

tile

URL format: /services/rest/XMap/2.27/tile/{zoomLevel}/{x}/{y}
since 2.0

Render a single map tile according the concept of the Map Tile API. By means of different frameworks a map image can be composed of multiple tiles. These tiles can be cached and reused for drawing of similar sections of a map. Optionally it is possible to return textual information on drawn Feature Layer data. Therefore, this operation can return either an image directly or a structured response which contains the image and additional information on drawn Feature Layer data such as their positions and names.

Path Parameter Name Type Since Description
zoomLevel ZoomLevel (int) 2.0 Zoom level. Details about zoom levels are documented in the Map Tile API.
x int 2.0 Horizontal tile index.
y int 2.0 Vertical tile index.
Query Parameter Name Type Default Since Description
storedProfile Url (String) default 2.2 The name of the stored profile to use without its extension, e.g. silkysand. The corresponding file silkysand.xml must be available in the folder conf/profiles. Parent profiles must be located in the same folder.
layers String[] - 2.2 A comma-separated list of layers which will be displayed on the map. If this parameter is specified, layers enabled in the stored profile are ignored. These layers can be the base layers labels, transport, and background, or any of the supported Feature Layer themes such as PTV_TruckAttributes. If this parameter is not present, the layers defined by the stored profile are displayed. For more information see Integration of custom data and Displaying Feature Layer PTV_TruckAttributes.
contentType ContentType ContentType.IMAGE 2.10 Content type of the response which can be either IMAGE for retrieving a tile image directly or JSON to obtain a structured response in JSON format. In case of JSON content type, the incorporated image has a format provided by the following parameter.
imageFormat ImageFormat ImageFormat.PNG 2.10 Image format of the rendered tile. This can be PNG or JPG. In case of JPG, the backgrounds (like oceans and forests) must be part of the image content, because they guarantee an image without any transparent pixels. This is important, because for JPG semi-transparent pixels would be drawn in black erroneously. Therefore a ParameterConflictException is thrown in such a case.
size PhysicalPixel (Integer) 256 2.2 Width and height of the tile in pixels. The maximum allowed value is 8192.
timeConsideration TimeConsiderationScenario TimeConsideration ... 2.3 Specifies how to evaluate Feature Layer attributes which contain time restrictions. For time consideration scenario NONE the parameters for reference time and timespan are not evaluated. For SNAPSHOT and TIME_SPAN the reference time is required. The time span is needed for the TIME_SPAN scenarios. For detailed information about time consideration scenarios see time consideration.
referenceTime XMLGregorianCalendar - 2.3 The reference time at which Feature Layer attributes with time restrictions will be evaluated. The time format either has to conform to the notation of xs:dateTime such as 2015-12-24T12:00:00+01:00, or it has to be a datetime sequence without any delimiters nor time-zone specification such as 20151224T120000. If the time-zone offset is missing, the corresponding service tries to detect it by means of information available in the calling context. A detailed description of this behavior can be found in the technical concept time zones. It is recommended to always specify the time zone. If no reference time is set, the current UTC time is used.
timeSpan Duration (Double) 86400.0 2.3 The duration of time (in combination with reference time as start) at which Feature Layer attributes with time restrictions will be evaluated, defined in [s]. The value is rounded to whole seconds.
showOnlyRelevantByTime Boolean false 2.3 Specifies if the map shows all attributes regardless of relevance for time consideration (default), or only the attributes which are relevant for this time consideration scenario. For further details, see Relevance of Feature Layer attributes.
showCopyright Boolean false 2.6 If true it shows the copyright text in the lower right corner of the image. If not defined the default value is false and no copyright text is shown.
preferredRouteTypes CommaSeparatedListValue[] (String[]) - 2.5 The road networks to be preferred by the routing algorithm as a comma-separated list (only if the Feature Layer PTV_PreferredRoutes is enabled). The available types can be requested through the xRuntime service and are documented in the manual as layer-specific properties of the Feature Layer PTV_PreferredRoutes. If this parameter is not present, all types of PTV_PreferredRoutes are displayed.
userLanguage LanguageCode (String) - 2.3 The language of texts such as traffic-incident descriptions which are returned for contentType = JSON.
contentSnapshotId String - 2.8 Specifies the content snapshot to use. If no snapshot ID is set, the most recent content is used.
mapLanguage LanguageCode (String) - 2.10 The language used for geographic names that are part of the map. The default x-ptv-DFT means that names are given in the language spoken in that country or region.
scope ScopeName (String) - 2.20 A user defined scope for persistent data like Feature Layers.
drawIcons Boolean true 2.23 Specifies if the Feature Layer icons have to be drawn on the map.
iconReference Boolean false 2.23 Specifies if icon references should be returned with the features.
Response Type Description
raw-binary If parameter contentType = IMAGE, the image is returned as binary directly.
TileResponse For contentType = JSON, the response contains the image, furthermore additional information on drawn Feature Layer object data.
XServerException Default exception for all xServer operations. See subtypes of XServerFault for details.

Types

Feature

used by MapResponse, TileResponse
since 2.0

Contains all Feature Layer attributes of a road segment rendered in the map.

Field Name Type Required Default Since Description
id String no - 2.0 The ID of the feature, if present.
referenceCoordinate Coordinate no - 2.0 The reference point of the road segment in real world coordinates.
referencePixelPoint PixelPoint no - 2.0 The reference point of the road segment in pixel coordinates.
pixelBoundingBox PixelBoundingBox no - 2.0 The bounding box of the icon(s) in pixel coordinates. Empty if there is no icon.
iconReference String no - 2.23 The icon reference useful to request the icon through the xRuntime service.
themeId ThemeId (String) yes - 2.0 The ID of the Feature Layer theme to which this feature belongs to.
attributes KeyValuePair[] 0..* - 2.1 The list of attributes of a segment. For each attribute its type (key) and value is provided via key-value pairs. See the documentation of the layer-specific attributes for more information on the type and the range of available attributes.

ImageOptions

used by MapRequest
since 2.0

Describes the configuration of the rendered image. Some properties of this type are described in detail in the Image Generation concept.

Field Name Type Required Default Since Description
format ImageFormat no ImageFormat.PNG 2.0 The format of the image. In case of JPG, the backgrounds (like oceans and forests) must be part of the image content, because they guarantee an image without any transparent pixels. This is important, because for JPG semi-transparent pixels would be drawn in black erroneously. Therefore a ParameterConflictException is thrown in such a case.
height PhysicalPixel (Integer) no 256 2.0 The height of the image in physical pixel. The maximum allowed value is 8192.
width PhysicalPixel (Integer) no 256 2.0 The width of the image in physical pixel. The maximum allowed value is 8192.

MapOptions

used by MapRequest
since 2.1

Configures further parameters of the map.

Field Name Type Required Default Since Description
timeConsideration TimeConsideration no - 2.1 Specifies how to evaluate data which contain time restrictions. For the use cases see time consideration. If the object is NULL, all data which have time restrictions are not considered. For some scenarios a reference time is needed to match properties with a time domain against this reference time. If for this time no time zone is defined, i.e. it represents a local time, some exposed map locations are checked for their time zone offsets. If a time zone cannot be determined for such a location, this location is not taken into further consideration. So, in a first step a set of locations with calculated time zones is determined. If this set contains no elements, an exception is thrown. When the time zones differ for some locations, then the time zone containing most locations is used and a result limitation is added to the result. If all locations are in the same time zone, then this time zone is used and the result is calculated as usual.
contentSnapshotId String no - 2.8 Specifies the content snapshot to use. If no snapshot ID is set, the most recent content is used.
showOnlyRelevantByTime Boolean no false 2.2 Specifies if the map show all attributes regardless of referenceTime (default), or only the attributes which are relevant for this referenceTime. For further details, see Relevance of Feature Layer attributes.
layers String[] 0..* - 2.4 Specifies a list of layers which will be displayed on the map. If this parameter is specified, layers enabled in the stored profile are ignored. These layers can be the base layers labels, transport, and background, or any of the supported Feature Layer themes such as PTV_TruckAttributes. If this parameter is not present, the layers defined by the stored profile are displayed. For more information see Integration of custom data.
preferredRouteTypes String[] 0..* - 2.5 The road networks to be preferred by the routing algorithm as a comma-separated list (only if the Feature Layer PTV_PreferredRoutes is enabled). The available types can be requested through the xRuntime service and are documented in the manual as layer-specific properties of the Feature Layer PTV_PreferredRoutes. If this parameter is not present, all types of PTV_PreferredRoutes are displayed.
showCopyright Boolean no false 2.6 If showCopyright is true then it shows the copyright text in the lower right corner of the image. If showCopyright is false then no copyright text is shown.
drawIcons Boolean no true 2.23 Specifies if the Feature Layer icons have to be drawn on the map.

MapRequest

extends RequestBase
used by XMap
since 2.0

Specifies the map image to be rendered.

Field Name Type Required Default Since Description
mapSection MapSection yes - 2.0 Map section to be rendered.
mapOptions MapOptions no - 2.1 Map options not contained in the profile.
imageOptions ImageOptions no - 2.0 Options of the rendered image.
resultFields ResultFields no - 2.0 Options to configure the result fields available in the response.

MapResponse

extends ResponseBase
used by XMap
since 2.0

Contains the result of a map request, specifically the map image(s).

Field Name Type Required Default Since Description
image byte[] no - 2.0 The image as a byte array if requested by ResultFields.image.
zoom Zoom (double) yes - 2.0 The zoom level of the map image.
bounds Bounds yes - 2.0 Visible section of the rendered map images.
features Feature[] 0..* - 2.0 The features of all enabled Feature Layer themes rendered in the map, if requested by ResultFields.featureThemeIds.

MapSection (abstract)

extended by MapSectionByBounds, MapSectionByCenter, MapSectionByTileKey
used by MapRequest
since 2.0

Abstract base type for the map section to be rendered. A map section represents the part of a map which is visible to the user. It can be defined in multiple ways by several derived types. Further details concerning the generation of a map image can be found in here.

No fields defined.

MapSectionByBounds

extends MapSection
since 2.0

The required map section is described by its bounds. The map content is always rendered without distortion, even if bounds and image size have a different aspect ratio. Further details can be found in the Generating a Map Image description.

Field Name Type Required Default Since Description
bounds Bounds yes - 2.0 The bounds of the rendered map section, their coordinate format is specified by RequestBase.coordinateFormat. The bounds will be extended either in width or height in order to guarantee a complete filling of the image without distortion.

MapSectionByCenter

extends MapSection
since 2.0

The required map section is described by its center coordinate and its zooming. The zooming value can be set continuously. Further details can be found in the Generating a Map Image description.

Field Name Type Required Default Since Description
centerCoordinate Coordinate yes - 2.0 The coordinate of the center of the map, its coordinate format is specified by RequestBase.coordinateFormat.
zoom Zoom (double) yes - 2.0 The zoom into the map. This value may be fractional.

MapSectionByTileKey

extends MapSection
since 2.0

The required map section is described by its tile key. Tiles are addressed by zoom level, x as the horizontal and y as the vertical index. The tile key defines the area to be drawn and is independent of the coordinate format given in RequestBase.coordinateFormat. Further details can be found in the Map Tile API description and Generating a Map Image description. Because the tile key defines directly the area to be drawn, the coordinate format given in RequestBase.coordinateFormat is ignored for the map section.

Field Name Type Required Default Since Description
zoomLevel ZoomLevel (int) yes - 2.0 The zoom level according the specifications in Map Tile API.
x int yes - 2.0 The tile's horizontal index within its zoom level.
y int yes - 2.0 The tile's vertical index within its zoom level.

PixelBoundingBox

used by Feature
since 2.0

Defines a bounding box (rectangle) in a pixel-based medium. This type is part of the concept for Generating a Map Image.

Field Name Type Required Default Since Description
left PhysicalPixel (int) yes - 2.0 Lower bound of the rectangle area on the X-axis in pixels, orientation from left to right.
top PhysicalPixel (int) yes - 2.0 Lower bound of the rectangle area on the Y-axis in pixels, orientation from top to bottom.
right PhysicalPixel (int) yes - 2.0 Upper bound of the rectangle area on the X-axis in pixels, orientation from left to right.
bottom PhysicalPixel (int) yes - 2.0 Upper bound of the rectangle area on the Y-axis in pixels, orientation from top to bottom.

PixelPoint

used by Feature
since 2.0

Locates the position on a pixel-based medium. This type is part of the concept for Generating a Map Image.

Field Name Type Required Default Since Description
x PhysicalPixel (int) yes - 2.0 X-axis, horizontal pixel position, orientation from left to right.
y PhysicalPixel (int) yes - 2.0 Y-axis, vertical pixel position, orientation from top to bottom.

ResultFields

used by MapRequest
since 2.0

Options to configure the result fields available in the response and in case of Feature Layer data, the individual themes for which object information should be returned.

Field Name Type Required Default Since Description
image Boolean no true 2.0 Activate the MapResponse.image as a return value.
featureThemeIds ThemeId[] (String[]) 0..* - 2.0 The list of Feature Layer theme IDs for which features are to be returned. Every requested theme must be enabled in the Feature Layer profile.
iconReference Boolean no false 2.23 Specifies if icon references should be returned with the features.

TileResponse

extends ResponseBase
used by XMap
since 2.0

Contains the result of a tile request, which demands for additional object information besides the rendered tile image.

Field Name Type Required Default Since Description
image byte[] yes - 2.0 The image as a byte array.
zoom Zoom (double) yes - 2.0 The zoom level of the tile image.
features Feature[] 0..* - 2.0 The features of all enabled Feature Layer themes rendered in the tile.
Enumeration

ContentType

used by XMap
since 2.3

Enumeration of the supported content types which can be used for REST requests of the getTile operation, to specify what kind of response is returned.

Enumeration Value Since Description
IMAGE 2.3 An image is provided solely Base64 encoded.
JSON 2.3 A response is returned according the definition of TileResponse.
Enumeration

ImageFormat

used by ImageOptions, XMap
since 2.0

Enumeration of the supported bitmap formats, which can be used for rendered map images.

Enumeration Value Since Description
PNG 2.0 Image is provided in Portable Network Graphics format.
JPG 2.0 Image is provided in Joint Photographic Experts Group format.

Diagrams

Operations Overview

Requests

Responses

Map Options