Requesting a Single Map Image with Web Service API
In contrast to the REST API, the web service interface allows you to:
- get more information about the generated image (e.g. effective extent and copyright)
- modify the pre-configured map profiles A profile is a collection of parameters used to configure the request. Full profiles consist of a number of specialized sub-profiles like the VehicleProfile which describes the properties of a vehicle. per request, especially the styles used for Feature Layer attributes
- specify the visible map section in various ways
- use fractional zoom levels
The web service interface provides more options, but it is also more complex to handle.
Check if the following prerequisites are fulfilled before you start with the use case:
- Installed and licensed PTV xMap Server
- Installed PTV Map
PTV xServer SOAP and JSON interfaces offer exactly the same functionality, you may choose the one that fits best your software ecosystem. For this description, we use the raw request runner to submit requests to the PTV xServer JSON interface, and inspect the results. The main functional entry point for the PTV xMap service is called renderMap. It takes a MapRequest as parameter and returns a MapResponse. So the basic steps are to construct the request, call the service, and process the response.
Constructing the request
With JSON, the request is just a string according the PTV xServer API reference definition, and looks like this:
In our example, we choose a map section of type MapSectionByBounds, giving the Bounds of the rectangle to be drawn and some image options. For special wishes about the map image you want, feel free to modify the request parameters accordingly.
Calling the service
Calling the service depends on the used programming language. In this topic we call the web service API using the interactive PTV xServer raw request runner.
Processing the result
With JSON, the result is returned as a JSON string, again according the PTV xServer API reference definition, and looks like this:
In our minimal example, the MapResponse object contains the actual Bounds of the drawn rectangle, and the image as a Base64-encoded binary block.
It is possible to request additional textual information about drawn Feature Layer items. more code samples can be found in the raw request runner.
More advanced use cases
If you'd like to specify the request this way and use it in an interactive map, you might like to read the following use case:
Some more detailed hints, which are common to all PTV xServers can be found in the article Web Service Interface Principles in the Developers Guide.
The following topics might be relevant for this use case.