README.md in purple_air_api-0.1.0 vs README.md in purple_air_api-0.1.1
- old
+ new
@@ -1,51 +1,183 @@
# PurpleAirApi
+This is a Ruby wrapper for the PurpleAir API.
-This is a client for interacting with the PurpleAir API. This was written using the V1 of the API. In order to use this gem, you must have been granted read and write tokens from PurpleAir.
-
## Installation
-
Add this line to your application's Gemfile:
```ruby
gem 'purple_air_api'
```
And then execute:
- $ bundle install
+`bundle install`
Or install it yourself as:
- $ gem install purple_air_api
+`gem install purple_air_api`
## Usage
+To use this gem, instantiate an instance of a PurpleAirApi client. The write token is
+optional and currently no write actions are implemented in this gem.
-To use this gem, instantiate an instance of a PurpleAirApi client by making the following request:
-
`client = PurpleAirApi.client(read_token: your_read_token, write_token: your_write_token)`
-You can then use this client to interact with the various API methods under the client like:
+You can then use this client to interact with the various API methods under the client:
-`client.get_sensors(options)`
+### Requesting multiple sensors
+```ruby
+# Optional parameters are added using a hash. For a full list of options refer to the documentation.
-Options would be and of the parameters you would like to pass onto the PurpleAir API. The gem will parse the parameters into the format required by the API.
+nw_lat_long = [37.804930, -122.448382]
+se_lat_long = [37.794832, -122.393589]
+fields = %w[icon name latitude longitude altitude pm2.5 pm2.5_10minute pm2.5_30minute pm2.5_60minute]
+location_type = %w[outside]
+show_only = [20, 40, 55, 120]
+options = {
+ fields: fields,
+ location_type: location_type,
+ bounding_box: { nw: nw_lat_long, se: se_lat_long },
+ show_only: show_only
+}
+
+response = client.request_sensors(options)
+
+response.parsed_response[:data][40] # access the individual sensor data using the parsed_response hash
+```
+
+### Requesting a single sensor index
+```ruby
+response = client.request_sensor(sensor_index: 1)
+
+current_air_quality = response.json_response[:sensor][:"pm2.5_a"]
+```
+
+### A sample service object for a lat-long bounding box
+```ruby
+# frozen_string_literal: true
+
+require 'purple_air_api'
+require 'dotenv/load'
+
+module AirQuality
+ # Class for making requests for local sensor data with a lat-long bounding box
+ class GetSensors
+ NW_LAT_LONG = [37.804930, -122.448382].freeze
+ SE_LAT_LONG = [37.794832, -122.393589].freeze
+ DEFAULT_FIELDS = %w[icon name latitude longitude altitude pm2.5 pm2.5_10minute pm2.5_30minute pm2.5_60minute].freeze
+ DEFAULT_LOCATION_TYPE = %w[outside].freeze
+
+ def self.call
+ new.request
+ end
+
+ def request
+ PurpleAirApi.client(read_token: read_token).request_sensors(fields)
+ end
+
+ def read_token
+ ENV['READ_TOKEN']
+ end
+
+ def fields
+ {
+ fields: DEFAULT_FIELDS,
+ location_type: DEFAULT_LOCATION_TYPE,
+ bounding_box: { nw: NW_LAT_LONG, se: SE_LAT_LONG }
+ }
+ end
+ end
+end
+````
+
+### A sample service object for a single sensor
+```ruby
+# frozen_string_literal: true
+
+require 'purple_air_api'
+require 'dotenv/load'
+
+module AirQuality
+ # Class for making requests for an individual sensor
+ class GetSensor
+ SENSOR_INDEX = 54_849
+
+ def self.call
+ new.request
+ end
+
+ def request
+ PurpleAirApi.client(read_token: read_token).request_sensor(sensor_index: SENSOR_INDEX)
+ end
+
+ def read_token
+ ENV['READ_TOKEN']
+ end
+ end
+end
+```
+
+### In a Sinatra app
+
+```ruby
+# frozen_string_literal: true
+
+require 'sinatra'
+require "sinatra/json"
+require 'dotenv/load'
+require 'purple_air_api'
+
+module HomeHub
+ # App server class for running the HomeHub app
+ class App < Sinatra::Base
+
+ get '/sensors/:id' do
+ json purple_air_client.request_sensor(sensor_index: params[:id].to_i).json_response
+ end
+
+ get '/sensors' do
+ json purple_air_client.request_sensors.json_response
+ end
+
+ def purple_air_client
+ @purple_air_client ||= PurpleAirApi.client(read_token: read_token)
+ end
+
+ def read_token
+ @read_token ||= ENV['READ_TOKEN']
+ end
+ end
+end
+```
+
+## Documentation
+
+Documentation for this gem can be found [here.](https://dkiselbach.github.io/purple_air_api/)
+
+## PurpleAir Documentation and Read and Write Tokens
+
+This wrapper was written using the [PurpleAir API Documentation](https://api.purpleair.com/). You will require a read
+and write token in order to use the PurpleAir API which can be received by [reaching out to PurpleAir](https://www2.purpleair.com/pages/contact-us).
+
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Make sure you are updating the Yard docs prior to pushing to master by running `rake yard`.
+
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/dkiselbach/purple_air_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/dkiselbach/purple_air_api/CODE_OF_CONDUCT.md).
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## Code of Conduct
-Everyone interacting in the PurpleAirApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/dkiselbach/purple_air_api/CODE_OF_CONDUCT.md).
+Everyone interacting in the PurpleAirApi project's codebase, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/dkiselbach/purple_air_api/blob/master/CODE_OF_CONDUCT.md).
[](code_of_conduct.md)