REST API Data Access and Queries

By setting up your API key on the Nuklai marketplace, you will be able to query your data through our REST API. You can also integrate the Nuklai REST API into the applications that you are building as a developer or a data professional.

In this user guide, we will show you how to set up your API and query your first dataset.

To use Nuklai’s REST API, you should have:

Knowledge of programming languages and the query language SQL
A code editor or Jupyter Notebook set-up on your device.

When you arrive on the Nuklai marketplace, in the sidebar there will be a menu item called Settings. When you click on this menu item, a sub-menu will unfold, and you will see a sub-menu called API key. When you click on this sub-menu, a screen will appear where you can generate your API key.

The API key is set up with the rights to query all datasets that the user has uploaded to the Nuklai marketplace and the user can query all datasets that have an active subscription.

You will also be asked to select how many days the API key stays valid in the Duration Days field. This is done for security purposes – we suggest renewing your API keys every 90 days, but you can select a time between 1 day and 365 days.

Give your API key a name to distinguish them from other active API keys. You will be able to generate up to 5 different keys.

Now click the Generate button. In the API Key field, you will see a long string. This string is your API key. You will need to store this key in a secure place – if you lose this key, you will need to generate a new one. You can click the copy button (two squares) to copy the API key.

Send a query via the API

You can now open up your preferred code editor, if you have not set up any code editor and if you are familiar with Python, you can also choose to set up a Jupyter Notebook. We recommend you follow the official guide for installing JupyterLab on your device.

To set up your API in your code editor you should set up three variables. The API url, the API key, and the DatasetID.

HTTP Method: POST

API Url: https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries

Response format: JSON

The Dataset-ID you can get from the url of the dataset you want to query. It is a 36-character hexadecimal string and it is split into 5 parts.

For example: https://app.nukl.ai/dataset/061e6d78-205e-43e0-b9c1-499cea3b759c

Where 061e6d78-205e-43e0-b9c1-499cea3b759c is the Dataset-ID.

// Setting up the variables

const ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries";
const ApiKey = "[API_KEY]";
const DatasetId = "[DATASET_ID]";

# Setting up the variables

ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries"
ApiKey = "[API_KEY]"
DatasetId = "[DATASET_ID]"

// Setting up the variables

$ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries";
$ApiKey = "[API_KEY]";
$DatasetId = "[DATASET_ID]";

To make a proper query you should also set the headers. The first one is for the content type (JSON) and the second is for the authentication.

// Setting up the header

const headers = {
  "Content-Type": "application/json",
  'authentication': ApiKey
}

# Setting up the header

headers = {
  "Content-Type": "application/json",
  "authentication": ApiKey
}

// Setting up the header

$headers = [
  "Content-Type: application/json",
  "authentication: $ApiKey"
];

You are now able to add an SQL query to the body of the dataset. In this example, we will query all columns and the first 5 records of the dataset by writing the following SQL query:

// Selecting 5 records from the dataset

select * from @dataset limit 5

This query is added to the body in the following way:

// @dataset represents your dataset rows as a table

const body = {
  sqlQuery: "select * from @dataset limit 5",
}

# @dataset represents your dataset rows as a table

body = {
  "sqlQuery": "select * from @dataset limit 5"
}

// @dataset represents your dataset rows as a table

$body = [
  "sqlQuery" => "select * from @dataset limit 5"
];

Your code should now look like this to make the query:

// variables
const ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries";
const ApiKey = "[API_KEY]";
const DatasetId = "[DATASET_ID]";

// header
const headers = {
  "Content-Type": "application/json",
  'authentication': ApiKey
}

// body with sql query
const body = {
  sqlQuery: "select * from @dataset limit 5",
}

// make a request
fetch(ApiUrl.replace(':datasetId', DatasetId), {
  method: "POST",
  headers: headers,
  body: JSON.stringify(body), // convert to json object
})
  .then((response) => response.json())
  .then((data) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

# pip install requests
# pip install json

import requests
import json

# variables
ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries"
ApiKey = "[API_KEY]"
DatasetId = "[DATASET_ID]"

# header 
headers = {
  "Content-Type": "application/json",
  "authentication": ApiKey
}

# body with sql query
body = {
  "sqlQuery": "select * from @dataset limit 5"
}

# make a request
url = ApiUrl.replace(':datasetId', DatasetId)
try:
  response = requests.post(url, headers=headers, data=json.dumps(body))
  data = response.json()
  print(data)
except requests.RequestException as error:
  print(f"Error: {error}")

// variables
$ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries";
$ApiKey = "[API_KEY]";
$DatasetId = "[DATASET_ID]";

// header
$headers = [
  "Content-Type: application/json",
  "authentication: $ApiKey"
];

// body with sql query
$body = [
  "sqlQuery" => "select * from @dataset limit 5"
];

// make a request
$ch = curl_init(str_replace(':datasetId', $DatasetId, $ApiUrl));

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body)); // convert to json object
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

$result = curl_exec($ch);
curl_close($ch);

echo $result;

curl -X POST 'https://api.nukl.ai/api/public/v1/datasets/[DATASET_ID]/queries' \
  -H 'Content-Type: application/json' \
  -H 'authentication: [API_KEY]' \
  -d '{"sqlQuery":"select * from @dataset limit 5"}'

Once you run the code, you will get a response. This response is a job-ID.

For example: 061e6d78-205e-43e0-b9c1-499cea3b759c

This job-ID can have three responses:

Pending
- Your query is still running, wait until the job is finished.
Failed
- There might be a problem with your SQL query. We suggest first writing the correct SQL query within the UI.
Completed
- Your query has been completed, you will now be able to see the result as an object.

Retrieving your data

HTTP Method: GET

API Url: https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries

Response format: JSON

Your code should now look like something like this to fetch the response of the query:

// variables
const ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries/:jobId";
const ApiKey = "[API_KEY]";
const DatasetId = "[DATASET_ID]";
const JobId = "[JOB_ID]"; // retrieved from /queries request

// header
const headers = {
  "Content-Type": "application/json",
  'authentication': ApiKey
}

// make a request
fetch(ApiUrl.replace(':datasetId', DatasetId).replace(':jobId', JobId), {
  method: "GET",
  headers: headers
})
  .then((response) => response.json())
  .then((data) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

# pip install requests

import requests

# variables
ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries/:jobId"
ApiKey = "[API_KEY]"
DatasetId = "[DATASET_ID]"
JobId = "[JOB_ID]"  # retrieved from /queries request

# header
headers = {
  "Content-Type": "application/json",
  "authentication": ApiKey
}

# make a request
url = ApiUrl.replace(':datasetId', DatasetId).replace(':jobId', JobId)
try:
  response = requests.get(url, headers=headers)
  data = response.json()
  print(data)
except requests.RequestException as error:
  print(f"Error: {error}")

// variables
$ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries/:jobId";
$ApiKey = "[API_KEY]";
$DatasetId = "[DATASET_ID]";
$JobId = "[JOB_ID]"; // retrieved from /queries request

// header
$headers = [
  "Content-Type: application/json",
  "authentication: $ApiKey"
];

// make a request
$ch = curl_init(str_replace(array(':datasetId', ':jobId'), array($DatasetId, $JobId), $ApiUrl));

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

$result = curl_exec($ch);
curl_close($ch);

echo $result;

curl 'https://api.nukl.ai/api/public/v1/datasets/[DATASET_ID]/queries/[JOB_ID]' \
  -H 'Content-Type: application/json' \
  -H 'authentication: [API_KEY]'

Congratulations you have now set up your API key and queried your first dataset through the REST API!

PreviousEnriching Metadata on Community Dataset NextManaging Data Requests and Responses

Last updated 3 months ago