API HTTP Call definitions (not in use)

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:

  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

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:

  1. action – the action to perform, in this case “login”
    • other actions are covered under separate call definitions
  2. orgName – the first portion of the SpatialKey organization domain name
    • if the organization domain is um.spatialkey.com then the orgName would be “um”
  3. 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
  4. 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:

  1. <error> – empty or contains error message
  2. <result_message> – result message text
  3. <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&notifyByEmail=false&addAllUsers=true

Arguments:

  1. 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
  2. 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
  3. 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
  4. 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

Returns: XML document and HTTP status of 200 if successfull

Root element: <sk_dia>

Child elements:

  1. <error> – empty or contains error message
  2. <error_code> – empty or contains an error code
  3. <result_message> – result message text
  4. <result> – the total number of records in the dataset
  5. <dataset_id> – the id of the new or overwritten dataset
  6. <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:

  1. action – the action to perform
    • Should be set as “poly” for a shape file upload
  2. datasetId – optional (must be passed if the dataset name is not), the id of the shape dataset to overwrite
  3. 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:

  1. <error> – empty or contains error message
  2. <error_code> – empty or contains an error code
  3. <result_message> – result message text
  4. <result> – the dataset ID
  5. <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:

  1. action – the action to perform
    • Should be set as “exportDSXML”
  2. 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:

  1. 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:

  1. <error> – empty or contains error message
  2. <error_code> – empty or contains an error code
  3. <result_message> – empty
  4. <result> – empty
  5. <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:

  1. action – the action to perform
    • Should be set as “deleteDataByRange”
  2. column – the data column that the range is checked against.  All data rows that match the column/range combination will be deleted.
  3. 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
  4. 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)
  5. 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)

Returns: XML document and HTTP status of 200 if successfull

Root element: <sk_dia>

Child elements:

  1. <error> – empty or contains error message
  2. <error_code> – empty or contains an error code
  3. <result_message> – the result message
  4. <result> – true/false
  5. <jsessionid> – the session identifier