API HTTP Call Definitions
Back to the Data Import API main page
Data Import API Calls
Cluster Lookup
The cluster lookup call is used to determine what protocol and URL to use for Data Import API calls for a specific SpatialKey organization.
URL Example:
http://[your organization SpatialKey domain]/clusterlookup.cfm
Arguments: N/A
Returns: XML Document
Root element: <organization>
Child elements:
- <error> - empty or contains error message
- <cluster> - the SpatialKey cluster URL
- <organizationID> - the SpatialKey organizations identifier
- <protocol> - typically https which should be used for all Data Import API calls
Authentication
The authentication call should be made directly to a SpatialKey cluster. This call will log in a user and provide a JSESSIONID for subsequent calls. It is important to pass the JSESSIONID as a cookie on each call made after the authentication operation.
URL Example:
https://[returned cluster domain]/SpatialKeyFramework/dataImportAPI?action=login&orgName=um&
user=test@spatialkey.com&password=12345
Arguments:
- action - the action to perform, in this case “login”
- other actions are covered under separate call definitions
- orgName - the first portion of the SpatialKey organization domain name
- if the organization domain is um.spatialkey.com then the orgName would be “um”
- user - the username (email) of the SpatialKey user to perform the authentication and subsequent Data Import API calls with
- This user must have dataset creation permissions and import permissions to upload data
- password - the password of the user to authenticate with
Returns: XML Document and HTTP status of 200 if successful
Root element: <sk_dia>
Child elements:
- <error> - empty or contains error message
- <result_message> - result message text
- <result> - same as result_message for login operation
Upload Data
The upload data call has various different options for how the processing and usage of the data should proceed. The call should follow a call to the authenticate call. After the call ends, the authenticated user will be automatically logged out of the system. Each call must have the JSESSIONID returned in the response header from the authenticate call added as a cookie to the POST request of the Upload Data call. Please see the Calling the API page for more information and the SpatialKey Data Poller example application (DataPollingTask.java) for a Java way of implementing this.
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 CSV data and XML descriptor) or the CSV and XML files attached.
URL Example:
https://[returned cluster domain]/SpatialKeyFramework/dataImportAPI?action=overwrite&
runAsBackground=true¬ifyByEmail=false
Arguments:
- action - the action to perform
- The action for an upload data call can be:
- overwrite - 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)
- The dataset the action works against is defined in the XML descriptor, see Required Files for more information
- The action for an upload data call can be:
- runAsBackground - determines if the SpatialKey server should return as soon as the data is uploaded (thus freeing up your connection), or should it wait for the entire import process to complete (defaults to false)
- valid values are:
- true
- false
- valid values are:
- notifyByEmail - if set as true (defaults to false) the SpatialKey server will send an email to the authenticated user when the import is complete
- valid values are:
- true
- false
- valid values are:
Returns: XML document and HTTP status of 200 if successfull
Root element: <sk_dia>
Child elements:
- <error> - empty or contains error message
- <result_message> - result message text
- <result> - the total number of records in the dataset
Follow Us: