Voxel51 API JavaScript Client Library

This package defines a JavaScript client library built on Node.js for accessing the Voxel51 Vision Services API.

The library is implemented with ES6-style classes and uses async/await to deliver Promised-based asynchronous execution.

Installation

To install the library, first clone it:

git clone https://github.com/voxel51/api-js
cd api-js

and then install the package:

npm ci

Sign-up and Authentication

To use the API, you must first create an account at https://console.voxel51.com and download an API token. Keep this token private. It is your access key to the API.

Each API request you make must be authenticated by your token. To activate your token, set the VOXEL51_API_TOKEN environment variable in your shell to point to your API token file:

export VOXEL51_API_TOKEN="/path/to/your/api-token.json"

Alternatively, you can permanently activate a token with following JavaScript code (from the Node REPL):

let voxel51 = require('.');

voxel51.auth.activateToken("/path/to/your/api-token.json");

In the latter case, your token is copied to ~/.voxel51/ and will be automatically used in all future sessions. A token can be deactivated via the voxel51.auth.deactivateToken() method.

After you have activated an API token, you have full access to the API.

Example Usage

To initialize an API session, issue the following commands in Node js:

let voxel51 = require('.');

let api = new voxel51.API();

// Convenience function to view JSON outputs
function pprint(obj) {
    console.log(JSON.stringify(obj, null, 4));
}

Analytics

List available analytics:

let analytics = api.listAnalytics();

Get documentation for the analytic with the given ID:

// ID of the analytic
let analyticId = 'XXXXXXXX';

api.getAnalyticDoc(analyticId).then(function(doc) {
  pprint(doc);
});

Data

Upload data to the cloud storage:

// Local path to the data
let uploadDataPath = '/path/to/video.mp4';

api.uploadData(uploadDataPath).then(function(metadata) {
  pprint(metadata);
});

List uploaded data:

api.listData().then(function(data) {
  pprint(data);
});

Jobs

List jobs you have created:

api.listJobs().then(function(metadata) {
  pprint(metadata);
});

Create a job request to perform an analytic on a data, where <analytic> is the name of the analytic to run, <data-id> is the ID of the data to process, and any <param#> values are set as necessary to configre the analytic:

let jobRequest = new voxel51.jobs.JobRequest('<analytic>');
let inputPath = voxel51.jobs.RemoteDataPath.fromDataId('<data-id>');
jobRequest.setInput('<input>', inputPath);
jobRequest.setParameter('<param1>', val1);
jobRequest.setParameter('<param2>', val2);

console.log(jobRequest.toString());

Upload a job request:

api.uploadJobRequest(jobRequest, '<job-name>').then(function(metadata) {
  pprint(metadata);
});

Start a job:

// ID of the job
let jobId = 'XXXXXXXX';

api.startJob(jobId).then(function(state) {
  console.log('Job started!');
});

Wait until a job is complete and then download its output:

// Local path to which to download the output
let jobOutputPath = '/path/to/output.zip';

api.waitUntilJobCompletes(jobId).then(function() {
  api.downloadJobOutput(jobId, jobOutputPath).then(function() {
    console.log('Download complete!');
  });
});

Get the status of a job:

api.getJobStatus(jobId).then(function(status) {
  pprint(status);
});

Generating Documentation

This project uses JSDoc to generate its documentation from source. To generate the documentation, run:

bash docs/generate_docs.bash

To view the documentation, open the docs/build/index.html file in your browser.

Copyright

Copyright 2018, Voxel51, LLC
voxel51.com