The Maponics Spatial API is a RESTful service, which allows communication via simple plaintext XML 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 Maponics Spatial 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.
The URL to POST your XML request to is:
As the API currently requires the use of HTTP POST on the client end, the name of the POST variable required is: apirequest
This means that your HTTP POST string to http://api.maponics.com/interface/ will look like this:
Also, the Content-Type header of the request must be equivalent to that of a POSTed form, that is:
The API expects an XML request coming in from a client to be structured in a specific manner, and is broken down into two sections; an authentication section, and a request section, as seen below:
|[USERNAME]||This is your customer API username||Assigned by Maponics|
|[APIKEY]||This is your unique 32-character API key||Assigned by Maponics|
|[DATASETCODE]||This upper-case code represents the target dataset of the API request||
|[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
(note: Sample return data in this documentation is given in XML format)
|[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|
If your contract with Maponics grants you access to Maponics Context™ data, you can query this data as part of your normal API query. To add a request for Context data to a normal API query, structure your XML as shown below:
You can find a list of available Maponics Context™ datasets here along with which geographic datasets they're valid for.
If you want to request data from more than one valid Maponics Context™ layer, simply add each desired layer as as separate <layer></layer> section in your request, like this:
Remember, the list of requested fields should be appropriate to the context dataset you're requesting in that particular <layer></layer> section.
The Maponics Spatial API accepts multiple <request></request> sections within the API request. Simply have them follow each other consecutively, like so:
Each <request></request> section will have its data returned in an equivalent <response></response> section within the XML response sent back by the API, and the order of the responses will match the order of the requests.
The details of the API response structure depend largely upon the method called in the request. However, the basic overall layout of the response XML is very simple:
|[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. If the API request contained more than one <request></request> section, then there would be correspondingly multiple <response></response> sections.
For more details on exactly what to expect as return values from the API, see the detailed documentation on the individual methods.