Requesting a Single Map Image with Web Service API

In use case Displaying a Basic Interactive Map we show a very easy way to display an interactive map. Popular toolkits can be used to render a map: Internally they request all small but needed tiles and compose them to a complete image. Commonly, the more restricted and REST REST (Representational State Transfer) represents a World Wide Web paradigm, consisting of constraints to the design of components which results in a better performance and maintainability.-based tile API is used for this purpose. However, if you have special needs about the appearance of your map, you should consider using the web service A web service represents a communication technology applied in computer networks. It provides an interface described in a machine-processable format, for example WSDL. interface (JSON JSON (JavaScript Object Notation) is an open standard format for which human-readable text is used to transmit information consisting of attribute–value pairs. It is the first-address data format used for asynchronous browser/server communication (AJAX). or SOAP SOAP (Simple Object Access Protocol) is a protocol specification for exchanging structured information in the context of Web services. XML is used for definition of the message format, and it is based on other application layer protocols, like Hypertext Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP).), which is explained in the following.

Benefits

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.

Prerequisites

Check if the following prerequisites are fulfilled before you start with the use case:

Installed and licensed PTV xMap Server
Installed PTV Map

Programming Guide

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:

Displaying a Configurable Interactive Map

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.