package module
Version: v0.0.0-...-7fa6395 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Jan 6, 2021 License: MIT Imports: 15 Imported by: 0


Algorithmia Common Library (Golang)

Golang client library for accessing the Algorithmia API.

For detailed library documentation, see the Godoc.

Table Of Contents


go get


First, create an Algorithmia client and authenticate with your API key:

import (
	algorithmia ""

var apiKey = "{{Your API key here}}"
var client = algorithmia.NewClient(apiKey, "")

Now you're 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 simply passing a string into its Pipe method. If the algorithm output is text, then the Result field of the response will be a string.

algo, _ := client.Algo("demo/Hello/0.1.1")
resp, _ := algo.Pipe("Author")
response := resp.(*algorithmia.AlgoResponse)
fmt.Println(response.Result)            //Hello Author
fmt.Println(response.Metadata)          //Metadata(content_type='text',duration=0.0002127)
fmt.Println(response.Metadata.Duration) //0.0002127
JSON input/output

Call an algorithm with JSON input by simply passing in a type that can be serialized to JSON. For algorithms that return JSON, the Result field of the response will be the appropriate deserialized type.

algo, _ := client.Algo("WebPredict/ListAnagrams/0.1.0")
resp, _ := algo.Pipe([]string{"transformer", "terraforms", "retransform"})
response := resp.(*algorithmia.AlgoResponse)
fmt.Println(response.Result) //[transformer retransform]
Binary input/output

Call an algorithm with binary input by passing a byte array into the Pipe method. Similarly, if the algorithm response is binary data, then the Result field of the response will be a byte array.

input, _ := ioutil.ReadFile("/path/to/bender.png")
algo, _ := client.Algo("opencv/SmartThumbnail/0.1")
resp, _ := algo.Pipe(input)
response := resp.(*algorithmia.AlgoResponse)
ioutil.WriteFile("thumbnail.png", response.Result.([]byte), 0666)
fmt.Println(response.Result) //[binary byte sequence]
Error handling

API errors and Algorithm exceptions will result in calls to Pipe returning an error:

algo, _ := client.Algo("util/whoopsWrongAlgo")
_, err := algo.Pipe("Hello, World!")
fmt.Println(err) //algorithm algo://util/whoopsWrongAlgo not found
Request options

The client exposes options that can configure algorithm requests. This includes support for changing the timeout or indicating that the API should include stdout in the response.

algo, _ = client.Algo("util/echo")
algo.SetOptions(algorithmia.AlgoOptions{Timeout: 60, Stdout: false})

Working with data

Create directories

Create directories by instantiating a DataDirectory object and calling Create:

client.Dir("data://.my/foo").Create(nil) //nil for default access control (private)
Upload files to a directory

Upload files by calling Put on a DataFile object.

foo := client.Dir("data://.my/foo")
foo.File("sample.txt").Put("sample text contents")
foo.File("binary_file").Put([]byte{72, 101, 108, 108, 111})

Note: you can instantiate a DataFile by either client.File(filepath) or client.Dir(path).File(filename)

Download contents of file

Download files by calling StringContents, Bytes, Json, or File on a DataFile object:

foo := client.Dir("data://.my/foo")
sampleText, _ := foo.File("sample.txt").StringContents() //string object
fmt.Println(sampleText)                                  //"sample text contents"

binaryContent, _ := foo.File("binary_file").Bytes()      //binary data
fmt.Println(string(binaryContent))                       //"Hello"

tempFile, _ := foo.File("binary_file").File()            //Open file descriptor for read
defer tempFile.Close()
binaryContent, _ = ioutil.ReadAll(tempFile)
fmt.Println(string(binaryContent))                       //"Hello"
Delete files and directories

Delete files and directories by calling Delete on their respective DataFile or DataDirectory object. DataDirectories have ForceDelete method that deletes the directory even it contains files or other directories.

foo := client.Dir("data://.my/foo")
foo.ForceDelete() // force deleting the directory and its contents
List directory contents

Iterate over the contents of a directory using the channel returned by calling List, Files, or Dirs on a DataDirectory object:

foo := client.Dir("data://.my/foo")

// List files in "foo"
for entry := range foo.Files() {
	if entry.Err == nil {
		file := entry.Object.(*algorithmia.DataFile)
		fmt.Println(file.Path(), "at URL:", file.Url(), "last modified:", file.LastModified())

// List directories in "foo"
for entry := range foo.Dirs() {
	if entry.Err == nil {
		dir := entry.Object.(*algorithmia.DataDirectory)
		fmt.Println(dir.Path(), "at URL:", dir.Url())

// List everything in "foo"
for entry := range foo.List() {
	if entry.Err == nil {
		fmt.Println(entry.Object.Path(), "at URL:", entry.Object.Url())
Manage directory permissions

Directory permissions may be set when creating a directory, or may be updated on already existing directories.

foo := client.Dir("data://.my/foo")

//ReadAclPublic is a wrapper for &Acl{AclTypePublic} to make things easier

acl, _ := foo.Permissions()                             //Acl object
fmt.Println(acl.ReadAcl() == algorithmia.AclTypePublic) //true

acl, _ = foo.Permissions()                               //Acl object
fmt.Println(acl.ReadAcl() == algorithmia.AclTypePrivate) //true

Running tests

To run all test files:

export ALGORITHMIA_API_KEY={{Your API key here}}
cd test
go test -v

To run particular test:

export ALGORITHMIA_API_KEY={{Your API key here}}
cd test
go test datadirlarge_test.go -v


Many thanks to Osman Bineev (algebraic-brain) for fully implementing the Algorithmia client spec in Go. This repo is an officially supported fork of his implementation.



Algorithmia API Client (Go)



This section is empty.


View Source
var InvalidPath = errors.New("Invalid path")
View Source
var NoAclProvided = errors.New("Response does not contain read ACL")
View Source
var ReadAclMyAlgos = &Acl{AclTypeMyAlgos}
View Source
var ReadAclPrivate = &Acl{AclTypePrivate}
View Source
var ReadAclPublic = &Acl{AclTypePublic}


func PathJoin

func PathJoin(parent, base string) string


type Acl

type Acl struct {
	// contains filtered or unexported fields

func (*Acl) ReadAcl

func (a *Acl) ReadAcl() AclType

type AclType

type AclType int
const (
	AclTypePublic AclType = iota
	AclTypeDefault = AclTypeMyAlgos

func (AclType) AclString

func (t AclType) AclString() string

func (AclType) Pseudonym

func (t AclType) Pseudonym() string

func (AclType) String

func (t AclType) String() string

type AlgoOptions

type AlgoOptions struct {
	Timeout         int
	Stdout          bool
	Output          OutputType
	QueryParameters url.Values

type AlgoResponse

type AlgoResponse struct {
	Result   interface{} `json:"result"`
	Metadata *Metadata   `json:"metadata"`
	Error    *Err        `json:"error"` //never set!

func (*AlgoResponse) String

func (resp *AlgoResponse) String() string

type Algorithm

type Algorithm struct {
	// contains filtered or unexported fields

func NewAlgorithm

func NewAlgorithm(client *Client, ref string) (*Algorithm, error)

func (*Algorithm) Path

func (algo *Algorithm) Path() string

func (*Algorithm) Pipe

func (algo *Algorithm) Pipe(input1 interface{}) (interface{}, error)

Pipe an input into this algorithm

func (*Algorithm) SetOptions

func (algo *Algorithm) SetOptions(opt AlgoOptions)

func (*Algorithm) Url

func (algo *Algorithm) Url() string

type AsyncResponse

type AsyncResponse struct {
	AsyncProtocol string `json:"async_protocol"`
	RequestId     string `json:"request_id"`
	Error         *Err   `json:"error"` //never set!

Response from the API for an asynchronous request (output=void)

func (*AsyncResponse) String

func (resp *AsyncResponse) String() string

type Client

type Client struct {
	// contains filtered or unexported fields

func NewClient

func NewClient(apiKey, apiAddress string) *Client

func (*Client) Algo

func (c *Client) Algo(ref string) (*Algorithm, error)

func (*Client) Dir

func (c *Client) Dir(dataUrl string) *DataDirectory

func (*Client) File

func (c *Client) File(dataUrl string) *DataFile

type DataDirectory

type DataDirectory struct {
	// contains filtered or unexported fields

func NewDataDirectory

func NewDataDirectory(client *Client, dataUrl string) *DataDirectory

func (*DataDirectory) Create

func (f *DataDirectory) Create(acl *Acl) error

Creates a directory, optionally include non-nil Acl argument to set permissions

func (*DataDirectory) Delete

func (f *DataDirectory) Delete() error

Delete directory if it's empty

func (*DataDirectory) Dir

func (f *DataDirectory) Dir(name string) *DataDirectory

func (*DataDirectory) Dirs

func (f *DataDirectory) Dirs() <-chan SubobjectResult

func (*DataDirectory) Exists

func (f *DataDirectory) Exists() (bool, error)

func (*DataDirectory) File

func (f *DataDirectory) File(name string) *DataFile

func (*DataDirectory) Files

func (f *DataDirectory) Files() <-chan SubobjectResult

func (*DataDirectory) ForceDelete

func (f *DataDirectory) ForceDelete() error

Forcibly delete directory (even non-empty)

func (*DataDirectory) List

func (f *DataDirectory) List() <-chan SubobjectResult

func (*DataDirectory) Name

func (f *DataDirectory) Name() (string, error)

func (*DataDirectory) Path

func (f *DataDirectory) Path() string

func (*DataDirectory) Permissions

func (f *DataDirectory) Permissions() (*Acl, error)

Returns permissions for this directory or None if it's a special collection such as

.session or .algo

func (*DataDirectory) SetAttributes

func (f *DataDirectory) SetAttributes(attr *DirAttributes) error

func (*DataDirectory) UpdatePermissions

func (f *DataDirectory) UpdatePermissions(acl *Acl) error

func (*DataDirectory) Url

func (f *DataDirectory) Url() string

type DataFile

type DataFile struct {
	// contains filtered or unexported fields

func NewDataFile

func NewDataFile(client *Client, dataUrl string) *DataFile

func (*DataFile) Bytes

func (f *DataFile) Bytes() ([]byte, error)

func (*DataFile) Delete

func (f *DataFile) Delete() error

Delete from data api

func (*DataFile) Exists

func (f *DataFile) Exists() (bool, error)

func (*DataFile) File

func (f *DataFile) File() (*os.File, error)

Get file from the data api

func (*DataFile) Json

func (f *DataFile) Json(x interface{}) error

func (*DataFile) LastModified

func (f *DataFile) LastModified() time.Time

func (*DataFile) Name

func (f *DataFile) Name() (string, error)

func (*DataFile) Path

func (f *DataFile) Path() string

func (*DataFile) Put

func (f *DataFile) Put(data interface{}) error

Post to data api

func (*DataFile) PutBytes

func (f *DataFile) PutBytes(data []byte) error

func (*DataFile) PutFile

func (f *DataFile) PutFile(fpath string) error

Post file to data api

func (*DataFile) PutJson

func (f *DataFile) PutJson(data interface{}) error

Post json to data api

func (*DataFile) SetAttributes

func (f *DataFile) SetAttributes(attr *FileAttributes) error

func (*DataFile) Size

func (f *DataFile) Size() int64

func (*DataFile) StringContents

func (f *DataFile) StringContents() (string, error)

func (*DataFile) Url

func (f *DataFile) Url() string

type DataObject

type DataObject interface {
	IsFile() bool         //Returns whether object is a file
	IsDir() bool          //Returns whether object is a directory
	Type() DataObjectType //Returns type of this DataObject
	Path() string
	Url() string

type DataObjectType

type DataObjectType int
const (
	File DataObjectType = iota
const DataObjectNone DataObjectType = -1

func (DataObjectType) IsDir

func (obj DataObjectType) IsDir() bool

Returns whether object is a directory

func (DataObjectType) IsFile

func (obj DataObjectType) IsFile() bool

Returns whether object is a file

func (DataObjectType) Type

func (obj DataObjectType) Type() DataObjectType

Returns type of DataObject

type DirAttributes

type DirAttributes struct {
	Name string `json:"name" mapstructure:"name"`

type Err

type Err struct {
	Message    string `json:"message" mapstructure:"message"`
	Stacktrace string `json:"stacktrace" mapstructure:"stacktrace"`

func (*Err) Error

func (e *Err) Error() string

type FileAttributes

type FileAttributes struct {
	FileName     string `json:"filename"`
	LastModified string `json:"last_modified"`
	Size         int64  `json:"size"`

type Metadata

type Metadata struct {
	ContentType string  `json:"content_type"`
	Duration    float64 `json:"duration"`
	Stdout      bool    `json:"stdout"`

func (*Metadata) String

func (d *Metadata) String() string

type OutputType

type OutputType int
const (
	Default OutputType = iota

type SubobjectResult

type SubobjectResult struct {
	Object DataObject
	Err    error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL