Dataset API

This article provides sample API calls used for obtaining a list of Datasets, creating and modifying individual Datasets, as well as obtaining and manipulating their data.

To query Datasets data and metadata, the following Item functions are used:

  1. dataset (to fetch metadata, to edit and to apply Access Maps to Datasets)
    • available since Version 5.4.0
  2. dataset_data (to obtain data from specific Datasets)
    • available since Version 5.3.1
  3. dataset_instance (to get a list of Dataset Instances)
    • available since Version 5.4.0

PREREQUISITES:

To be able to make API calls, you need to obtain an access Token

For more information, see:

Get a Token using API Toolkit

Go to Admin > Utilities > API Toolkit > API Test Tool

  1. Item: from the dropdown, select get_token
  2. ID: enter External Application ID
  3. Request: input User Name after "user": in the Request
  4. Run request: click to get the Token

Since all API calls require a Token, you need to copy the token from the Raw Response field and enter it in the provided Token field.

Obtain a list of Datasets in Metric Insights

You can use any of the available Datasets as a model for a new Dataset.

The example provided below shows how create a new Dataset from an existing Dataset.

  1. Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
  2. Item: from the dropdown, select dataset 
  3. Methods: choose GET
  4. Run request: click to get a list of all Datasets and their metadata

Raw response will contain information about Datasets in Metric Insights.

1. Create a new Dataset

  1. Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
  2. Item: from the dropdown, select dataset 
  3. Methods: choose POST
  4. ID: input the ID of an existing Dataset that you want to use as a model for a new Dataset
    • After you input the Dataset ID, the Request field will display the settings for that Dataset
  5. Request: type in the name for the new Dataset
    • Optionally, you can change the Dataset description, snapshotting options and other settings
  6. Run request: click to create a new Dataset

Raw response will contain metadata for the new Dataset. The newly created Dataset will be assigned an ID that can be used in subsequent API calls (e.g.: when validating, enabling and updating your Dataset)

2. Modify your Dataset via the API action calls

PUT Method (used in API calls to Metric Insights) supports the following actions:

  1. Validate
  2. Delete data
  3. Get Access Map
  4. Set Access Map
  5. Enable
  6. Update Dataset

2.1. Validate and enable your Dataset

  1. Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
    • The same Token can be used for a series of subsequent API calls
  2. Actions: from the dropdown, select the relevant option
  3. Request: if you choose to validate, enter the date against which Dataset data will be validated
    • measurement_time parameter must be in the following format: year-month-day
  4. Run request: click to run the API action call

After you validate and enable your Dataset, you can get the Dataset data by following the steps described in Section 4 of this article.

2.2. Update a Dataset

After modifying your Dataset, update the Dataset to make the changes effective.

  1. Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
  2. Actions: from the dropdown, select Update Dataset
  3. Request: measurement_time can be changed from default
    • measurement_time parameter must have the following format: year-month-day
  4. Run request: click to run the API action call

If the API update call is successful, the "status":"OK" message will be displayed in the Raw response

2.3. Query a Dataset Access Map

Dataset API calls allow you to query the Access (User) Map of any existing Dataset that has an Access (User) Map.

  1. Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
  2. Actions: from the dropdown, select Get Access Map
  3. Run request: click to run the API action call

Raw response will contain the Dataset columns mapped to Access Map columns.  

For more information on Access (User) Maps, refer to:

2.4. Apply an Access Map to a Dataset

  1. Token: enter the Token that you have previously obtained as noted in the PREREQUISITES
  2. ID: input the ID of a Dataset
  3. Actions: choose Set Access Map
    • After you input the Dataset ID, the Request field will display Dataset columns that have already been mapped to Access (User) Map columns
    • Note: for the Set Access Map action to work, at least one Access (User) Map column should already be mapped to the corresponding Dataset column
  4. Request: input additional columns from the Dataset and User Map that will be mapped against one another
    • To get a list of all available columns in an Access (User) Map, use the dataset_data item since Acces Maps are treated as Datasets by the system. For more information, check Fetch Dataset Data  
  5. Run request: click to run the API action call

3. Fetch Dataset Data

You can either query all the data contained in that (All Data) View of the Dataset or specify a particular View and/or Time Instance.

3.1. Get data from an "All Data" View

  1. Token: enter a Token that you have previously obtained as noted in the PREREQUISITES
  2. Item:  select "dataset_data" from the drop-down
  3. Methods: GET
  4. ID: must be left blank
  5. dataset:  enter the Dataset ID. Learn how to find your Dataset ID
  6. Request URL (generated automatically): https://yourcompany.metricinsights.com/api/dataset_data?dataset=<id>
  7. Run request

3.2. Get data from a Specific View

To see a specific View, additionally enter a View ID. Learn how to find you Dataset View ID.

Request URL (generated automatically): https://yourcompany.metricinsights.com/api/dataset_data?dataset=<id>&view=<id> .

3.3. Get data from a Specific Dataset Instance

In the example below, the data displayed in the Raw Response was pre-filtered for a specific View and Date.

  1. dataset: required
  2. View ID: optional
  3. Measurement_time: type in the date that you need to fetch your information for (only the following format is supported: yyyy-mm-dd). If Dataset is NOT "set to keep history", the "measurement_time" parameter is ignored during the API call. The Raw Response returns data exclusively for the last time the data was collected.

Request URL (generated automatically): https://yourcompany.metricinsights.com/api/dataset_data?dataset=<id>&view=<id>&measurement_time=yyyy-mm-dd .

Where can I find Dataset ID?

Dataset ID can be found in the the web browser URL of the Dataset Viewer or Dataset Editor:

https://stg530.metricinsights.com/dataset/index/index/ds/474

Where can I find Dataset View ID?

Dataset View ID can be found in the the web browser URL of the Dataset Viewer.

https://stg530.metricinsights.com/dataset/index/index/ds/474/filter/211

4. Query all Dataset Instances

  1. Token: enter a Token that you have previously obtained as noted in the PREREQUISITES
  2. Item:  select "dataset_data" from the drop-down
  3. Methods: only GET is currently supported
  4. ID: must be left blank
  5. dataset:  enter the Dataset ID
  6. Request URL (generated automatically): https://yourcompany.metricinsights.com/api/dataset_data?dataset=<id>
  7. Run request

Raw response will contain a list of Dataset Instances