xdata

XData Operations

SOAP/JSON

Synchronous API

since 2.5
Operation Name Request Type Response Type Since Description
getSegments SegmentsRequest SegmentsResponse 2.19 Retrieves a list of segments from the map data according to the specified input, for example a coordinate. Returns a list of segments according to the specified criteria.
getTimeZone TimeZoneRequest TimeZoneResponse 2.14 Determines the time zone for a given location.
createContentSnapshot CreateContentSnapshotRequest ContentSnapshotResponse 2.8 Creates a snapshot of the current state of automatically updated data, such as PTV_TrafficIncidents Feature Layer. See technical concept about content snapshots for more details. Returns the ID of the content snapshot.
deleteContentSnapshot DeleteContentSnapshotRequest VoidResponse 2.8 Deletes a content snapshot.
listContentSnapshots ListContentSnapshotsRequest ContentSnapshotsListResponse 2.8 Lists available content snapshots including their meta data considering user privileges.
deleteHighPerformanceRoutingNetwork DeleteHighPerformanceRoutingNetworkRequest VoidResponse 2.8 Deletes a high-performance routing network with a given ID considering user privileges and concurrent usage.
listHighPerformanceRoutingNetworks ListHighPerformanceRoutingNetworksRequest HighPerformanceRoutingNetworksListResponse 2.5 Lists available high-performance routing networks including their meta data considering user privileges. Both networks of the map and user-created networks are listed. Networks belonging to the map have no scope, no tenant, and cannot be deleted. See technical concept about multitenancy on how to list networks for all available tenants or scopes.
createFeatureLayer CreateFeatureLayerRequest FeatureLayerResponse 2.19 Creates a custom Feature Layer. Returns the Feature Layer as a binary object or the layer id if the persistent mode is choosen.
deleteFeatureLayer DeleteFeatureLayerRequest VoidResponse 2.19 Deletes a custom Feature Layer.
listFeatureLayers ListFeatureLayersRequest FeatureLayersListResponse 2.19 Lists available custom Feature Layers including their meta data considering user privileges and concurrent usage. See technical concept about multitenancy on how to list Feature Layers for all available tenants or scopes.
SOAP/JSON

Asynchronous API

since 2.8
Operation Name Request Type Response Type Since Description
startCreateHighPerformanceRoutingNetwork CreateHighPerformanceRoutingNetworkRequest Job 2.8

Creates a high-performance routing network. Returns the ID of the high-performance routing network.

Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchHighPerformanceRoutingNetworkResponse. If the job ended with status FAILED, fetchHighPerformanceRoutingNetworkResponse throws the exception that occurred during calculation.

startCreateFeatureLayer CreateFeatureLayerRequest Job 2.19

This is the asynchronous version of createFeatureLayer.

Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchFeatureLayerResponse. If the job ended with status FAILED, fetchFeatureLayerResponse throws the exception that occurred during calculation.

fetchFeatureLayerResponse JobRequest FeatureLayerResponse 2.19

Fetches results of type FeatureLayerResponse for the given job. If the calculation ended with an exception, fetchFeatureLayerResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown.

fetchHighPerformanceRoutingNetworkResponse JobRequest HighPerformanceRoutingNetworkResponse 2.8

Fetches results of type HighPerformanceRoutingNetworkResponse for the given job. If the calculation ended with an exception, fetchHighPerformanceRoutingNetworkResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown.

watchJob WatchRequest Job 2.8

Returns the status of the given job.

This operation behaves exactly like the watchJob operation of the xRuntime service.

stopJob JobRequest Job 2.8

Attempts to stop a running job. If the status of the job changes to SUCCEEDED, preliminary results can be fetched, if available.

This operation behaves exactly like the stopJob operation of the xRuntime service.

deleteJob JobRequest Job 2.8

Attempts to delete a running job. If successful, the returned job will have state DELETED.

This operation behaves exactly like the deleteJob operation of the xRuntime service.

REST

timeZone

URL format: /services/rest/XData/2.26/timeZone/{x}/{y}
since 2.14

Determines the time zone for a given location.

Path Parameter Name Type Since Description
x double 2.14 The value in x-direction (west to east), longitude for WGS84.
y double 2.14 The value in y-direction (south to north), latitude for WGS84.
Query Parameter Name Type Default Since Description
referenceDate XMLGregorianCalendar - 2.14 The date to determine the daylight saving time for the given location. If not specified the time zone valid now will be returned. If daylight saving time changes at this date, the status at 12 noon will be assumed. Consequently, if daylight saving time changes from winter to summer at this date, summer will be returned.
Response Type Description
TimeZoneResponse Response object.
XServerException Default exception for all xServer operations. See subtypes of XServerFault for details.

Types

ContentSnapshotDescription

used by ContentSnapshotInformation, ContentSnapshotResponse
since 2.8

This type represents meta data about a content snapshot.

Field Name Type Required Default Since Description
id String no - 2.8 The ID of the content snapshot.
label UserDefinedName (String) no - 2.8 The optional label of the content snapshot, if it was specified in the request. This label is only used for displaying the content snapshot, e.g. in the dashboard, and is not considered in any other way.
tenant String no - 2.8 The tenant is returned only for administrators.
scope ScopeName (String) no - 2.8 The user defined scope.
createdAt XMLGregorianCalendar no - 2.8 Indicates the date the content snapshot was created.
lastUsedAt XMLGregorianCalendar no - 2.8 Indicates the date the content snapshot was used the last time.
size Long no - 2.8 Indicates the size of the content snapshot on the hard drive in bytes.

ContentSnapshotInformation

used by ContentSnapshotsListResponse
since 2.8

The result that lists a description of a single content snapshot or the exception that was returned querying the content snapshot ID.

Field Name Type Required Default Since Description
contentSnapshotDescription ContentSnapshotDescription no - 2.8 Meta data that describes the content snapshot.
listException SuppressedXServerException no - 2.8 Exception in case of an error querying a content snapshot ID.

ContentSnapshotResponse

extends ResponseBase
used by XData
since 2.8

This type represents a summary of the meta information on a content snapshot.

Field Name Type Required Default Since Description
contentSnapshotDescription ContentSnapshotDescription no - 2.8 Meta information that describes the current content snapshot.

ContentSnapshotsListResponse

extends ResponseBase
used by XData
since 2.8

This type represents a list of meta information on content snapshots.

Field Name Type Required Default Since Description
contentSnapshotInformation ContentSnapshotInformation[] 0..* - 2.8 The result list containing information about each content snapshot. If specific content snapshot IDs have been requested there is one entry in the list for each requested ID in the same order.

CreateContentSnapshotRequest

extends RequestBase
used by XData
since 2.8

This type represents settings for the creation of a new content snapshot.

Field Name Type Required Default Since Description
label UserDefinedName (String) no - 2.8 The label or description of this content snapshot.

CreateFeatureLayerRequest

extends RequestBase
used by XData
since 2.19

This type represents settings for the creation of a new Feature Layer.

Field Name Type Required Default Since Description
themeId ThemeId (String) yes - 2.19 The ID of the Feature Layer theme.
featureScenario FeatureScenario (String) no - 2.19 The scenario or description of this Feature Layer. This is especially useful to associate a layer to a user scenario in order to use only this layer during the routing and rendering requests. The scenario is required when the result field binaryFeatureLayer is set to false.
features Feature[] 1..* - 2.19 The list of features to add in the Feature Layer.
resultFields CreateFeatureLayerResultFields no - 2.19 The fields to be returned in the response.

CreateFeatureLayerResultFields

used by CreateFeatureLayerRequest
since 2.19

This type represents result fields when creating a Feature Layer.

Field Name Type Required Default Since Description
binaryFeatureLayer Boolean no true 2.19 Specifies if createFeatureLayer has to return a binary Feature Layer. If false, the generated layer will be persistent.

CreateHighPerformanceRoutingNetworkRequest

extends RequestBase
used by XData
since 2.8

This type represents settings for the creation of a new high-performance routing network. An InvalidValueFault is returned if the Feature Layer theme PTV_RestrictionZones is activated. PTV_RestrictionZones are not supported in high-performance routing.

Field Name Type Required Default Since Description
label UserDefinedName (String) no - 2.8 The label or description of this high-performance routing network. This is especially useful if the networks should be listed in the PTV xServer dashboard.
highPerformanceRoutingNetworkOptions HighPerformanceRoutingNetworkOptions no - 2.8 This type represents options that are relevant for selection of a high-performance routing network besides the profile.

DeleteContentSnapshotRequest

extends RequestBase
used by XData
since 2.8

This type represents settings for deleting a content snapshot.

Field Name Type Required Default Since Description
id String yes - 2.8 The ID of the content snapshot to be deleted.

DeleteFeatureLayerRequest

extends RequestBase
used by XData
since 2.19

This type represents settings for deleting a Feature Layer.

Field Name Type Required Default Since Description
themeId ThemeId (String) yes - 2.19 The ID of the Feature Layer theme.
featureScenario FeatureScenario (String) yes - 2.19 The scenario of the Feature Layer to be deleted.

DeleteHighPerformanceRoutingNetworkRequest

extends RequestBase
used by XData
since 2.8

This type represents settings for deleting a high-performance routing network.

Field Name Type Required Default Since Description
id String yes - 2.8 The ID of the high-performance routing network to be deleted.

Feature

used by CreateFeatureLayerRequest
since 2.19

This type represents settings for the creation of a new Feature Layer.

Field Name Type Required Default Since Description
segmentIds SegmentId[] (String[]) 1..* - 2.19 The segments.
direction SegmentDirection no SegmentDirection. ... 2.19 The direction in which to use the segment.
descriptions FeatureDescription[] 1..* - 2.19 The descriptions.

FeatureDescription

used by Feature
since 2.19

This type represents settings for the description of a new feature.

Field Name Type Required Default Since Description
attributes KeyValuePair[] 1..* - 2.19 The list of attributes.
timeDomain String no - 2.19 The time domain.

FeatureLayerDescription

used by FeatureLayerInformation, FeatureLayerResponse
since 2.19

This type represents meta data about a Feature Layer.

Field Name Type Required Default Since Description
themeId ThemeId (String) yes - 2.19 The ID of the Feature Layer theme.
featureScenario FeatureScenario (String) no - 2.19 The optional scenario of the Feature Layer, if it was specified in the request. This scenario is used for displaying the Feature Layer, e.g. in the dashboard, and is also stored in the layer.
tenant String no - 2.19 The tenant is returned only for administrators.
scope ScopeName (String) no - 2.19 The user defined scope.
createdAt XMLGregorianCalendar no - 2.19 Indicates the date the Feature Layer was created.
lastUsedAt XMLGregorianCalendar no - 2.19 Indicates the date the Feature Layer was used the last time.
size Long no - 2.19 Indicates the size of the Feature Layer on the hard drive in bytes.
providerInformation String no - 2.19 Display information on the data providers of the map. This string consists of a comma-separated list of pairs of data provider name and provider version number, e.g. TomTom 2016.12. The string format can be changed at any time, it is for display purposes only.

FeatureLayerInformation

used by FeatureLayersListResponse
since 2.19

The result that lists a description of a single Feature Layer or the exception that was returned querying the Feature Layer ID.

Field Name Type Required Default Since Description
featureLayerDescription FeatureLayerDescription no - 2.19 Meta data that describes the Feature Layer.
listException SuppressedXServerException no - 2.19 Exception in case of an error querying a Feature Layer content ID.

FeatureLayerResponse

extends ResponseBase
used by XData
since 2.19

This type represents the response when a Feature Layer is created.

Field Name Type Required Default Since Description
binaryFeatureLayer EncodedContent (String) no - 2.19 The binary representation of the Feature Layer, returned as an encoded string.
featureLayerDescription FeatureLayerDescription no - 2.19 Meta information that describes the current Feature Layer content.

FeatureLayersListResponse

extends ResponseBase
used by XData
since 2.19

This type represents a list of meta information on Feature Layers.

Field Name Type Required Default Since Description
featureLayerInformation FeatureLayerInformation[] 0..* - 2.19 The result list containing information about each Feature Layer. If specific Feature Layer IDs have been requested there is one entry in the list for each requested ID in the same order.

HighPerformanceRoutingNetworkAlreadyAvailableLimitation

extends ResultLimitation
since 2.8

This result limitation indicates that a high-performance routing network already exists and hasn't been created as a result of the request.

Field Name Type Required Default Since Description
id String no - 2.8 The ID of the high-performance routing network if it has been created by the user. An unitialized ID indicates that the user has requested a high-performance routing network which has been delivered with the map.

HighPerformanceRoutingNetworkDescription

used by HighPerformanceRoutingNetworkInformation
since 2.5

This type represents meta data about a high-performance routing network.

Field Name Type Required Default Since Description
id String no - 2.5 The ID of the network.
label UserDefinedName (String) no - 2.5 The optional label of the network, if it was specified in the request. This label is only used for displaying the network, e.g. in the dashboard, and is not considered in any other way.
highPerformanceRoutingNetworkOptions HighPerformanceRoutingNetworkOptions no - 2.5

The options used for this high-performance routing network.

Warning: Options are removed from the response if they cannot be represented using the requested API version. This situation might occur if a more recent API version was used for the creation of the high-performance routing network than for this list request. In general, it is not recommended to mix different API versions.

profile RequestProfile no - 2.5

Contains only the relevant profile parameters.

Warning: Profile elements are removed from the response if they cannot be represented using the requested API version. This restriction also applies to elements of the stored profile used for calculation of this high-performance routing network. If the returned profile should be used as a request profile in a subsequent request (e.g. for creating another high-performance routing network or for a route calculation), it is recommended to specify the same stored profile as in the original create request. In general, it is not recommended to mix different API versions.

tenant String no - 2.5 The tenant is returned only for administrators and only for user-created networks.
scope ScopeName (String) no - 2.5 The user defined scope. It is returned only for user-created networks.
lastUsedAt XMLGregorianCalendar no - 2.8 Indicates the date the network was used the last time.
size Long no - 2.8 Indicates the size of the network on the hard drive in bytes.

HighPerformanceRoutingNetworkInformation

used by HighPerformanceRoutingNetworksListResponse
since 2.5

The result that lists a description of a single high-performance routing network or the exception that was returned querying the network.

Field Name Type Required Default Since Description
highPerformanceRoutingNetworkDescription HighPerformanceRoutingNetworkDescription no - 2.5 Meta data that describes the current network.
listException SuppressedXServerException no - 2.5 Exception in case of an error querying a network ID.

This type represents additional options that are relevant for selection of a high-performance routing network besides the profile.

Field Name Type Required Default Since Description
timeConsideration TimeConsideration no - 2.8 Set this parameter if time dependent features should be considered for the high-performance routing network calculation. The different scenarios of time consideration are explained in more detail in the technical concept about time consideration. Please note that the time consideration values ExactTimeConsiderationAtStart and ExactTimeConsiderationAtArrival are not available and if used an exception will be returned.
contentSnapshotId String no - 2.8 Specifies the content snapshot to use. If no snapshot ID is set, the most recent content is used.
geographicRestrictions GeographicRestrictions no - 2.5 Specifies geographic restrictions that are considered during the high-performance routing network calculation.

HighPerformanceRoutingNetworkProgress

extends JobProgress
since 2.8

The progress for a running high-performance routing network calculation.

Field Name Type Required Default Since Description
status HighPerformanceRoutingNetworkProgressStatus yes - 2.8 The action currently being performed.
progress Percent (Double) no - 2.8 The progress of the actions PREPROCESSING and GENERATING_NETWORK.

HighPerformanceRoutingNetworkResponse

extends ResponseBase
used by XData
since 2.8

This type contains the ID of a high-performance routing network that has been created.

Field Name Type Required Default Since Description
id String no - 2.8 The ID of the high-performance routing network which is generated when the network is created. Use this ID to reference the high-performance routing network for further use. The ID can be uninitialized. An uninitialized ID indicates that the requested high-performance routing network is already existing. In this case a HighPerformanceRoutingNetworkAlreadyAvailableLimitation is created. It may contain the ID of the already existing high-performance routing network. Otherwise an unitialized ID in the HighPerformanceRoutingNetworkAlreadyAvailableLimitation indicates that the user has requested a high-performance routing network which has been delivered with the map.

HighPerformanceRoutingNetworksListResponse

extends ResponseBase
used by XData
since 2.5

This type represents a list of meta information on high-performance routing networks.

Field Name Type Required Default Since Description
highPerformanceRoutingNetworkInformation HighPerformanceRoutingNetworkInformation[] 0..* - 2.5 The result list containing information about each high-performance routing network. If specific high-performance routing network IDs have been requested there is one entry in the list for each requested ID in the same order.

IncludedNetworkClasses

used by SegmentsOptions
since 2.19

Defines a list of network classes to be included in the result. For more information about network classes see the type of the segment attribute network class.

Field Name Type Required Default Since Description
included Boolean[] 8..8 - 2.19 The network classes to include in the result.

ListContentSnapshotsRequest

extends RequestBase
used by XData
since 2.8

This type represents settings for listing meta information of content snapshots.

Field Name Type Required Default Since Description
ids String[] 0..* - 2.8 The IDs of all content snapshots that should be listed. If the list is null or empty, all available snapshots will be listed.

ListFeatureLayersRequest

extends RequestBase
used by XData
since 2.19

This type represents settings for listing meta information of Feature Layers.

Field Name Type Required Default Since Description
themeIds ThemeId[] (String[]) 0..* - 2.19 The IDs of the Feature Layer themes.

ListHighPerformanceRoutingNetworksRequest

extends RequestBase
used by XData
since 2.5

This type represents settings for listing meta data about high-performance routing networks.

Field Name Type Required Default Since Description
ids String[] 0..* - 2.5 The IDs of all high-performance routing networks that should be listed. If the list is null or empty, all available networks will be listed.
returnOnlyMatchingNetworks Boolean no false 2.8 If this parameter is set to true then only the high-performance routing networks that match the given options and profile are returned. In this case the profile and options that shall match have to be set also in the request.
highPerformanceRoutingNetworkOptions HighPerformanceRoutingNetworkOptions no - 2.8 Specifies options that are also relevant for selection of a high-performance routing network besides the profile. If only the matching networks are requested these options are used to filter the networks. Otherwise they are ignored.
resultFields ListHighPerformanceRoutingNetworksResultFields no - 2.5 Specifies the result fields that will be available in the response.

ListHighPerformanceRoutingNetworksResultFields

used by ListHighPerformanceRoutingNetworksRequest
since 2.5

Settings for the result fields of the meta data about high-performance routing networks.

Field Name Type Required Default Since Description
highPerformanceRoutingNetworkOptions Boolean no false 2.5 Indicates if the options of the high-performance routing networks should be included in the result.
profiles Boolean no false 2.5 Indicates if the profiles should be included in the result.

MapSegment

used by SegmentsResponse
since 2.19

A segment on the map. It represents a geographic location on a map, specified by its segment-id and may contain a polyline representation and additional descriptors like road name and number or combined transport attributes .

Field Name Type Required Default Since Description
type SegmentType yes - 2.19 A segment may have different types, e.g. it may be a "normal" segment between two network nodes, a "link segment", a virtual segment which represents a border crossing or a waiting time, or a combined transport segment.
polyline EncodedGeometry no - 2.19

The polyline of the segment. This polyline consists of all coordinates representing the segment and can be used to draw the segment into a map. Not available for segments of type SegmentType.NOT_DRIVING.

The polyline is returned in the direction of traffic in the case of one-way.

descriptors SegmentDescriptors no - 2.19 Attributes which basically describe the segment such as road name and number.
combinedTransport CombinedTransportAttributes no - 2.19 Attributes which describe the combined transport this segment represents. Available only for segments of type SegmentType.COMBINED_TRANSPORT.
id SegmentId (String) no - 2.19 The internal ID of the segment. Could then be used, for example, to create a FeatureLayer or calculate a route passing through a combined transport.

SegmentsByCoordinateRequest

extends SegmentsRequest
since 2.19

Retrieve segments from the map according to a given coordinate.

Field Name Type Required Default Since Description
coordinate Coordinate yes - 2.19 The coordinate that is located on the segment or nearby the segment(s).

SegmentsByIdRequest

extends SegmentsRequest
since 2.22

Retrieve segments from the map according to given segment ids.

Field Name Type Required Default Since Description
ids SegmentId[] (String[]) 1..* - 2.22 The Ids of the segment(s).

SegmentsByIntersectingPolylineRequest

extends SegmentsRequest
since 2.19

Retrieve segments from the map that are intersected by a given polyline.

Field Name Type Required Default Since Description
polyline EncodedGeometry yes - 2.19 The polyline that intersects the segment(s).

SegmentsBySurroundingPolygonRequest

extends SegmentsRequest
since 2.19

Retrieve segments from the map that are surrounded by a given polygon.

Field Name Type Required Default Since Description
polygon EncodedGeometry yes - 2.19 The polygon that surrounds the segment(s).

SegmentsOptions

used by SegmentsRequest
since 2.19

Specifies search options for segments.

Field Name Type Required Default Since Description
includedNetworkClasses IncludedNetworkClasses no - 2.19 Specifies for which network classes the segments shall be included in the result. If not specified, the segments will be included whatever their network class.
includedSegmentTypes SegmentType[] 0..* - 2.20 The segment types to include in the result. If the list is null or empty, all the segments will be included whatever their type. Only SegmentType.NETWORK_SEGMENT and SegmentType.COMBINED_TRANSPORT are supported.

Abstract base type to retrieve segments from the map for different kinds of selection criteria.

Field Name Type Required Default Since Description
resultFields SegmentsResultFields no - 2.19 Specifies which parts of the found segments should be included in the result.
segmentsOptions SegmentsOptions no - 2.19 Options to configure the result fields available in the response.

SegmentsResponse

extends ResponseBase
used by XData
since 2.19

Response of a getSegments request which contains all selected segments according to the request criteria.

Field Name Type Required Default Since Description
segments MapSegment[] 0..* - 2.19 The list of selected segments according to the specified criteria from the request.

SegmentsResultFields

used by SegmentsRequest
since 2.19

Specifies to what extent segments shall be returned.

Field Name Type Required Default Since Description
polyline Boolean no false 2.19 Specifies if the segments shall contain the polyline.
descriptors Boolean no false 2.19 Specifies if the segments shall contain the descriptors such as country, road name and number.
combinedTransport Boolean no false 2.20 Specifies if the segments shall contain the combined transport attributes such as type and name.

TimeZoneRequest

extends RequestBase
used by XData
since 2.14

Specifies the coordinate and an optional reference date to determine the daylight saving time.

Field Name Type Required Default Since Description
coordinate Coordinate yes - 2.14 The coordinate of the location in question. The coordinate must be on a land-based area covered by the map and close to some road. The time zone cannot be determined for coordinates in the sea. In such a case a UTCOffsetNotDeterminableException is thrown. See technical concept about time zones for details.
referenceDate XMLGregorianCalendar no - 2.14 The date to determine the daylight saving time for the given location. If not specified the time zone valid now will be returned. If daylight saving time changes at this date, the status at 12 noon will be assumed. Consequently, if daylight saving time changes from winter to summer at this date, summer will be returned.

TimeZoneResponse

extends ResponseBase
used by XData
since 2.14

The time zone of the given location

Field Name Type Required Default Since Description
timeZone TimeZone no - 2.14 Specifies time zone and daylight saving time.
Enumeration

HighPerformanceRoutingNetworkProgressStatus

used by HighPerformanceRoutingNetworkProgress
since 2.8

Possible status values for the progress of a running high-performance routing network calculation.

Enumeration Value Since Description
PREPROCESSING 2.8 Indicates that some tasks have to be done before generating the high-performance routing network. The actual progress of this state is available in HighPerformanceRoutingNetworkProgress.progress.
GENERATING_NETWORK 2.8 Indicates the generation of the high-performance routing network is ongoing. The actual progress of this state is available in HighPerformanceRoutingNetworkProgress.progress.
DONE 2.8 Indicates that the generation of the high-performance routing network is finished.

Diagrams

Operations Overview (High-Performance Routing)

Operations Overview (Content Snapshot)

Operations Overview (Feature Layer)

Operations Overview (Time Zone)

Job Progress

Segments

Time Zone

High-Performance Routing Requests

High-Performance Routing Responses

Result Limitations

Content Snapshot Requests

Content Snapshot Responses

Feature Layer Requests

Feature Layer Responses