The SpatialKey Data Import API (DMAPI) allows developers to programmatically create, update, delete and query metadata about SpatialKey datasets.

This document will walk through the process of Authenticating and various dataset calls.

The Data Management API can help you manage your data in SpatialKey by facilitating dataset imports and overwrites. Before data can be imported or overwritten, you must upload the dataset. The rest of this section will walk you through the steps to using the Data Management API for a standard workflow. If you want to jump directly to all Data Management related calls, click here.

Since the API is based on REST principles, it’s very easy to write and test. You can use pretty much any HTTP client in any programming language to interact with the API. We have examples in multiple languages that you can leverage as a starting point. We also have a Command Line Tool that can be used with the DMAPI without any programming.

Authentication and Token calls

Authenticating

Follow a few steps to authenticate for the Data Management API:

  1. Obtain the API Keys
  2. Generate the OAuth JSON Web Token
  3. Generate the OAuth Access Token

Validating the OAuth Access Token

You may find that you want to validate the OAuth Access Token prior to making a call.  OAuth Access Tokens expire some it may be helpful to validate at times.

Uploading dataset(s)

The first step in importing a dataset through the API is to upload the dataset.

Required parameters

  • token: OAuth Access Token (created in the authentication process)
  • POST body: CSV file (can either be a .CSV, a .CSV zipped up to reduce the time to upload, or a zipped shapefile package)

Uploading a dataset

HTTP Call: POST

https://[spatialkey URL]/SpatialKeyFramework/api/v2/upload.json

Note: With the SpatialKey API you choose whether you want to use XML or JSON and you control this by ending the calls in either .json or .xml. In the authentication example above  we are using JSON.

Returns: Upload status list that includes an upload ID. Note that Upload IDs are needed for the actual import of the data.

To check the status of the upload – HTTP Call: GET

Importing dataset(s)

After a file has been uploaded to the server, the next step is to import the dataset. You will need an XML descriptor for the dataset.  To learn how to generate the XML file, click here.

Required parameters

  • uploadId: the upload ID obtained from the response during the upload process
  • POST body: XML descriptor for the dataset (XML file generation)

Importing a dataset

HTTP Call: POST

https://[spatialkey URL]/SpatialKeyFramework/api/v2/upload/{uploadID}

Note: With the SpatialKey API you choose whether you want to use XML or JSON and you control this by ending the calls in either .json or .xml. In the authentication example above  we are using JSON.

Returns: Immediate import status. The upload call is asynchronous since large datasets can take a significant amount of time to complete so you must poll for completion by checking the status using the upload ID – HTTP Call: GET.  The dataset ID will not be available until the status is “IMPORT_COMPLETE_CLEAN”.  Check the status to also monitor import errors.

Append/Overwrite a dataset

After the upload is complete, use the upload ID and the dataset ID to complete the append/upload.

Required parameters

  • uploadId: the upload ID obtained from the response during the upload process
  • datasetId:
  • method: “append” or “overwrite”
  • POST body: {XML descriptor for the dataset}

HTTP Call: POST

https://[spatialkey URL]/SpatialKeyFramework/api/v2/upload/{uploadID}/dataset/{dataset ID}/dataset.json

Note: With the SpatialKey API you choose whether you want to use XML or JSON and you control this by ending the calls in either .json or .xml. In the authentication example above  we are using JSON.

Returns: Immediate import status. The upload call is asynchronous since large datasets can take a significant amount of time to complete so you must poll for completion by checking the status using the upload ID – HTTP Call: GET.  The dataset ID will not be available until the status is “IMPORT_COMPLETE_CLEAN”.  Check the status to also monitor import errors.

Other dataset management calls

We include other dataset management API calls, some examples are listed below.

To view a list of all dataset management calls, click here.