ambient is a Go client library for accessing the Ambient Weather API.
Currently, ambient requires Go version 1.19 or greater. We do our best not to break older versions of Go if we don't have to, but due to tooling constraints, we don't always test older versions.
ambient is compatible with modern Go releases in module mode, with Go installed:
go get github.com/lrosenman/ambientwill resolve and add the package to the current development module, along with its dependencies.
Alternatively the same can be achieved if you use import in a package:
import "github.com/lrosenman/ambient"and run go get without parameters.
Lists all devices (weather stations) that are registered for a given api key
key := ambient.NewKey("... your application key ...", "... you api key ...")
devices, err := ambient.Device(key)Queries a specific device for its last 10 observations
key := ambient.NewKey("... your application key ...", "... you api key ...")
queryResults, err := ambient.DeviceMac(key, "... device mac address ...", time.Now().UTC(), 10)More examples of how to use this library can be found in the examples directory
| Name | Purpose |
|---|---|
| list-devices | Lists all devices (weather stations) that are registered for the account the application and api keys are associated with |
| query-device | Queries a specific device for its observations |
| query-all-devices | Queries all registered devices for an account for their observations |
| print-api | Shows all API calls and the responses to them |
The Ambient Weather API uses an application key that identifies a specific application and an api key that grants access to a specific user's devices. See Ambient API Authentication documentation for more details on these values and how to generate / manage.
This is represented in the ambient library by the Key struct and is used for any calls to the API:
key := ambient.NewKey("... your application key ...", "... you api key ...")
devices, err := ambient.Device(key)Ambient Weather API requests are capped at 1 request per second for each user's apiKey and 3 requests per second for a given applicationKey. When this limit is exceeded, the API will return a 429 response code.
To determine if any of your requests have been rate limited, the HTTPResponseCode field has been added to response structs to determine the nature of a failed API call.
We would like to cover the entire Ambient Weather API and contributions are of course always welcome. See CONTRIBUTING.md for details.
In general, ambient follows semver as closely as we can for tagging releases of the package.
This library is distributed under the BSD-style license found in the LICENSE.md
file.