Advanced

The basic methods of the API can be strung together to achieve more complicated result sets or to perform functions that it may not be immediately apparent can be performed using the Maponics Spatial API. This is referred to as a batch call because you are batching multiple requests within a single API call.

Anatomy of A Batch Call

To make a batch call, simply include each <request></request> section one after the other:

<?xml version="1.0" encoding="UTF-8" ?>
<data>
    <auth>
        <loginname>[USERNAME<loginname>
        <key>[APIKEY]</key>
    </auth> 
    <request> 
        <dataset>[DATASETCODE]</dataset> 
        <method>[METHOD]</method> 
        <parameters>
            [PARAMETERS] 
        </parameters> 
    </request> 
    <request>
        <dataset>[DATASETCODE]</dataset>
        <method>[METHOD]</method>
        <parameters>
            [PARAMETERS] 
        </parameters>
    </request> 
    <request> 
        <dataset>[DATASETCODE]</dataset>
        <method>[METHOD]</method>
        <parameters>
            [PARAMETERS]
        </parameters>
    </request>
</data>

Retrieving Multiple Polygons

If we look at the base list of methods, as presented by the API, there is no method that allows us to request a list of polygons based on certain geographical criteria, such as a radius around an address. In fact, there is no single method that ever returns more than one polygon.

getGeoPolyByAddress, getGeoPolyByID and getGeoPolyByName all return a single polygon's set of coordinates.

However the Maponics Spatial API will accept multiple requests in a batch mode. This means that you can use one of the getGeoListBy* methods to return a list of the polygon IDs that satisfy your criteria, and then build a list of getGeoPolyByID methods and send them as a batch request to the API.

This requires two steps inside the client that you write, of course. The first request will be a single method call to one of the getGeoListBy* methods. This request will return a list of ID numbers. You can iterate through that list of ID numbers and build a batch method call XML request to send to the API and then send those requests en masse.

Retrieving Polygon and Attribute Data Simultaneously

The API's ability to process more than one request at the same time also allows you to request multiple types of information about the same polygon. It can be seen from the method list that no single method allows you to request both the polygonal coordinates of an object and any selection of attributes from that object at the same time. This means, for example, there is no one single method that allows you to retrieve both the coordinates of a neighborhood and that neighborhood's name and/or ID.

However, in the example page we've done exactly that. We retrieve the polygonal coordinates of the neighborhood that the address resides in, and at the same time, we retrieve the name and ID of that neighborhood, passing them to Google to be displayed in their GMarker information bubble window.

By examining the sample XML displayed below the Google Mashup, it can be seen that the method by which we accomplished this was to simply send two method calls to the API in the same XML request, one to getGeoAttByAddress for the attributes of the neighborhood and one to getGeoPolyByAddress to retrieve the neighborhood boundary itself.

The API will always return the results of each method call in a multi-method request in the same order in which it received the method calls, so when parsing the results, we always know which resultset belongs to which method.