Input and Output Structure


While the way in which you call any Algorithm is universal across Algorithmia, the input you pass to the Algorithm is unique to what it does. For example, an image colorization tool may accept a string containing the URL of an image, while a timeseries prediction function may take a list of numbers. Some Algorithms can even take several different kinds of input; for example, SentimentAnalysis will happily accept:

  • a single string: "good"
  • a map/dictionary: {"document": "good"}
  • a list of maps: [{"document": "good"},{"document": "bad"}]

The choice of input formats is up to the Algorithm's developer. You can find simple samples under the "Run an Example" and "Install and Use" sections of the Algorithm's main page, and more in-depth information on the "Docs" tab of the page.

Consider the following two ways of calling SentimentAnalysis...

Here's an example of calling SentimentAnalysis from Java, using the simplest input data structure, a String:

Here's a sample calling it from Python, and using the list-style input instead: 

Despite being different languages, these two code samples are quite similar, using client.algo('algoname') to define the Algorithm to call, and algo.pipe(input) to send the input. Also note that the Algorithm is always run the same way, using .pipe(input), regardless of which input format is being used.

In case you were wondering, there's never a need to do any JSON encoding or decoding: the Client's .pipe() function takes language-native objects. For example, the Python example uses a List of Dictionaries as the input. Behind the scenes, this is serialized into JSON by the Algorithmia Client, then deserialized on our servers to call the actual Algorithm -- but you don't need to worry about any of that when writing your code. You can just pretend that you are calling a language-native local function, and Algorithmia invisibly handles the remote connection and any language-to-language translation that needs to take place.


If nothing goes wrong, the algo.pipe() call returns an object containing the properties .result and .metadata (we'll talk about errors/exceptions in the next section).

The .result property contains the actual output from the Algorithm (once again, this is a language-native construct: for example, in Python, it'll be a Dictionary). In the case of Sentiment Analysis, we can see from its sample output (under "Run an Example" and the "Docs" tab), this will be a structure of the form [ { "document": "great", "sentiment": 0.6249 } ] -- so algo.pipe("great").result[0]['sentiment'] would contain the calculated sentiment value for the phrase "great". Take a close look at the "Docs" tab of the Algorithm you're calling; sometimes the structure of the .result varies, depending on which variation of the input structure you're using.

The .metadata property contains information about the execution of the Algorithm; notably, .metadata.duration tells us how many seconds (or fraction thereof) it took to actually execute the code on Algorithmia's servers. This may be smaller than the observed clock-time it takes to run the call, because one must also consider network latency (transmission time across the internet), and possible warm-up time if we spin up a new copy of the Algorithm to service your call. Regardless, you only pay for the actual compute-time (.metadata.duration) it took to run the code, rounded up to whole seconds.


Some Algorithms use files (especially "data://" URIs) as their input or output -- we'll learn more about that under Managing Data.

But first, let's take on error handling.