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.34/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 | TimeSpanDuration (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 operation getDataInformation in the xRuntime service (Feature Layer theme 'PTV_PreferredRoutes', profile property 'preferredRouteType') 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
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. |
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. |
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 operation getDataInformation in the xRuntime service (Feature Layer theme 'PTV_PreferredRoutes', profile property 'preferredRouteType') 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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
Contains the result of a tile request, which demands for additional object information besides the rendered tile image.
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. |