Getting Started

Updated August 06, 2021

Welcome to Getting Started with the Algorithmia API. This guide will show you how to call an algorithm via our API in a few lines of code using our supported language clients.

We’ll show an example in cURL, Python, Java, Rust, R, Node, Ruby, JavaScript, Scala, Go, and Swift in order to get you up and running quickly.

Finding an Algorithm

To get started, find an algorithm you’d like to call. You can do this by using the search bar or browsing the marketplace by tags & categories:

Each algorithm has an owner and an algorithm name; you’ll need both to format your request. This information is listed under the algorithm name on the description page as well as in the format of the algorithm’s URL.

For a given user and algorithm name, API calls are made to the following URL:

POST https://api.algorithmia.com/v1/algo/:owner/:algoname

We recommend that you also append the algorithm version in your API call to ensure that the correct algorithm is called.

To call a private version of an algorithm you own, you must use a fully specified semantic version or a version hash or you will get an error. For more information you can get details in the API Docs

If you want a complete guide on how to navigate an algorithm’s description page including how to determine the price of calling an algorithm, check out our Algorithm Profiles guide.

Making your first API call

We’ll make our first call with the demo algorithm “Hello”. This algorithm takes an input of a string (preferably your name!) and returns a greeting addressed to the input.

curl -X POST -d '"YOUR_USERNAME"' -H 'Content-Type: application/json' -H 'Authorization: Simple YOUR_API_KEY' https://api.algorithmia.com/v1/algo/demo/Hello/

If you aren’t logged in, make sure to replace YOUR_USERNAME with your name & YOUR_API_KEY with your API key.

You can also use one of the clients to make your call. See below for examples or visit one of the Client Guides for details on how to call algorithms and work with data in your language of choice.

import Algorithmia
input = "YOUR_USERNAME"
client = Algorithmia.client('YOUR_API_KEY')
algo = client.algo('demo/Hello/')
print(algo.pipe(input))

import com.algorithmia.*;
import com.algorithmia.algo.*;

String input = "YOUR_USERNAME"
AlgorithmiaClient client = Algorithmia.client("YOUR_API_KEY");
Algorithm algo = client.algo("demo/Hello/");
AlgoResponse result = algo.pipe(input);
System.out.println(result.asJsonString());

library(algorithmia)

input <- "YOUR_USERNAME"
client <- getAlgorithmiaClient("YOUR_API_KEY")
algo <- client$algo("demo/Hello/")
result <- algo$pipe(input)$result
print(result)

var input = "YOUR_USERNAME";
Algorithmia.client("YOUR_API_KEY")
          .algo("demo/Hello/")
          .pipe(input)
          .then(function(output) {
            console.log(output);
          });

var input = "YOUR_USERNAME";
Algorithmia.client("YOUR_API_KEY")
          .algo("algo://demo/Hello/")
          .pipe(input)
          .then(function(response) {
            console.log(response.get());
          });

require 'algorithmia'

input = "YOUR_USERNAME"
client = Algorithmia.client("YOUR_API_KEY")
algo = client.algo("demo/Hello/")
response = algo.pipe(input).result
puts response

use algorithmia::*;

let input = "YOUR_USERNAME";
let client = Algorithmia::client("YOUR_API_KEY");
let algo = client.algo("demo/Hello/");
let response = algo.pipe(input);
println!(response)

import com.algorithmia._
import com.algorithmia.algo._

val input = "YOUR_USERNAME"
val client = Algorithmia.client("YOUR_API_KEY")
val algo = client.algo("algo://demo/Hello/")
val result = algo.pipeJson(input)
System.out.println(result.asString)

import Algorithmia

let input = "YOUR_USERNAME";
let client = Algorithmia.client(simpleKey: "YOUR_API_KEY")
let algo = client.algo(algoUri: "demo/Hello/") { resp, error in
  print(resp)
}

using Algorithmia;

var input = "YOUR_USERNAME";
var client = new Client("YOUR_API_KEY");
var algo = client.algo(client, "algo://demo/hello");
var response = algo.pipe<string>(input);
System.Console.WriteLine(response.result.ToString());

import (
  algorithmia "github.com/algorithmiaio/algorithmia-go"
)

input := "YOUR_USERNAME"

var client = algorithmia.NewClient("YOUR_API_KEY", "")
algo, _ := client.Algo("algo://demo/Hello/")
resp, _ := algo.Pipe(input)
response := resp.(*algorithmia.AlgoResponse)
fmt.Println(response.Result)

use LWP::UserAgent;

my $input = 'YOUR_USERNAME';
my $api_key = 'YOUR_API_KEY';
my $req = HTTP::Request->new(POST => 'http://api.algorithmia.com/v1/algo/demo/hello');
$req->header('content-type' => 'application/json');
$req->header('Authorization' => 'Simple '.$api_key);
$req->content($post_data);
my $ua = LWP::UserAgent->new;
my $resp = $ua->request($req);
if ($resp->is_success) {
    print $resp->decoded_content;
} else {
    print 'POST error: ', $resp->code, ': ', $resp->message;
}

$input = 'YOUR_USERNAME';
$api_key = 'YOUR_API_KEY';
$data_json = json_encode($input);
$ch = curl_init();
  curl_setopt_array($ch, array(
    CURLOPT_URL => 'https://api.algorithmia.com/v1/algo/demo/hello',
    CURLOPT_HTTPHEADER => array(
      'Content-Type: application/json',
      'Authorization: Simple ' . $api_key,
      'Content-Length: ' . strlen($data_json)
    ),
    CURLOPT_POSTFIELDS => $data_json,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true
  ));
  $response_json = curl_exec($ch);
  curl_close($ch);
  $response = json_decode($response_json);
  if($response->error) {
    print('ERROR: ');
    print_r($response->error);
  } else {
    print_r($response->result);
  }

Understanding the response

Each algorithm returns a response in JSON. It will include the "result" as well as metadata about the API call you made. The metadata will include the content_type as well as a duration.

curl -X POST -d '"YOUR_USERNAME"' -H 'Content-Type: application/json' -H 'Authorization: Simple YOUR_API_KEY' https://api.algorithmia.com/v1/algo/demo/Hello/

{
  "result": "Hello YOUR_USERNAME",
  "metadata": {
     "content_type": "text",
     "duration": 0.000187722
  }
}

The duration is the compute time of the API call into the algorithm. This is the time in seconds between the start of the execution of the algorithm and when it produces a response. Because you are charged on the compute time of the API call, this information will help you optimize your use of the API.

For more thorough tutorials in the language of your choice go back to Client Guides or if you want more information about pricing, check out our Pricing Guide.

Developer Center

Resources to get you started with Algorithmia

Getting Started

Finding an Algorithm

Making your first API call

Understanding the response