Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@probakowski
probakowski committed Nov 19, 2021
1 parent db13f7f commit 5869dba
Show file tree
Hide file tree
Showing 3 changed files with 63 additions and 29 deletions.
40 changes: 37 additions & 3 deletions airly.go
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Package airly provides wrapper for Airly API https://developer.airly.org/docs
package airly

import (
Expand All @@ -8,6 +9,7 @@ import (
"time"
)

// Installation metadata, see https://developer.airly.org/docs#endpoints.installations
type Installation struct {
Id int `json:"id"`
Location Location `json:"location"`
Expand All @@ -17,11 +19,14 @@ type Installation struct {
Sponsor Sponsor `json:"sponsor"`
}

// Location represents geographical location given by coordinates, used for Nearest* APIs
// and as part of Installation metadata
type Location struct {
Latitude float64 `json:"latitude"`
Longitude float64 `json:"longitude"`
}

// Address of Installation
type Address struct {
Country string `json:"country"`
City string `json:"city"`
Expand All @@ -31,6 +36,7 @@ type Address struct {
DisplayAddress2 string `json:"displayAddress2"`
}

// Sponsor of Installation, see https://developer.airly.org/docs#concepts.installations.sponsors
type Sponsor struct {
Id int `json:"id"`
Name string `json:"name"`
Expand All @@ -40,17 +46,20 @@ type Sponsor struct {
DisplayName string `json:"displayName"`
}

// Measurements data, see https://developer.airly.org/docs#endpoints.measurements
type Measurements struct {
Current Measurement `json:"current"`
History []Measurement `json:"history"`
Forecast []Measurement `json:"forecast"`
}

// Value of measurement
type Value struct {
Name string `json:"name"`
Value float64 `json:"value"`
}

// Index showing aggregated air quality
type Index struct {
Name string `json:"name"`
Value float64 `json:"value"`
Expand All @@ -60,13 +69,15 @@ type Index struct {
Color string `json:"color"`
}

// Standard used for measuring
type Standard struct {
Name string `json:"name"`
Pollutant string `json:"pollutant"`
Limit float64 `json:"limit"`
Percent float64 `json:"percent"`
}

// Measurement represents aggregated values
type Measurement struct {
FromDateTime time.Time `json:"fromDateTime"`
TillDateTime time.Time `json:"tillDateTime"`
Expand All @@ -75,27 +86,33 @@ type Measurement struct {
Standards []Standard `json:"standards"`
}

// IndexType represents index metadata, https://developer.airly.org/docs#endpoints.meta.indexes
type IndexType struct {
Name string `json:"name"`
Levels []Levels `json:"levels"`
Name string `json:"name"`
Levels []Level `json:"levels"`
}
type Levels struct {

// Level metadata
type Level struct {
Values string `json:"values"`
Level string `json:"level"`
Description string `json:"description"`
Color string `json:"color"`
}

// MeasurementType metadata, see https://developer.airly.org/docs#endpoints.meta.measurements
type MeasurementType struct {
Name string `json:"name"`
Label string `json:"label"`
Unit string `json:"unit"`
}

// HttpClient to use for requests
type HttpClient interface {
Do(req *http.Request) (*http.Response, error)
}

// Client for Airly API
type Client struct {
Key string
Language string
Expand Down Expand Up @@ -137,12 +154,15 @@ func (c Client) get(path string, v interface{}) error {
return json.Unmarshal(body, v)
}

// Installation returns installation by id. See https://developer.airly.org/docs#endpoints.installations.getbyid
func (c Client) Installation(id int) (Installation, error) {
var i Installation
err := c.get(fmt.Sprintf("installations/%d", id), &i)
return i, err
}

// NearestInstallations returns installations near specified point, range can be defined with MaxDistance,
// number of results can be defined with MaxResults. See https://developer.airly.org/docs#endpoints.installations.nearest
func (c Client) NearestInstallations(loc Location, options ...NearestInstallationsOption) ([]Installation, error) {
var i []Installation
config := nearestInstallationsConfig{3.0, 1}
Expand All @@ -154,6 +174,8 @@ func (c Client) NearestInstallations(loc Location, options ...NearestInstallatio
return i, err
}

// NearestMeasurements returns measurements for an installation closest to a given location, range can be defined with MaxDistance.
// See https://developer.airly.org/en/docs#endpoints.measurements.nearest
func (c Client) NearestMeasurements(loc Location, options ...NearestInstallationsOption) (Measurements, error) {
var m Measurements
config := nearestInstallationsConfig{3.0, 1}
Expand All @@ -165,26 +187,34 @@ func (c Client) NearestMeasurements(loc Location, options ...NearestInstallation
return m, err
}

// PointMeasurements returns any geographical location.
// Measurement values are interpolated by averaging measurements from nearby sensors (up to 1,5km away from the given point).
// The returned value is a weighted average, with the weight inversely proportional to the distance from the sensor to the given point.
// See https://developer.airly.org/docs#endpoints.measurements.point
func (c Client) PointMeasurements(loc Location) (Measurements, error) {
var m Measurements
err := c.get(fmt.Sprintf("measurements/point?lat=%f&lng=%f", loc.Latitude, loc.Longitude), &m)
return m, err
}

// InstallationMeasurements returns measurements for concrete installation, see https://developer.airly.org/docs#endpoints.measurements.installation
func (c Client) InstallationMeasurements(installationId int) (Measurements, error) {
var m Measurements
err := c.get(fmt.Sprintf("measurements/installation?installationId=%d", installationId), &m)
return m, err
}

// NearestInstallationsOption represents option to narrow search results
type NearestInstallationsOption func(config *nearestInstallationsConfig)

// MaxDistance to given points in km
func MaxDistance(maxDistance float64) NearestInstallationsOption {
return func(c *nearestInstallationsConfig) {
c.maxDistance = maxDistance
}
}

// MaxResults that can be returned by API call
func MaxResults(maxResults int) NearestInstallationsOption {
return func(c *nearestInstallationsConfig) {
c.maxResults = maxResults
Expand All @@ -196,12 +226,16 @@ type nearestInstallationsConfig struct {
maxResults int
}

// IndexTypes returns a list of all the index types supported in the API along with lists of levels defined
// per each index type, see https://developer.airly.org/docs#endpoints.meta.indexes
func (c Client) IndexTypes() ([]IndexType, error) {
var i []IndexType
err := c.get("meta/measurements", &i)
return i, err
}

// MeasurementTypes returns list of all the measurement types supported in the API along with their names and units,
// see https://developer.airly.org/docs#endpoints.meta.measurements
func (c Client) MeasurementTypes() ([]MeasurementType, error) {
var m []MeasurementType
err := c.get("meta/measurements", &m)
Expand Down
4 changes: 2 additions & 2 deletions airly_it_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@ func TestInstallationIT(t *testing.T) {
assert.Equal(t, Installation{
Id: 8077,
Location: Location{50.062006, 19.940984},
Address: Address{"Poland", "Krakow", "Mikołajska", "", "Krakow", "Mikołajska"},
Address: address{"Poland", "Krakow", "Mikołajska", "", "Krakow", "Mikołajska"},
Elevation: 220.38,
Airly: true,
Sponsor: Sponsor{489, "Chatham Financial", "Sponsor sensora Airly", "https://cdn.airly.eu/logo/ChathamFinancial_1570109001008_473803190.jpg", "https://crossweb.pl/job/chatham-financial/ ", "Chatham Financial"},
Sponsor: sponsor{489, "Chatham Financial", "sponsor sensora Airly", "https://cdn.airly.eu/logo/ChathamFinancial_1570109001008_473803190.jpg", "https://crossweb.pl/job/chatham-financial/ ", "Chatham Financial"},
}, installation)
}
48 changes: 24 additions & 24 deletions airly_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ func TestInstallation(t *testing.T) {
Latitude: 50.062006,
Longitude: 19.940984,
},
Address: Address{
Address: address{
Country: "Poland",
City: "Kraków",
Street: "Mikołajska",
Expand All @@ -103,7 +103,7 @@ func TestInstallation(t *testing.T) {
},
Elevation: 220.38,
Airly: true,
Sponsor: Sponsor{
Sponsor: sponsor{
Name: "KrakówOddycha",
Description: "Sensor Airly w ramach akcji",
Logo: "https://cdn.airly.org/logo/KrakówOddycha.jpg",
Expand Down Expand Up @@ -158,7 +158,7 @@ func TestNearestInstallations(t *testing.T) {
Latitude: 50.062006,
Longitude: 19.940984,
},
Address: Address{
Address: address{
Country: "Poland",
City: "Kraków",
Street: "Mikołajska",
Expand All @@ -168,7 +168,7 @@ func TestNearestInstallations(t *testing.T) {
},
Elevation: 220.38,
Airly: true,
Sponsor: Sponsor{
Sponsor: sponsor{
Name: "KrakówOddycha",
Description: "Sensor Airly w ramach akcji",
Logo: "https://cdn.airly.org/logo/KrakówOddycha.jpg",
Expand Down Expand Up @@ -224,7 +224,7 @@ func TestNearestInstallationsOptions(t *testing.T) {
Latitude: 50.062006,
Longitude: 19.940984,
},
Address: Address{
Address: address{
Country: "Poland",
City: "Kraków",
Street: "Mikołajska",
Expand All @@ -234,7 +234,7 @@ func TestNearestInstallationsOptions(t *testing.T) {
},
Elevation: 220.38,
Airly: true,
Sponsor: Sponsor{
Sponsor: sponsor{
Name: "KrakówOddycha",
Description: "Sensor Airly w ramach akcji",
Logo: "https://cdn.airly.org/logo/KrakówOddycha.jpg",
Expand Down Expand Up @@ -290,33 +290,33 @@ func TestInstallationMeasurements(t *testing.T) {
measurements, err := api.InstallationMeasurements(204)
assert.Nil(t, err)
assert.Equal(t, Measurements{
Current: Measurement{
Current: measurement{
FromDateTime: time.Date(2018, 8, 24, 8, 24, 48, 652*1000*1000, time.UTC),
TillDateTime: time.Date(2018, 8, 24, 9, 24, 48, 652*1000*1000, time.UTC),
Values: []Value{{
Values: []value{{
Name: "PM1",
Value: 12.73,
}, {
Name: "PM25",
Value: 18.7,
}},
Indexes: []Index{{
Indexes: []index{{
Name: "AIRLY_CAQI",
Value: 35.53,
Level: "LOW",
Description: "Dobre powietrze.",
Advice: "Możesz bez obaw wyjść na zewnątrz.",
Color: "#D1CF1E",
}},
Standards: []Standard{{
Standards: []standard{{
Name: "WHO",
Pollutant: "PM25",
Limit: 25,
Percent: 74.81,
}},
},
History: []Measurement{},
Forecast: []Measurement{},
History: []measurement{},
Forecast: []measurement{},
}, measurements)
}

Expand Down Expand Up @@ -367,33 +367,33 @@ func TestNearestMeasurements(t *testing.T) {
measurements, err := api.NearestMeasurements(Location{50.062006, 19.940984}, MaxDistance(5))
assert.Nil(t, err)
assert.Equal(t, Measurements{
Current: Measurement{
Current: measurement{
FromDateTime: time.Date(2018, 8, 24, 8, 24, 48, 652*1000*1000, time.UTC),
TillDateTime: time.Date(2018, 8, 24, 9, 24, 48, 652*1000*1000, time.UTC),
Values: []Value{{
Values: []value{{
Name: "PM1",
Value: 12.73,
}, {
Name: "PM25",
Value: 18.7,
}},
Indexes: []Index{{
Indexes: []index{{
Name: "AIRLY_CAQI",
Value: 35.53,
Level: "LOW",
Description: "Dobre powietrze.",
Advice: "Możesz bez obaw wyjść na zewnątrz.",
Color: "#D1CF1E",
}},
Standards: []Standard{{
Standards: []standard{{
Name: "WHO",
Pollutant: "PM25",
Limit: 25,
Percent: 74.81,
}},
},
History: []Measurement{},
Forecast: []Measurement{},
History: []measurement{},
Forecast: []measurement{},
}, measurements)
}

Expand Down Expand Up @@ -444,32 +444,32 @@ func TestPointMeasurements(t *testing.T) {
measurements, err := api.PointMeasurements(Location{50.062006, 19.940984})
assert.Nil(t, err)
assert.Equal(t, Measurements{
Current: Measurement{
Current: measurement{
FromDateTime: time.Date(2018, 8, 24, 8, 24, 48, 652*1000*1000, time.UTC),
TillDateTime: time.Date(2018, 8, 24, 9, 24, 48, 652*1000*1000, time.UTC),
Values: []Value{{
Values: []value{{
Name: "PM1",
Value: 12.73,
}, {
Name: "PM25",
Value: 18.7,
}},
Indexes: []Index{{
Indexes: []index{{
Name: "AIRLY_CAQI",
Value: 35.53,
Level: "LOW",
Description: "Dobre powietrze.",
Advice: "Możesz bez obaw wyjść na zewnątrz.",
Color: "#D1CF1E",
}},
Standards: []Standard{{
Standards: []standard{{
Name: "WHO",
Pollutant: "PM25",
Limit: 25,
Percent: 74.81,
}},
},
History: []Measurement{},
Forecast: []Measurement{},
History: []measurement{},
Forecast: []measurement{},
}, measurements)
}

0 comments on commit 5869dba

Please sign in to comment.