cloudsight

README

cloudsight-go

A simple CloudSight API Client for Go programming language.

Status

This package is currently in beta status. It means the API may still change in backwards incompatible way.

Installation

$ go get github.com/cloudsight/cloudsight-go

Configuration

You need your API key and secret (if using OAuth1 authentication). They are available on CloudSight site after you sign up and create a project.

Usage

Import the cloudsight package:

import (
    ...

    "github.com/cloudsight/cloudsight-go"
)

Create a client instance using simple key-based authentication:

client, err := cloudsight.NewClientSimple("your-api-key")

Or, using OAuth1 authentication:

client, err := cloudsight.NewClientOAuth("your-api-key", "your-api-secret")

Send the image request using a file:

f, err := os.Open("your-file.jpg")
if err != nil {
	panic(err)
}

defer f.Close()

params := cloudsight.Params{}
params.SetLocale("en")
job, err := client.ImageRequest(f, "your-file.jpg", params)

Or, you can send the image request using a URL:

params := cloudsight.Params{}
params.SetLocale("en")
job, err := client.RemoteImageRequest("http://www.example.com/image.jpg", params)

Then, update the job status to see if it's already processed:

err := client.UpdateJob(job)
if job != cloudsight.StatusNotCompleted {
	// Done!
}

It usually takes 6-12 seconds to receive a completed response. You may use WaitJob() method to wait until the image is processed:

err := client.WaitJob(job, 30 * time.Second)

Note that Params is just a map[string]string so you may choose to use more "dynamic" approach:

params := map[string]string{
	"image_request[locale]": "en",
}
job, err := client.RemoteImageRequest("http://www.example.com/image.jpg", cloudsight.Params(params))

Consult the complete documentation.

Documentation

Overview

A simple CloudSight API client library. For full API documentation go to https://cloudsight.readme.io/v1.0/docs.

Index

• Constants
• Variables
• type Client
  • func NewClientOAuth(key, secret string) (*Client, error)
  • func NewClientSimple(key string) (*Client, error)
  • func (c *Client) ImageRequest(image io.Reader, filename string, params Params) (*Job, error)
  • func (c *Client) RemoteImageRequest(url string, params Params) (*Job, error)
  • func (c *Client) RepostJob(job *Job) error
  • func (c *Client) UpdateJob(job *Job) error
  • func (c *Client) WaitJob(job *Job, timeout time.Duration) error
• type Job
• type JobStatus
  • func (s JobStatus) Description() string
• type Params
  • func (p Params) SetAltitude(alt float64)
  • func (p Params) SetDeviceID(id string)
  • func (p Params) SetFocusAbsolute(x, y int) error
  • func (p Params) SetFocusRelative(x, y float64) error
  • func (p Params) SetLanguage(lang string)
  • func (p Params) SetLatitude(lat float64) error
  • func (p Params) SetLocale(locale string)
  • func (p Params) SetLongitude(lon float64) error
  • func (p Params) SetMaxTTL()
  • func (p Params) SetPosition(lat, lon, alt float64) error
  • func (p Params) SetTTL(ttl int) error
• type SkipReason
  • func (r SkipReason) Description() string

Examples

• Client.ImageRequest
• Client.RemoteImageRequest
• Client.UpdateJob

Constants

const BaseURL = "https://api.cloudsightapi.com"

Base API URL.

const DefaultLocale = "en-US"

Default locale that will be used when none is specified in Params.

Variables

var (
	ErrMissingKey          = errors.New("key cannot be empty")
	ErrMissingSecret       = errors.New("secret cannot be empty")
	ErrTimeout             = errors.New("poll timed out")
	ErrInvalidRepostStatus = errors.New("the job needs to have the timeout status")
)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClientOAuth

func NewClientOAuth(key, secret string) (*Client, error)

Create a new Client instance that will authenticate using OAuth1 protocol.

Error (ErrMissingKey or ErrMissingSecret) will be returned if either key or secret is empty.

func NewClientSimple

func NewClientSimple(key string) (*Client, error)

Create a new Client instance that will authenticate using simple key-based method.

ErrMissingKey will be returned if key is empty.

func (*Client) ImageRequest

func (c *Client) ImageRequest(image io.Reader, filename string, params Params) (*Job, error)

Send an image for classification. The image may be a os.File instance any other object implementing io.Reader interface. The params parameter is optional and may be nil.

On success this method will immediately return a Job instance. Its status will initially be "not completed" as it usually takes 6-12 seconds for the server to process an image. In order to retrieve the annotation data, you need to keep updating the job status using the UpdateJob() method until the status changes. You may also use the WaitJob() method which does this automatically.

Example

c, _ := NewClientSimple("api-key")
f, _ := os.Open("some-file.jpg")
defer f.Close()

params := Params{}
// Set the position to 50.0°N 19.0°E
params.SetLatitude(50.0)
params.SetLongitude(19.0)

job, err := c.ImageRequest(f, "some-file.jpg", params)
if err != nil {
	panic(err)
}

fmt.Println("Token:", job.Token)

func (*Client) RemoteImageRequest

func (c *Client) RemoteImageRequest(url string, params Params) (*Job, error)

Send an image for classification. The image will be retrieved from the URL specified. The params parameter is optional and may be nil.

On success this method will immediately return a Job instance. Its status will initially be "not completed" as it usually takes 6-12 seconds for the server to process an image. In order to retrieve the annotation data, you need to keep updating the job status using the UpdateJob() method until the status changes. You may also use the WaitJob() method which does this automatically.

Example

c, _ := NewClientSimple("api-key")
params := Params{}
// Set the position to 50.0°N 19.0°E
params.SetLatitude(50.0)
params.SetLongitude(19.0)

job, err := c.RemoteImageRequest("http://www.example.com/some-image.jpg", params)
if err != nil {
	panic(err)
}

fmt.Println("Token:", job.Token)

func (*Client) RepostJob

func (c *Client) RepostJob(job *Job) error

Repost the job if it has timed out (StatusTimeout).

ErrInvalidRepostStatus will be returned if current job status is different than StatusTimeout.

func (*Client) UpdateJob

func (c *Client) UpdateJob(job *Job) error

Contact the server and update the job status. This method does nothing if the status has already changed from "not completed".

After a request has been submitted, it usually takes 6-12 seconds to receive a completed response. We recommend polling for a response every 1 second after a 4 second delay from the initial request, while the status is "not completed". WaitJob() method does this automatically.

Example

c, _ := NewClientSimple("api-key")
job, _ := c.RemoteImageRequest("http://www.example.com/some-image.jpg", nil)

time.Sleep(3 * time.Second)

for job.Status == StatusNotCompleted {
	time.Sleep(1 * time.Second)
	c.UpdateJob(job)
}

fmt.Println("Status:", job.Status, job.Status.Description())

func (*Client) WaitJob

func (c *Client) WaitJob(job *Job, timeout time.Duration) error

Wait for the job until it has been processed. This method will block for up to timeout seconds. After that ErrTimeout will be returned. If the timeout parameter is set to 0, WaitJob() will wait infinitely.

This method will wait for 4 seconds after the initial request and then will call UpdateJob() method every second until the status changes.

type Job

type Job struct {
	// Image description as annotated by the API.
	Name string

	// Current job status.
	Status JobStatus

	// Time To Live.
	TTL float64

	// Token uniquely identifying the job.
	Token string

	// URL to the image as stored on CloudSight API servers.
	URL string

	// The reason for the job being skipped, if any.
	SkipReason SkipReason
	// contains filtered or unexported fields
}

Job is a result of sending an image to CloudSight API.

type JobStatus

type JobStatus string

Possible values for current job status.

const (
	// Recognition has not yet been completed for this image. Continue polling
	// until response has been marked completed.
	StatusNotCompleted JobStatus = "not completed"

	// Recognition has been completed. Annotation can be found in Name and
	// Categories field of Job structure.
	StatusCompleted JobStatus = "completed"

	// Token supplied on URL does not match an image.
	StatusNotFound JobStatus = "not found"

	// Image couldn't be recognized because of a specific reason. Check the
	// SkipReason field.
	StatusSkipped JobStatus = "skipped"

	// Recognition process exceeded the allowed TTL setting.
	StatusTimeout JobStatus = "timeout"
)

func (JobStatus) Description

func (s JobStatus) Description() string

Return a detailed description of the job status.

type Params

type Params map[string]string

Additional API parameters.

func (Params) SetAltitude

func (p Params) SetAltitude(alt float64)

Set the altitude for additional geolocation context.

func (Params) SetDeviceID

func (p Params) SetDeviceID(id string)

Set a unique ID generated for the device sending the request. We recommend generating a UUID.

func (Params) SetFocusAbsolute

func (p Params) SetFocusAbsolute(x, y int) error

Set an absolute focal point on image for specificity.

The point uses North-West gravity (0, 0 corresponds to upper-left corner), for which to place a hightlight of attention on the image. In the event there are many identifiable objects in the image, this attempts to place importance on the ones closest to the focal point. This method accepts absolute coordinates (ie. a 400x400 image would have 0 through 400 for each axis).

func (Params) SetFocusRelative

func (p Params) SetFocusRelative(x, y float64) error

Set a relative focal point on image for specificity.

The point uses North-West gravity (0.0, 0.0 corresponds to upper-left corner), for which to place a hightlight of attention on the image. In the event there are many identifiable objects in the image, this attempts to place importance on the ones closest to the focal point. This method accepts relative coordinates (0.0 through 1.0).

func (Params) SetLanguage

func (p Params) SetLanguage(lang string)

Set the language of the request. The response will be returned in this language. The default is "en".

func (Params) SetLatitude

func (p Params) SetLatitude(lat float64) error

Set the latitude for additional geolocation context.

func (Params) SetLocale

func (p Params) SetLocale(locale string)

Set the locale of the request. Default is "en-US".

func (Params) SetLongitude

func (p Params) SetLongitude(lon float64) error

Set the longitute for additional geolocation context.

func (Params) SetMaxTTL

func (p Params) SetMaxTTL()

Set the maximum deadline before expired state is set.

func (Params) SetPosition

func (p Params) SetPosition(lat, lon, alt float64) error

Set the position for additional geolocation context.

func (Params) SetTTL

func (p Params) SetTTL(ttl int) error

Set the deadline in seconds before expired state is set. Use a high ttl for low-priority image requests. Use `SetMaxTTL()` for maximum deadline.

type SkipReason

type SkipReason string

The API may choose not to return any response for given image. SkipReason type includes possible reasons for such behavior.

const (
	// Offensive image content.
	ReasonOffensive SkipReason = "offensive"

	// Too blurry to identify.
	ReasonBlurry SkipReason = "blurry"

	// Too close to identify.
	ReasonClose SkipReason = "close"

	// Too dark to identify.
	ReasonDark SkipReason = "dark"

	// Too bright to identify.
	ReasonBright SkipReason = "bright"

	// Content could not be identified.
	ReasonUnsure SkipReason = "unsure"
)

func (SkipReason) Description

func (r SkipReason) Description() string

Return a detailed description of the skip reason.