api.maponics.com logo

Documentation

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.

Connection Details

The URL to POST your XML request to is:

http://api.maponics.com/interface/

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:

apirequest=<?xml version="1.0" encoding="UTF-8" ?><data>...</data>

Also, the Content-Type header of the request must be equivalent to that of a POSTed form, that is:

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

API Request Structure

The API expects an 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:

Show XML request

Show json request

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 upper-case code represents the target dataset of the API request
  • Z : ZIP Codes
  • N : Neighborhoods
  • CR : Carrier Routes
[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
(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

Context Data

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 request as shown below:

Show XML request

Show json request

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:

<context> <layer> <context_dataset>[CONTEXTCODE1]</context_dataset> <attributes>[CONTEXTFIELDLIST1]</attributes> </layer> <layer> <context_dataset>[CONTEXTCODE2]</context_dataset> <attributes>[CONTEXTFIELDLIST2]</attributes> </layer> </context>

Remember, the list of requested fields should be appropriate to the context dataset you're requesting in that particular <layer></layer> section.

Multiple Requests

The Maponics Spatial API accepts multiple <request></request> sections within the API request. Simply have them follow each other consecutively, like so:

<?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>

Each <request></request> section will have its data returned in an equivalent <response></response> section within the response sent back by the API, and the order of the responses will match the order of the requests.

API Response Structure

The details of the API response structure depend largely upon the method called in the request. However, the basic overall layout of the response is very simple:

Show XML return

Show json return

Element Description
[REQUESTID] The internal Maponics 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. 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.