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://[spatialkey URL]/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://[spatialkey URL]/SpatialKeyFramework/dataImportAPI?action=overwrite& runAsBackground=true¬ifyByEmail=false&addAllUsers=true
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:
- addAllUsers – optional, if set as true (defaults to false) the SpatialKey server will add the All Users group as a viewer of the dataset
- 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
- <error_code> – empty or contains an error code
- <result_message> – result message text
- <result> – the total number of records in the dataset
- <dataset_id> – the id of the new or overwritten dataset
- <jsessionid> – the session identifier
Shape File Upload
The shape file upload call allows for the overwriting of an existing shape file dataset (the shape dataset must have been previously created using the SpatialKey application). 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 shape file contents) attached.
URL Example:
https://[spatialkey URL]/SpatialKeyFramework/dataImportAPI?action=poly& datasetId=my dataset id here
Arguments:
- action – the action to perform
- Should be set as “poly” for a shape file upload
- datasetId – optional (must be passed if the dataset name is not), the id of the shape dataset to overwrite
- datasetName – optional (must be passed if the dataset id is not), the text name of the shape dataset to overwrite
Returns: XML document and HTTP status of 200 if successfull
Root element: <sk_dia>
Child elements:
- <error> – empty or contains error message
- <error_code> – empty or contains an error code
- <result_message> – result message text
- <result> – the dataset ID
- <jsessionid> – the session identifier
Export Dataset XML
This call will return the custom XML document describing a previously uploaded dataset. This XML file can then be used for calling append/overwrite API calls against the dataset. You can also download the XML using the SpatialKey application in the Dataset Manager.
URL Example:
https://[spatialkey URL]/SpatialKeyFramework/dataImportAPI?action=exportDSXML& datasetId=my dataset id here
Arguments:
- action – the action to perform
- Should be set as “exportDSXML”
- datasetId – the id of the dataset to get the XML descriptor for
Returns: the custom XML document describing the requested dataset
Get Session ID
This call can be used to acquire the JSESSIONID after establishing a session with the SpatialKey server.
URL Example:
https://[spatialkey URL]/SpatialKeyFramework/dataImportAPI?action=getSessionId
Arguments:
- action – the action to perform
- Should be set as “getSessionId”
Returns: XML document and HTTP status of 200 if successfull
Root element: <sk_dia>
Child elements:
- <error> – empty or contains error message
- <error_code> – empty or contains an error code
- <result_message> – empty
- <result> – empty
- <jsessionid> – the session identifier
Delete Data By Range
This call is used to delete data out of an existing uploaded dataset by a given column and data range. Please take caution as this process cannot be undone.
URL Example:
https://[spatialkey URL]/SpatialKeyFramework/dataImportAPI?action=deleteDataByRange& column=the column to check against&startRange=10.02.2009.00.00.00&endRange=10.10.2009&dataType=date
Arguments:
- action – the action to perform
- Should be set as “deleteDataByRange”
- column – the data column that the range is checked against. All data rows that match the column/range combination will be deleted.
- dataType – optional (default to “date”), determins the data type of the column being checked
- The only valid value at this time is “date”
- Other column types may be added in the future
- startRange – the starting data value for the ranage check
- For dates:
- Can be in one of two formats
- mm.dd.yyyy (will default to 00:00:00 for time)
- mm.dd.yyyy.hh.mm.ss (must use 24 hour time)
- Can be in one of two formats
- For dates:
- endRange – the ending data value for the range check
- For dates:
-
- Can be in one of two formats
- mm.dd.yyyy (will default to 23:59:59 for time)
- mm.dd.yyyy.hh.mm.ss (must use 24 hour time)
- Can be in one of two formats
Returns: XML document and HTTP status of 200 if successfull
Root element: <sk_dia>
Child elements:
- <error> – empty or contains error message
- <error_code> – empty or contains an error code
- <result_message> – the result message
- <result> – true/false
- <jsessionid> – the session identifier