Data Mapping REST Web Services

MapForce 2016 Release 2 includes expanded functionality for Web Services data mapping, providing robust support for REST Web services. MapForce accepts XML or JSON as the Web service response, allows definition of parameters, and supports custom HTTP headers. Users may define the Web service interface manually or by importing settings from a WADL file or a URL. Manual definition of REST Web Service Settings lets developers create settings based on a template URL. This is a convenient step when developers test and refine REST calls in a Web browser window, since the URL can be copied from the browser to become the template.

We’ve noted previously that coordinates captured by GPS systems are precise, but elevation data is notoriously inaccurate. The USGS provides a REST Web service that accepts queries providing longitude and latitude and supplies accurate elevation data, either in XML or JSON. We can use this Web service in a MapForce data mapping to update GPS data from a Garmin device and simultaneously convert the data format from XML to JSON.

We’ll start by testing the Web service in a browser window. The URL shown below opens an input form to generate a sample query:

When we click the Get Elevation button, the form generates a complete REST GET query, submits it, and displays the result below. We can use this result to model the response for our data mapping.

We’ll add the Web service to our mapping by clicking the Insert Web Service Function button in the MapForce toolbar. This opens the Web Service Call Setting dialog, where we provide the URL of the USGS service.

Next we need to define the request parameters and the response body, which will create the elements for mapping, as seen below in the next portion of the Call Settings dialog.

We conveniently generated a JSON Schema in XMLSpy to define the response, based on the JSON instance file saved from the browser window. Shown below is the XMLSpy Schema view of the converted response:

The USGS elevation service input form gave us all the information we need to define the input parameters, so we can add those to the next section of the Call Settings dialog:

The units and output values for each request won’t change during execution and we could have specified fixed values. Instead, we’ll provide them in the mapping as constants. Any necessary security settings would also be configured in the Call Settings dialog. When we click Okay to close the dialog, the Web Service function is added to the mapping.

Each trackpoint in the source GPX file will provide a set of input coordinates. During mapping execution, a Web Services GET request will query the USGS every time a trackpoint is processed and the response will provide replacement elevation data.

Now all we need to do is connect elements of the request and response to input and output components, as shown below. The constants for units and output type are seen at the top left, and the elevation value is rounded to two decimal places before insertion into the output.

Note that the output is a JSON file. The input component is not shown in this partial view of the mapping, but it is an standard GPX file in XML format. The data mapping connection lines entering from the left, that pass behind the Web Service function in the illustration and connect to the output component are all values that will be copied without change from the XML input to the corresponding JSON elements.

When we click the MapForce Output button, the mapping executes and a JSON file is generated, as seen in the partial view here:

In a production environment we could save the mapping as a MapForce Execution File for automated processing by MapForce Server, either from a command line or under control of FlowForce Server.

Altova MapForce is an award-winning any-to-any graphical data mapping, conversion, and integration tool that maps data between any combination of XML, database, EDI, XBRL, flat file, Excel, JSON, and/or Web service. Download a fully-functional free trial and check it out for yourself!