Home Page

Overview

The Maponics Spatial API is a RESTful service that allows communication via simple plaintext XML or JSON over SSL by means of the HTTP POST protocol. Dispensing with SOAP removes a lot of unnecessary protocol-related overheads, allowing the data sent back and forth to be smaller and the communication to be more efficient.

Connecting to the API requires a username and an API key. These are issued by Maponics, and each request made to the API will require them to be sent.

Connecting to the API

The URL endpoint for the API is:

https://api.maponics.com/interface/

The API accepts data sent as HTTP POST, HTTP GET or direct.

HTTP POST

An HTTP POST request requires the Content-Type header of the request to be that of a POSTed web form, that is:

Content-Type: application/x-www-form-urlencoded

It also requires the data to be sent as a name/value pair. The name required is apirequest and the value will be the payload as a single string, whether XML or JSON. The API will automatically process XML or JSON. You do not need to tell it which format you are using.

HTTP GET

An HTTP GET request simply appends the payload as a single string to the end of the URL. Like HTTP POST, it requires the same name/value pair. An HTTP GET request would look something like this:

https://api.maponics.com/interface/?apirequest=<?xml version="1.0" encoding="UTF-8"?><data>...</data>

Direct

Direct requests send the XML or JSON payload directly to the endpoint without requiring a name/value pair. You simply open a connection to the API endpoint and stream the data through.

API Request Structure

The API expects a request coming from a client to be structured in a specific manner and this structure is broken down into two sections, an authentication section and a request section, as seen below:

XML

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

JSON

{
    "data":{
        "auth":{
            "loginname":"[USERNAME]",
            "key":"[APIKEY]"
        },
        "request":[
            {
                "dataset":"[DATASETCODE]",
                "method":"[METHOD]",
                "returnType":"[RETURNTYPE]",
                "parameters":{
                    [PARAMETERS]
                }
            }
        ]
    }
}
Element Description Valid Values
[USERNAME] This is your customer API username Assigned by Maponics
[APIKEY] This is your unique 32-character API key Assigned by Maponics
[DATASETCODE] This uppercase code represents the target dataset of the API request List of available datasets
[METHOD] The name of the public method this API request is attempting to access. List of public methods
[RETURNTYPE] The format of the returned data. xml
json
[PARAMETERS] XML list of parameters appropriate to that method For a list of parameters appropriate to each method type, please view the documentation for that specific method

API Return Structure

XML

<?xml version="1.0" encoding="UTF-8" ?>
<data>
    <resultcode>[CODE]</resultcode>
    <message>[MESSAGE]</message>
    <requestid>[REQUESTID]</requestid>
    <response>
        <item>
            [ITEM_DETAILS]
        </item>
        <item>
            [ITEM_DETAILS]
        </item>
    </response>
</data>

JSON

[
    {
        "resultcode":[CODE],
        "message":"[MESSAGE]",
        "requestid":"[REQUESTID]",
        "request":[
            [
                {
                    [ITEM_DETAILS]
                },
                {
                    [ITEM_DETAILS]
                }
            ]
        ]
    }
]
Element Description
[REQUESTID] The internal ID of this request.
[CODE] The result code of the operation. This is an integer. Explanations of all the possible result codes can be found here.
[MESSAGE] A textual string sometimes included with a result code providing further explanation.
[ITEM_DETAILS] XML formatted plaintext details of the object or objects returned in response to the request made.

The actual contents of the [ITEM_DETAILS] sections will of course vary, depending on the request made to the API.

For more details on exactly what to expect as return values from the API, see the detailed documentation on the individual methods.