glair

GLAIR Vision Go SDK

Requirement

• Go 1.18 or later with Go modules.

Installation

You can import the SDK in your Go files with import:

import (
    "github.com/glair-ai/glair-vision-go"
    "github.com/glair-ai/glair-vision-go/client"
)

After that, you can run go commands and let the Go toolchain resolve and fetch the SDK module automatically.

Alternatively, you can also run go get to explicitly resolve and fetch the SDK module:

go get -u github.com/glair-ai/glair-vision-go

Usage

The package needs to be configured with your credentials, see here for more detailed instructions

package main

import (
    "github.com/glair-ai/glair-vision-go"
	"github.com/glair-ai/glair-vision-go/client"
)

func main() {
    config := glair.NewConfig("<username>", "<password>", "<api_key>")

    client := client.New(config)
}

The configuration object will be initialized with the following values:

You can change the above values using the provided With<Option> method of the configuration object, for example:

package main

import (
    "github.com/glair-ai/glair-vision-go"
	"github.com/glair-ai/glair-vision-go/client"
)

func main() {
    config := glair.NewConfig("<username>", "<password>", "<api_key>")
    // set the base url to `http://localhost:3000` 
    config = config.WithBaseURL("http://localhost:3000")

    client := client.New(config)
}

Afterwards, you can use the provided functions to access GLAIR Vision API.

Documentation

For comprehensive list of available API provided by GLAIR Vision Go SDK, check out the API Documentation. You can also see the runnable examples in the examples folder. For details on all the functionality in this library, see the Go documentation.

Below are a few simple usage examples:

Perform OCR on KTP

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/glair-ai/glair-vision-go"
	"github.com/glair-ai/glair-vision-go/client"
)

func main() {
	ctx := context.Background()

	config := glair.NewConfig("", "", "")
	client := client.New(config)

	file, _ := os.Open("path/to/image.jpg")

	result, err := client.Ocr.KTP(ctx, glair.OCRInput{
		Image: file,
	})

	if err != nil {
		log.Fatalln(err.Error())
	}

  	fmt.Println(result.Read.Nama)
}

Perform OCR on Receipt by providing path to the image file

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/glair-ai/glair-vision-go"
	"github.com/glair-ai/glair-vision-go/client"
)

func main() {
	ctx := context.Background()

	config := glair.NewConfig("", "", "")
	client := client.New(config)

	result, err := client.Ocr.Receipt(ctx, glair.OCRInput{
		Image: "path/to/image.jpg",
	})

	if err != nil {
		log.Fatalln(err.Error())
	}

  	fmt.Println(result.Read.Nama)
}

Perform OCR on KTP with timeout

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/glair-ai/glair-vision-go"
	"github.com/glair-ai/glair-vision-go/client"
)

func main() {
	baseContext := context.Background()
	contextWithTimeout, cancel := context.WithTimeout(baseContext, 100*time.Millisecond)
	defer cancel()

	config := glair.NewConfig("", "", "")
	client := client.New(config)

	file, _ := os.Open("../images/ktp.jpeg")

	result, err := client.Ocr.KTP(contextWithTimeout, glair.OCRInput{
		Image: file,
	})

	if err != nil {
		if glairErr, ok := err.(*glair.Error); ok {
			switch glairErr.Code {
			case glair.ErrorCodeTimeout:
				log.Printf("Request timed out")
			default:
				log.Printf("Error: %v\n", glairErr.Code)
			}
		} else {
			log.Printf("Unexpected Error: %v\n", err)
		}

		os.Exit(1)
	}

	beautified, _ := json.MarshalIndent(result, "", "  ")

	fmt.Println(string(beautified))
}

Using custom HTTP client to intercept HTTP requests

package client

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"

	"github.com/glair-ai/glair-vision-go"
)

// MyClient is a HTTP client that adds `x-powered-by`
// header to a normal HTTP request.
//
// It wraps the default HTTP client
type MyClient struct {
	client *http.Client
}

func (c *MyClient) Do(req *http.Request) (*http.Response, error) {
	req.Header.Set("X-Powered-By", "GLAIR")

	res, err := c.client.Do(req)
	if err != nil {
		return nil, err
	}

	return res, nil
}

func main() {
	ctx := context.Background()

	config := glair.NewConfig("", "", "").WithClient(&MyClient{client: http.DefaultClient})
	client := New(config)

	file, _ := os.Open("../images/ktp.jpeg")

	result, err := client.Ocr.KTP(ctx, glair.OCRInput{
		Image: file,
	})

	if err != nil {
		log.Fatalln(err.Error())
	}

	beautified, _ := json.MarshalIndent(result, "", "  ")

	fmt.Println(string(beautified))
}

Perform face verification using GLAIR Vision Face Verification API

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/glair-ai/glair-vision-go"
	"github.com/glair-ai/glair-vision-go/client"
)

func main() {
	ctx := context.Background()

	config := glair.NewConfig("", "", "")
	client := client.New(config)

	image, _ := os.Open("path/to/image.jpg")

	result, err := client.FaceBio.FaceMatching(ctx, glair.FaceMatchingInput{
		StoredImage:   image,
		CapturedImage: image,
	})

	if err != nil {
		log.Fatalln(err.Error())
	}

	beautified, _ := json.MarshalIndent(result, "", "  ")

	fmt.Println(string(beautified))
}

Perform KTP data verification using GLAIR Identity Verification API

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/glair-ai/glair-vision-go"
	"github.com/glair-ai/glair-vision-go/client"
)

func main() {
	ctx := context.Background()

	config := glair.NewConfig("", "", "")
	client := client.New(config)

	result, err := client.Identity.BasicVerification(ctx, glair.BasicVerificationInput{
		Nik:    "",
		Name:   glair.String(""),
		Gender: glair.String(""),
		DateOfBirth: ""
	})

	if err != nil {
		log.Fatalln(err.Error())
	}

	beautified, _ := json.MarshalIndent(result, "", "  ")

	fmt.Println(string(beautified))
}

Error Handling

Whenever an error occurs, GLAIR Vision Go SDK will wrap the error into a glair.Error object that contains the following properties

It's recommended to assert the error to glair.Error whenever an error is returned, for example:

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/glair-ai/glair-vision-go"
	"github.com/glair-ai/glair-vision-go/client"
)

func main() {
	ctx := context.Background()

	config := glair.NewConfig("", "", "")
	client := client.New(config)

	file, _ := os.Open("path/to/image.jpg")

	result, err := client.Ocr.KTP(ctx, glair.OCRInput{
		Image: file,
	})

	if err != nil {
    		// is a glair.Error, assert the error code
	  	if glairErr, ok := err.(*glair.Error); ok {
      		switch glairErr.Code {
        		case glair.ErrorCodeFileError:
          			fmt.Println("Cannot read input file correctly")
        		case glair.ErrorCodeNetworkError:
          			fmt.Println("There are problems while connecting to GLAIR Vision API")
        		default:
          			fmt.Printf("GLAIR SDK returns error code: %d", glairErr.Code)
      			}
    		} else {
      			fmt.Printf("Unexpected error occured: %w", err)
    		}
	}
}

Error Code

To make debugging errors easier, GLAIR Vision Go SDK provides error code to all glair.Error objects. Below are the list of error codes that are returned by GLAIR Vision Go SDK

Response

When error with code ErrorCodeAPIError is returned, GLAIR Vision SDK with return additional context of the failure encapsulated in the Response object. The Response object has the following properties.

Logging

By default, GLAIR Vision Go SDK does not log anything regardless of severity. However, you can enable logging implementing the Logger interface from the main package and add it to the configuration object with WithLogger method.

package main

import (
	"fmt"

	"github.com/glair-ai/glair-vision-go"
	"github.com/glair-ai/glair-vision-go/client"
)

type MyLogger struct {}

func (l MyLogger) Debugf(format string, val ...interface{}) {
	// do not log debug messages
}

func (l MyLogger) Infof(format string, val ...interface{}) {
	fmt.Printf("[GLAIR - Information] " + format, val)
}

func (l MyLogger) Warnf(format string, val ...interface{}) {
	fmt.Printf("[GLAIR - Warning] " + format, val)
}

func (l MyLogger) Errorf(format string, val ...interface{}) {
	fmt.Printf("[GLAIR - Debug] " + format, val)
}

func main() {
	config := glair.NewConfig("<username>", "<password>", "<api_key>").
		WithLogger(MyLogger{})
}

The Logger interface has the following signature

type Logger interface {
	Debugf(format string, val ...interface{})
	Infof(format string, val ...interface{})
	Warnf(format string, val ...interface{})
	Errorf(format string, val ...interface{})
}

Alternatively, the SDK provides convenient LeveledLogger struct that implements the Logger interface.

type LeveledLogger struct {
	Level LogLevel
}

LeveledLogger accepts Level property that determines what messages should be logged. Below is the list of available Level for LeveledLogger

All Level property also logs any messages below their Level. For example, LeveledLogger with LevelInfo will log informational, warnings, and error messages.

License

This project is licensed under the MIT License