The v1 DMAPI will be deprecated on 1/1/2016. If you have questions or need assistance migrating to the latest version please contact us.

Before making any calls to the API make sure you have authenticated and have a session token that is used for all subsequent calls. You can make multiple calls without authenticating as long as you session is preserved. Sessions will timeout after 20 minutes without any activity.

CSV Upload/Overwrite

A CSV upload through the API uses a combination of a CSV and an XML descriptor file. Although it is not required, it is recommended to ZIP the CSV and XML files up into .zip file. This will reduce the overall size of the CSV (as they can grow quite large) and therefore cut down on network traffic as well.  Manually creating the XML file can be error prone so we recommend uploading a small subset of your data through the SpatialKey client once then using the steps in this article to generate the XML. You will then pair this generated XML with your CSV.

The upload itself requires only one server call. The .zip (or CSV and XML) file needs to be placed as a multi-part form post HTTP call. In addition to attaching the files to the form post, additional arguments are required as well. It is at this point that some decisions need to be made about the type of upload needed for this dataset. Is the data appending or overwriting data? Should the API return as soon as the upload is finished or after the data is processed and entered into the SpatialKey database? Should an email be sent by SpatialKey when the import is complete? Each of these questions is answered with a URL argument:

HTTP Call: POST

https://[spatialkey URL]//SpatialKeyFramework/dataImportAPI?action=overwrite&runAsBackground=true&notifyByEmail=false

Required Parameters

Parameter Description
action overwrite/appendoverwrite – to overwrite existing data of the dataset (if the dataset is not new, creates it otherwise)append – appends to existing data of the dataset (if the dataset is new, creates it otherwise)
runAsBackground true/false – If this is set to false the response for the call will not return until the data has finished uploading. If this is set to true it will return right away and run as a background task.
notifyByEmail true/false – Be notified by email once the data upload has completed
addAllUsers (optional) If set to true (defaults to false) the SpatialKey server will add the All Users group as a viewer of the dataset

Returns: XML Document
Root element: <organization>

Child elements:

  1. <error> – empty or contains error message
  2. <cluster> – the SpatialKey cluster URL
  3. <organizationID> – the SpatialKey organizations identifier
  4. <protocol> – typically https which should be used for all Data Import API calls

Shape File Upload/Overwrite

The shape file upload call allows for the creation or overwrite of a geoset. In addition to the standard URL as used in other Data Import API calls, this call requires a multi-part form POST submission including a .zip file (containing the shape file contents) attached.

HTTP Call: POST

https://[spatialkey URL]//SpatialKeyFramework/dataImportAPIaction=poly&datasetName=Name_of_dataset

Required Parameters

Parameter Description
action poly
datasetName Required if uploading a new shapefile
datasetId Required if overwriting an existing shapefile. If this argument is present SpatialKey assumes an overwrite of the dataset.(To get the datasetId for an existing shape dataset, login to SpatialKey, open the settings for your shapefile from the “Manage Data” tab. Click on the “Advanced Settings” option, then click on the “Data Import API” tab. The dataset ID is at the bottom of this screen.)

Returns: XML Document
Root element: <organization>

Child elements:

  1. <error> – empty or contains error message
  2. <cluster> – the SpatialKey cluster URL
  3. <organizationID> – the SpatialKey organizations identifier
  4. <protocol> – typically https which should be used for all Data Import API calls