Javascript

The Algorithmia JavaScript client provides a native interface for calling algorithms using the Algorithmia API.

This guide will cover setting up the client, calling an algorithm using direct user input, and calling an algorithm that uses JSON as input. For complete details about the Algorithmia API, please refer to the API Docs.

The code in this guide can be run from the JavaScript console in your browser or used in your own scripts.

Set up the client

The JavaScript client can be downloaded from https://algorithmia.com/v1/clients/js/algorithmia-0.2.1.js and the JavaScript file can be included as a script tag:

<script src="//algorithmia.com/v1/clients/js/algorithmia-0.2.1.js" type="text/javascript"></script>

To use the client you’ll need an API key, which Algorithmia uses for fine-grained authentication across the platform. For this example, we’ll use the default-key that was created along with your account, which has a broad set of permissions. Log in to Algorithmia and navigate to Home > API Keys to find your key, or read the API keys documentation for more information.

Once the client is included, you can instantiate the client object:

var client = Algorithmia.client("YOUR_API_KEY");

Specifying an on-premises or private cloud endpoint

This feature is available to Algorithmia Enterprise users only.

If you are running Algorithmia Enterprise, you can specify the API endpoint when you create the client object:

var client = Algorithmia.client("YOUR_API_KEY", "https://mylocalendpoint/v1/web/algo");

Calling an algorithm

Algorithms take three basic types of input whether they are invoked directly through the API or by using a client library: strings, JSON, and binary data. In addition, individual algorithms might have their own I/O requirements, such as using different data types for input and output, or accepting multiple types of input, so consult the input and output sections of an algorithm’s documentation for specifics.

The first algorithm we’ll call is a demo version of the algorithm used in the Algorithm Development Getting Started guide, which is available at demo/Hello. Looking at the algorithm’s documentation, it takes a string as input and returns a string.

In order to call an Algorithm from JavaScript, we need to first create an algorithm object. With the client already instantiated, we can run the following code to create an object:

var algo = client.algo("demo/Hello");

Then, we can use the .pipe() method to call the algorithm, and provide our input as the argument to the function. The JavaScript client returns a promise, so we can use .then() to handle the result and any errors.

algo.pipe("HAL 9000").then(function (output)
    {
        if(output.error) return console.error("error: " + output.error.message);
        console.log(output.result);
    });

Which should print the phrase Hello HAL 9000 to the console.

JSON inputs

Let’s look at an example using JSON and the nlp/LDA algorithm. The algorithm docs tell us that the algorithm takes a list of documents and returns a number of topics that are relevant to those documents. The documents can be a list of strings, a Data API file path, or a URL. We’ll call this algorithm using a JSON object as our input, following the format in the algorithm documentation:

input = {
    "docsList":
        [
            "It's apple picking season",
            "The apples are ready for picking"
        ]
};

const algoJSON = client.algo("nlp/LDA/1.0.0");
algoJSON.pipe(input).then(function (output)
    {
        if(output.error) return console.error("error: " + output.error.message);
        console.log(output.result);
    }
);

The output will be a JSON object which includes an array of topics which include relevant words and the number of occurrences.

[
    {ready: 1},
    {apple: 1, season: 1},
    {picking: 2},
    {apples: 1}
]

You might have noticed that in this example we included a version number when instantiating the algorithm. Pinning your code to a specific version of the algorithm can be especially important in a production environment where the underlying implementation might change from version to version.

Error handling

To be able to better develop across languages, Algorithmia has created a set of standardized errors that can be returned by either the platform or by the algorithm being run. In JavaScript, API errors and Algorithm exceptions will result in calls to .pipe() returning an error object in their output.

client.algo("util/whoopsWrongAlgo").pipe("").then(function (output)
    {
        if(output.error) return console.error("error: " + output.error.message);
        console.log(output.result);
    }
)
//[Error] error: algorithm algo://util/whoopsWrongAlgo/ not found

You can read more about Error Handling in the Algorithm Development section of the dev center.

Limits

Your account can make up to 80 Algorithmia requests at the same time (this limit can be raised if needed).

Algorithm requests have a payload size limit of 10MB for input and 15MB for output. If you need to work with larger amounts of data, you can make use of the Algorithmia Data API.

Working with files

Because of security concerns, the JavaScript client does not implement the Data API which other clients use to move files into and out of Data Sources. This can be a problem if you call an algorithm which writes its output to a file (instead of returning it directly). However, there are workarounds:

For smaller files, the util/Cat and ANaimi/Base64DataConverter algorithms can be used for retrieving file contents.

For larger files, you can set up an Amazon S3 Connector to an S3 bucket with public read access. Then, direct the algorithms you call to write their output into that S3 connector (or use s3utilities/UploadFiletoS3/ to move it there). Once it is in the S3 bucket, you can access the file via its publicly-readable URL.

Alternately, you could implement a small piece of backend code in another language and use it to retrieve the file for you.