algorithmia.js
A nodejs library for calling algorithms on Algorithmia.com with partial support for the DataAPI
Getting started
The official Algorithmia nodejs client is available on NPM.
Install it for your project by adding algorithmia
to your package.json:
npm install --save algorithmia
Then instantiate an Algorithmia client using your API key:
var algorithmia = ; var client = ;
Now you are ready to call algorithms.
Calling algorithms
The following examples of calling algorithms are organized by type of input/output which vary between algorithms.
Note: a single algorithm may have different input and output types, or accept multiple types of input, so consult the algorithm's description for usage examples specific to that algorithm.
Text input/output
Call an algorithm with text input by passing a string into the pipe
method.
The returned promise will be called with the response with the Algorithm completes (or when an error occurs).
If the algorithm output is text, then the get()
method on the response will return a string.
client ;// -> Hello HAL 9000
JSON input/output
Call an algorithm with JSON input by passing in a native JavaScript type;
most of the time this will be an Object
or an Array
(though Boolean
, Number
, and Null
are possible).
Similarly, if the algorithm response is JSON, the get()
method will return the appropriate native JavaScript type.
client ;
Alternatively, if you already have serialized JSON, you can call pipeJson
with the raw JSON string.
The following example makes the same API call as the previous example:
client
Binary input/output
Call an algorithm with binary input by passing a Buffer
into the pipe method.
Similarly, if the algorithm response is binary data, then the get
method on the response will be a byte array.
var buffer = fs;client ;
Note: while it is possible to use response.result
for text or JSON responses, in the case of a binary resonse,
the result
field will be base64-encoded. The get()
method is recommended
because it will return the correct type in all cases.
Error handling
If an error occurs when calling an algorithm, the response will contain an error field that you can check:
client ;
Request options
The Algorithmia API exposes parameters to configure algorithm requests including support for changing the timeout of indicating that the API should include stdout in the response. Currently, the node.js client exposes these as query paremeters to the algorithm URI:
client
Note: stdout=true
is only supported if you have access to the algorithm source.
Working with data
The Algorithmia client also provides a way to manage both Algorithmia hosted data and data from Dropbox or S3 accounts that you've connected to you Algorithmia account.
Create directories
Create directories by instantiating a Dir
object and calling create()
:
var robots = clientdir"data://.my/robots";robots;
Upload files to a directory
Upload files by calling the putFile
method a Dir
object or put
on a File
object:
var robots = clientdir"data://.my/robots";robots
You can also write to a File
using the put
method with either a string
or Buffer
as input:
var prime = client;prime
Download content from files
Download files by calling get
on a File
object:
var robots = clientdir"data://.my/robots"; // Get a text file's contents as a stringrobots; /// Get a binary file's contents as a Bufferrobots;
Delete files and directories
Delete files by calling delete
on their respective File
or Dir
object.
When deleting directories, you may optionally specify a force
argument
that indicates whether or not a directory should be deleted if it contains files or other directories (default = false
).
var c3po = client;c3po; // Force delete a directoryclientdir"data://.my/robots" ;
List directory contents
Iterate over the contents of a directory using the iterated returned by calling forEachDir
or forEachFile
on a Dir
object:
// List top level directoriesclientdir"data://.my"; // List files in the Public folder of your connected Dropbox accountclientdir"dropbox://Public";
Building the client
This project uses gulp to compile coffeescript.
npm installnpm install -g gulp-cli gulp
Note: Don't edit the .js in the lib
directory; they will get overwritten on subsequent compiles.
Instead, modify .coffee
files in the src
dir, and run gulp
.