Introduction

This is the documentation for the Go client for Objectia® API. You can find the source code for the client on GitHub. We have API clients in several other programming languages hosted on GitHub.

Requirements

The Go client for Objectia API requires golang version 1.8 or later. To check the version of your golang environment, type the following in the terminal window:

go version

You should see something like:

go version go1.12.3 darwin/amd64

If you do not have go installed, head over to golang.org and download the appropriate installer for your system. Once you've installed go, return to your terminal and run the command above once again. If you don't see the installed go version, you may need to relaunch your terminal.

Installation

To install the client library, use go get like you normanlly do:

go get github.com/objectia/objectia-go

Using

Import the library into your code as objectia:

import "github.com/objectia/objectia-go"

TIP

If you do not have an API Key, you can easily generate one by heading over to the API settings page.

Authentication

After importing the library, you can create an API client.

apiKey := "your-api-key"
client, err := objectia.NewClient(apiKey, nil)

IMPORTANT

We recommend that you load API keys from an environment variable. It is bad practice to hard code it like in the example above.

Calling the API

Then we are ready to call the API:

location, err := client.GeoLocation.Get("8.8.8.8", nil)

println("Country:", location.Country)           // prints "United States"
println("Country code:", location.CountryCode)  // and    "US"

Error handling

Each client API function returns an error object with the result. The error is a pointer to an objectia.Error struct.

You handle the error in traditional golang style:

// If you enter an invalid IP address, we get an error
location, err := client.GeoLocation.Get("288.8.8.8", nil)
if err != nil {
	e, ok := err.(*objectia.Error)
	if ok {
		if e.Code == "err-invalid-ip" {
			// handle API error ...
		}
	} else {
		// other error
	}
}

You will find all the error codes in the REST API documentation.