Globalping Go API Client

The official Go client for the Globalping API.

Installation

To install the client, run the following command:

go get github.com/jsdelivr/globalping-go

Usage

To use the client, import it into your Go code:

import "github.com/jsdelivr/globalping-go"

func main() {
  client := globalping.NewClient(globalping.Config{
    AuthToken: "<your_access_token>", // Optional
  })
}

Create Measurement

Creates a new measurement with the set parameters. The measurement runs asynchronously, and you can retrieve its current state using GetMeasurement() or wait for its final state using AwaitMeasurement().

  o := &globalping.MeasurementCreate{
    Type:   globalping.MeasurementTypePing,
    Target: "google.com",
    Limit:  1,
    Locations: globalping.LocationOptions{
      {
        Magic: "world",
      },
    },
  }

  res, err := client.CreateMeasurement(ctx, o)
  if err != nil {
    fmt.Println(err)
    return
  }

Get a measurement

Returns the current state of the measurement.

  measurement, err := client.GetMeasurement(ctx, res.ID)
  if err != nil {
    fmt.Println(err)
    return
  }

  fmt.Printf("%+v\n", measurement)

Await a measurement

Similar to GetMeasurement(), but keeps polling the API until the measurement is finished, and returns its final state.

  measurement, err := client.AwaitMeasurement(ctx, res.ID)
  if err != nil {
    fmt.Println(err)
    return
  }

  fmt.Printf("%+v\n", measurement)

Get raw measurement bytes

Returns the raw measurement bytes.

  b, err := client.GetMeasurementRaw(ctx, res.ID)
  if err != nil {
    fmt.Println(err)
    return
  }

Probes

Returns a list of all probes currently online and their metadata, such as location and assigned tags.

  probes, err := client.Probes(ctx)
  if err != nil {
    fmt.Println(err)
    return
  }

  fmt.Printf("%+v\n", probes)

Get rate limits

Returns rate limits for the current user (if authenticated) or IP address (if not authenticated).

  limits, err := client.Limits(ctx)
  if err != nil {
    fmt.Println(err)
    return
  }

  fmt.Printf("%+v\n", limits)

Error handling

HTTP failures are exposed as *globalping.HTTPError values. Use errors.As to access the response status and headers, including when the HTTP error is wrapped by an endpoint-specific error such as *globalping.MeasurementError, *globalping.ProbesError, or *globalping.LimitsError.

  measurement, err := client.GetMeasurement(ctx, res.ID)
  if err != nil {
    var httpErr *globalping.HTTPError
    if errors.As(err, &httpErr) {
      // httpErr.StatusCode
      // httpErr.Header
    } else {
      fmt.Println(err)
    }
  }

Advanced configuration

AuthToken

A user authentication token obtained from https://dash.globalping.io or via OAuth (currently available only to official Globalping apps).

UserAgent

Defaults to globalping-go/<Version> (https://github.com/jsdelivr/globalping-go), where <Version> is the current SDK version. If you build another open-source project based on this library, you should override this value to point to your project instead.

CacheExpireSeconds

Specifies the expiration time for cached measurements in seconds. 0 means no expiration.

HTTPClient

Custom HTTP client to use for requests.

Development

Please refer to CONTRIBUTING.md for more information.