openaq

package module
v0.0.0-...-6c70f38 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 28, 2023 License: MIT Imports: 11 Imported by: 8

README

OpenAQ Golang API Client

This library is in early development. DO NOT USE UNTIL 1.0.0 RELEASE

A low-level golang wrapper around the OpenAQ v3 REST API.

Usage
Client

A client is initialized with a configuration struct which holds some global configuration for interacting with the API.

client := NewClient(Config{
    APIKey: "my-openaq-api-key-123456-7890"
})

All methods take a context.Context as the first parameter to allow for context level cancellation and deadlines.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	// Error message.
	Message string `json:"message"`
	// HTTP code.
	Code int
}

func (APIError) Error

func (err APIError) Error() string

func (APIError) String

func (err APIError) String() string

type BaseArgs

type BaseArgs struct {
	//
	Limit int64
	//
	Page int64
}

func (*BaseArgs) Values

func (b *BaseArgs) Values(q url.Values) (url.Values, error)

type Bbox

type Bbox struct {
	Type        string        `json:"type"`
	Coordinates []interface{} `json:"coordinates"`
}

bounding box to define the geographic bounds of the data coordinates in the form of []

type Client

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

func NewClient

func NewClient(config Config) (*Client, error)

New creates a new OpenAQ client.

func (*Client) GetCountries

func (c *Client) GetCountries(ctx context.Context, countryArgs CountryArgs) (*CountriesResponse, error)

GetCountries fetches all countries filtered by any params passed.

func (*Client) GetCountry

func (c *Client) GetCountry(ctx context.Context, countriesID int64) (*CountriesResponse, error)

GetCountry fetches a single country by ID.

func (*Client) GetInstrument

func (c *Client) GetInstrument(ctx context.Context, instrumentsID int64) (*InstrumentsResponse, error)

GetInstrument fetches a single instrument by ID.

func (*Client) GetInstruments

func (c *Client) GetInstruments(ctx context.Context, args InstrumentArgs) (*InstrumentsResponse, error)

GetInstruments fetches all instruments filtered by any params passed.

func (*Client) GetLocation

func (c *Client) GetLocation(ctx context.Context, locationsID int64) (*LocationsResponse, error)

GetLocation fetches a single location by ID.

func (*Client) GetLocationMeasurements

func (c *Client) GetLocationMeasurements(ctx context.Context, locationsID int64, args MeasurementsArgs) (*MeasurementsResponse, error)

GetLocationMeasurements fetches measurements for a single location by ID and any params passed

func (*Client) GetLocationSensors

func (c *Client) GetLocationSensors(ctx context.Context, locationsID int64) (*SensorsResponse, error)

GetSensors fetches all sensors of a given location

func (*Client) GetLocations

func (c *Client) GetLocations(ctx context.Context, args LocationArgs) (*LocationsResponse, error)

GetLocations fetches all locations filtered by any params passed.

func (*Client) GetManufacturer

func (c *Client) GetManufacturer(ctx context.Context, manufacturersID int64) (*ManufacturersResponse, error)

GetManufacturer fetches a single manufacturer by ID.

func (*Client) GetManufacturerInstruments

func (c *Client) GetManufacturerInstruments(ctx context.Context, manufacturerID int64) (*InstrumentsResponse, error)

GetManufacturerInstruments fetches instruments by manufacturer ID.

func (*Client) GetManufacturers

func (c *Client) GetManufacturers(ctx context.Context, args ManufacturerArgs) (*ManufacturersResponse, error)

GetManufacturers fetches all manufacturers filtered by any params passed.

func (*Client) GetOwner

func (c *Client) GetOwner(ctx context.Context, OwnersID int64) (*OwnersResponse, error)

GetOwner fetches a single owner by ID.

func (*Client) GetOwners

func (c *Client) GetOwners(ctx context.Context, args OwnersArgs) (*OwnersResponse, error)

GetOwners fetches all owners filtered by any params passed.

func (*Client) GetParameter

func (c *Client) GetParameter(ctx context.Context, parametersID int64) (*ParametersResponse, error)

GetParameter fetches a single parameter by ID.

func (*Client) GetParameters

func (c *Client) GetParameters(ctx context.Context, args ParametersArgs) (*ParametersResponse, error)

GetParameters fetches all parameters filtered by any params passed.

func (*Client) GetProvider

func (c *Client) GetProvider(ctx context.Context, providersID int64) (*ProvidersResponse, error)

GetProvider fetches a single provider by ID.

func (*Client) GetProviders

func (c *Client) GetProviders(ctx context.Context, args ProvidersArgs) (*ProvidersResponse, error)

GetProviders fetches all providers filtered by any params passed.

func (*Client) GetSensor

func (c *Client) GetSensor(ctx context.Context, SensorsID int64) (*SensorsResponse, error)

GetSensor fetches a single Sensor by ID.

func (*Client) GetSensorMeasurements

func (c *Client) GetSensorMeasurements(ctx context.Context, sensorsID int64, args MeasurementsArgs) (*MeasurementsResponse, error)

GetSensorMeasurements fetches measurements for a single sensor by ID and any params passed

func (*Client) GetTrends

func (c *Client) GetTrends(ctx context.Context, locationsID int64, parameterID int64) (*TrendsResponse, error)

GetTrends fetches trends of a given location and parameter ID

type ClientError

type ClientError struct {
	ErrorType ErrorType
	Message   string
}

func (ClientError) Error

func (err ClientError) Error() string

func (ClientError) String

func (err ClientError) String() string

type Config

type Config struct {
	// BaseURLScheme is the url scheme to use defaults to https
	BaseURLScheme string
	// BaseURLHost is the base url to use defualts to api.openaq.org
	BaseURLHost string
	// APIKey is an optional API key.
	APIKey string
	// userAgent is an optional HTTP header.
	UserAgent string
	// HTTPHeaders are additional optional HTTP headers.
	HttpHeaders map[string]string
	// Client provides an optional HTTP client, otherwise a default will be used.
	Client *http.Client
}

Config contains client configuration.

type Coordinates

type Coordinates struct {
	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`
}

a coordinate pair of latitude and longitude in WGS84

type CoordinatesArgs

type CoordinatesArgs struct {
	Lat float64
	Lon float64
}

type Countries

type Countries struct {
	// a slice of countries IDs
	IDs []int64
}

func (*Countries) Values

func (args *Countries) Values(q url.Values) url.Values

type CountriesResponse

type CountriesResponse struct {
	Meta    Meta      `json:"meta"`
	Results []Country `json:"results"`
}

type Country

type Country struct {
	ID            int64           `json:"id"`
	Code          string          `json:"code"`
	Name          string          `json:"name"`
	DatetimeFirst time.Time       `json:"datetimeFirst"`
	DatetimeLast  time.Time       `json:"datetimeLast"`
	Parameters    []ParameterBase `json:"parameters"`
}

type CountryArgs

type CountryArgs struct {
	//
	BaseArgs BaseArgs
}

func (CountryArgs) QueryParams

func (countryArgs CountryArgs) QueryParams() (url.Values, error)

type Datetime

type Datetime struct {
	UTC   time.Time `json:"utc"`
	Local time.Time `json:"local"`
}

type ErrorType

type ErrorType int
const (
	MissingParamError ErrorType = iota
)

func (ErrorType) String

func (e ErrorType) String() string

type Instrument

type Instrument struct {
	ID           int64            `json:"id"`
	Name         string           `json:"name"`
	Manufacturer ManufacturerBase `json:"manufacturer"`
}

type InstrumentArgs

type InstrumentArgs struct {
	BaseArgs BaseArgs
}

func (InstrumentArgs) QueryParams

func (instrumentArgs InstrumentArgs) QueryParams() (url.Values, error)

QueryParams translates InstrumentArgs struct into url.Values

type InstrumentBase

type InstrumentBase struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
}

type InstrumentsResponse

type InstrumentsResponse struct {
	Meta    Meta         `json:"meta"`
	Results []Instrument `json:"results"`
}

type Location

type Location struct {
	ID       int64  `json:"id"`
	Name     string `json:"name"`
	Locality string `json:"locality"`
	Timezone string `json:"timezone"`
	Country  struct {
		ID   int64  `json:"id"`
		Code string `json:"code"`
		Name string `json:"name"`
	} `json:"country"`
	Owner struct {
		ID   int64  `json:"id"`
		Name string `json:"name"`
	} `json:"owner"`
	Provider      ProviderBase     `json:"provider"`
	IsMobile      bool             `json:"isMobile"`
	IsMonitor     bool             `json:"isMonitor"`
	Instruments   []InstrumentBase `json:"instruments"`
	Sensors       []SensorBase     `json:"sensors"`
	Coordinates   Coordinates      `json:"coordinates"`
	Bounds        []float64        `json:"bounds"`
	Distance      float64          `json:"distance"`
	DatetimeFirst Datetime         `json:"datetimeFirst"`
	DatetimeLast  Datetime         `json:"datetimeLast"`
}

type LocationArgs

type LocationArgs struct {
	//
	BaseArgs *BaseArgs
	// Coordinates represents latitude,longitude (y,x) values to center the search
	// must be paired with Radius
	Coordinates *CoordinatesArgs
	// Radius represents the distance in meters from the Coordinates position
	// to search, must be paired with Coordinates
	Radius int64
	// Bbox is a bounding box to search within and is represented as a slice of four coordinates
	// in the form [ymin xmin ymax xmax]
	Bbox []float64
	// IsoCode is the ISO 3166-1 alpha-2 country code, unlike countries ID ISO code searching can only accept
	// a single value and not a slice of values
	IsoCode string
	// Monitor allows filtering for reference grade/regulatory monitors vs air sensors (AKA low-cost sensors)
	Monitor *bool
	// Mobile allowing filtering for mobile locations vs stationary locations
	Mobile bool
	// A slice of owners IDs
	OwnersIDs []int64
	//
	Countries *Countries
	//
	Providers *Providers
}

func (LocationArgs) QueryParams

func (locationArgs LocationArgs) QueryParams() (url.Values, error)

QueryParams translates LocationArgs struct into url.Values

func (*LocationArgs) Values

func (locationArgs *LocationArgs) Values(q url.Values) (url.Values, error)

type LocationsResponse

type LocationsResponse struct {
	Meta    Meta       `json:"meta"`
	Results []Location `json:"results"`
}

type Manufacturer

type Manufacturer struct {
	ID          int64            `json:"id"`
	Name        string           `json:"name"`
	Instruments []InstrumentBase `json:"instruments"`
}

type ManufacturerArgs

type ManufacturerArgs struct {
	BaseArgs BaseArgs
}

func (ManufacturerArgs) QueryParams

func (manufacturerArgs ManufacturerArgs) QueryParams() (url.Values, error)

QueryParams translates ManufacturerArgs struct into url.Values

type ManufacturerBase

type ManufacturerBase struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
}

type ManufacturersResponse

type ManufacturersResponse struct {
	Meta    Meta           `json:"meta"`
	Results []Manufacturer `json:"results"`
}

type Measurement

type Measurement struct {
	Period      period        `json:"period"`
	Value       float64       `json:"value"`
	Parameter   ParameterBase `json:"parameter"`
	Coordinates Coordinates   `json:"coordinates"`
	Summary     summary       `json:"summary"`
	Coverage    coverage      `json:"coverage"`
}

type MeasurementsArgs

type MeasurementsArgs struct {
	BaseArgs     BaseArgs
	DatetimeFrom time.Time
	DatetimeTo   time.Time
	Parameters   *Parameters
	PeriodName   string
}

func (MeasurementsArgs) QueryParams

func (args MeasurementsArgs) QueryParams() (url.Values, error)

QueryParams translates MeasurementsArgs struct into url.Values

func (*MeasurementsArgs) Values

func (m *MeasurementsArgs) Values(q url.Values) (url.Values, error)

type MeasurementsResponse

type MeasurementsResponse struct {
	Meta    Meta          `json:"meta"`
	Results []Measurement `json:"results"`
}

type Meta

type Meta struct {
	Name    string `json:"name"`
	Website string `json:"website"`
	Page    int64  `json:"page"`
	Limit   int64  `json:"limit"`
	Found   any    `json:"found"`
}

type Owner

type Owner struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
}

type OwnerBase

type OwnerBase struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
}

type OwnerEntityBase

type OwnerEntityBase struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
}

type OwnersArgs

type OwnersArgs struct {
	BaseArgs BaseArgs
}

func (OwnersArgs) QueryParams

func (args OwnersArgs) QueryParams() (url.Values, error)

QueryParams translates OwnerArgs struct into url.Values

func (*OwnersArgs) Values

func (ownersArgs *OwnersArgs) Values(q url.Values) (url.Values, error)

type OwnersResponse

type OwnersResponse struct {
	Meta    Meta    `json:"meta"`
	Results []Owner `json:"results"`
}

type Parameter

type Parameter struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	Units       string `json:"units"`
	DisplayName string `json:"displayName"`
	Description string `json:"description"`
}

type ParameterBase

type ParameterBase struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	Units       string `json:"units"`
	DisplayName string `json:"displayName"`
}

type Parameters

type Parameters struct {
	//
	IDs []int64
}

func (*Parameters) Values

func (parameters *Parameters) Values(q url.Values) url.Values

type ParametersArgs

type ParametersArgs struct {
	BaseArgs      BaseArgs
	ParameterType string
}

func (ParametersArgs) QueryParams

func (parametersArgs ParametersArgs) QueryParams() (url.Values, error)

QueryParams translates ParametersArgs struct into url.Values

func (*ParametersArgs) Values

func (parametersArgs *ParametersArgs) Values(q url.Values) (url.Values, error)

type ParametersResponse

type ParametersResponse struct {
	Meta    Meta        `json:"meta"`
	Results []Parameter `json:"results"`
}

type Provider

type Provider struct {
	ID            int64           `json:"id"`
	Name          string          `json:"name"`
	SourceName    string          `json:"sourceName"`
	ExportPrefix  string          `json:"exportPrefix"`
	License       string          `json:"license"`
	DatetimeAdded time.Time       `json:"datetimeAdded"`
	DatetimeFirst time.Time       `json:"datetimeFirst"`
	DatetimeLast  time.Time       `json:"datetimeLast"`
	OwnerEntity   OwnerEntityBase `json:"ownerEntity"`
	Parameters    []ParameterBase `json:"parameters"`
	Bbox          Bbox            `json:"bbox"`
}

type ProviderBase

type ProviderBase struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	Units       string `json:"units"`
	DisplayName string `json:"displayName"`
}

type Providers

type Providers struct {
	//
	IDs []int64
}

func (*Providers) Values

func (providers *Providers) Values(q url.Values) url.Values

type ProvidersArgs

type ProvidersArgs struct {
	BaseArgs BaseArgs
}

func (ProvidersArgs) QueryParams

func (providersArgs ProvidersArgs) QueryParams() (url.Values, error)

QueryParams translates ProvidersArgs struct into url.Values

func (*ProvidersArgs) Values

func (providersArgs *ProvidersArgs) Values(q url.Values) (url.Values, error)

type ProvidersResponse

type ProvidersResponse struct {
	Meta    Meta       `json:"meta"`
	Results []Provider `json:"results"`
}

type SensorArgs

type SensorArgs struct {
	BaseArgs BaseArgs
}

func (SensorArgs) QueryParams

func (args SensorArgs) QueryParams() (url.Values, error)

QueryParams translates SensorArgs struct into url.Values

type SensorBase

type SensorBase struct {
	ID        int64         `json:"id"`
	Name      string        `json:"name"`
	Parameter ParameterBase `json:"parameter"`
}

type SensorsResponse

type SensorsResponse struct{}

type TrendsArgs

type TrendsArgs struct {
	BaseArgs BaseArgs
}

func (TrendsArgs) QueryParams

func (args TrendsArgs) QueryParams() (url.Values, error)

QueryParams translates TrendsArgs struct into url.Values

type TrendsResponse

type TrendsResponse struct{}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL