purple_air_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 01b62b7c6de5e4d8448ae7a1285db326b712464b3e9b18ed2d6ae828f6d1146c
+  data.tar.gz: 48f3649122ce37ec5413588bcdf8d12105506303f749e10989d89cb7cc2b69d0
+SHA512:
+  metadata.gz: d5af049019b69727c5a0421abe9dc2dcfbec967532728caeb4fdc5cf29401d80b99c4381f7612bbac56f3beab33bf0fb1d108fa6539b2b81b39e55b0ae02f9d1
+  data.tar.gz: 845f907c45befc6d3abed0fae9e586ce0a05a818d0e7376cf4213a1152b15b6d4026a380a6da95825435a9e28dfd2134b616b4e4b831430959ac075a1a586276

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.idea/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,15 @@
+AllCops:
+  TargetRubyVersion: 2.7.0
+  NewCops: enable
+
+Metrics/BlockLength:
+  Exclude:
+    - '**/*_spec.rb'
+
+Metrics:
+  Exclude:
+    - '**/raise_http_exception.rb'
+
+Metrics/ClassLength:
+  Exclude:
+    - '**/get_sensors.rb'

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at dylankiselbach@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/Gemfile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in purple_air_api.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+
+group :test, :development do
+  gem 'faker'
+  gem 'rspec', '~> 3.0'
+  gem 'rubocop', '~> 1.9'
+  gem 'webmock'
+  gem 'yard'
+  # for yard
+  gem 'webrick'
+end

data/Gemfile.lock

@@ -0,0 +1,86 @@
+PATH
+  remote: .
+  specs:
+    purple_air_api (0.1.0)
+      faraday (~> 1.3)
+      fast_jsonparser (~> 0.5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    ast (2.4.2)
+    concurrent-ruby (1.1.8)
+    crack (0.4.5)
+      rexml
+    diff-lcs (1.4.4)
+    faker (2.15.1)
+      i18n (>= 1.6, < 2)
+    faraday (1.3.0)
+      faraday-net_http (~> 1.0)
+      multipart-post (>= 1.2, < 3)
+      ruby2_keywords
+    faraday-net_http (1.0.1)
+    fast_jsonparser (0.5.0)
+    hashdiff (1.0.1)
+    i18n (1.8.7)
+      concurrent-ruby (~> 1.0)
+    multipart-post (2.1.1)
+    parallel (1.20.1)
+    parser (3.0.0.0)
+      ast (~> 2.4.1)
+    public_suffix (4.0.6)
+    rainbow (3.0.0)
+    rake (13.0.3)
+    regexp_parser (2.0.3)
+    rexml (3.2.4)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.1)
+    rubocop (1.9.0)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.2.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.4.1)
+      parser (>= 2.7.1.5)
+    ruby-progressbar (1.11.0)
+    ruby2_keywords (0.0.4)
+    unicode-display_width (2.0.0)
+    webmock (3.11.1)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    webrick (1.7.0)
+    yard (0.9.26)
+
+PLATFORMS
+  x86_64-darwin-19
+
+DEPENDENCIES
+  faker
+  purple_air_api!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.9)
+  webmock
+  webrick
+  yard
+
+BUNDLED WITH
+   2.2.5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 dkiselbach
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,51 @@
+# PurpleAirApi
+
+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
+
+Or install it yourself as:
+
+    $ gem install purple_air_api
+
+## Usage
+
+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:
+
+`client.get_sensors(options)` 
+
+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.
+
+## 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).
+
+## 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).
+
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](code_of_conduct.md)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'purple_air_api'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/purple_air_api.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'fast_jsonparser'
+require_relative 'purple_air_api/version'
+require_relative 'purple_air_api/V1/client'
+require_relative 'purple_air_api/V1/raise_http_exception'
+require_relative 'purple_air_api/V1/errors'
+require_relative 'purple_air_api/v1/sensors/get_sensors'
+require_relative 'purple_air_api/v1/sensors/get_sensor'
+require_relative 'purple_air_api/v1/sensors/errors'
+
+# The PurpleAirApi is a gem intended to be used to interact with the PurpleAir API easily.
+module PurpleAirApi
+  # Alias for PurpleAirApi::V1::Client.new
+  #
+  # @return [PurpleAirApi::V1::Client]
+  # @example requesting data for a few sensors
+  #   options = { fields: ['icon', 'name'], location_type: ['outside'], show_only: [26, 41], max_age: 3600}
+  #   PurpleAirApi.client(read_token: "1234", write_token: "1234").request_sensors(options)
+
+  def self.client(read_token:, write_token: nil)
+    PurpleAirApi::V1::Client.new(read_token: read_token, write_token: write_token)
+  end
+
+  # Delegate to PurpleAirApi::V1::Client
+  def self.method_missing(method, *args, &block)
+    return super unless client.respond_to?(method)
+
+    client.send(method, *args, &block)
+  end
+
+  # Delegate to PurpleAirApi::V1::Client
+  def self.respond_to?(method, include_all: false)
+    client.respond_to?(method, include_all) || super
+  end
+
+  # Delegate to PurpleAirApi::V1::Client
+  def self.respond_to_missing?(method_name, include_private: false)
+    client.respond_to_missing?(method_name, include_private) || super
+  end
+end

data/lib/purple_air_api/V1/client.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PurpleAirApi
+  # The V1 API Module for namespacing the PurpleAir V1 API
+  module V1
+    # Client class for interfacing with the V1 PurpleAir API. Refer to the instance methods to learn more about what
+    # methods and API options are available.
+    class Client
+      attr_reader :read_client, :write_client
+
+      # The base URL for the PurpleAir API
+      API_URL = 'https://api.purpleair.com/v1/'
+
+      # Creates a read and write client to interface with the Purple Air API.
+      # @!method initialize(read_token:, write_token:)
+      # @param read_token [String] The read client you received from PurpleAir
+      # @param write_token [String] The write client you received from PurpleAir
+      # @example generate a client instance
+      #   PurpleAirApi::V1::Client.new(read_token: "1234", write_token: "1234")
+
+      def initialize(read_token:, write_token: nil)
+        @read_client = create_http_client(read_token)
+        @write_client = create_http_client(write_token) unless write_token.nil?
+      end
+
+      # Makes a request to the sensors endpoint and returns an instance of the V1::GetSensors class.
+      # @!method request_sensors(options)
+      # @param [Hash] options A hash of options { :option_name=>value }
+      # @option options [Array<Integer>] :show_only An array of indexes for the sensors you want to request.
+      # @option options [Array<String>] :location_type An array of strings specifying sensor location.
+      # @option options [Array<String>] :fields An array of fields you want returned.
+      # @option options [Integer] :modified_since Only return sensors updated since this timestamp.
+      # @option options [Integer] :max_age Only return sensors updated in the last n seconds.
+      # @option options [Hash<array>] :bounding_box A hash with a :nw and :se array { nw: [lat,long], se: [lat,long] }.
+      # @example
+      #   { bounding_box: { nw: [37.7790262, -122.4199061], se: [37.6535403, -122.4168664]}}
+      # @option options [Array<String>] :read_keys An array of read-keys which are required for private devices.
+      # @return [PurpleAirApi::GetSensors]
+      # @example request sensor data for a few sensors
+      #   options = { fields: ['icon', 'name'], location_type: ['outside'], show_only: [20, 47], max_age: 3600}
+      #   client = PurpleAirApi::V1::Client.new(read_token: "1234", write_token: "1234")
+      #   response = client.request_sensors(options)
+      #   response_hash = response.parsed_response
+
+      def request_sensors(options = {})
+        GetSensors.call(client: read_client, **options)
+      end
+
+      def request_sensor(sensor_index:, read_key: nil)
+        GetSensor.call(client: read_client, sensor_index: sensor_index, read_key: read_key)
+      end
+
+      private
+
+      def create_http_client(token)
+        Faraday.new(url: API_URL) do |faraday|
+          faraday.headers['X-API-KEY'] = token
+          faraday.use RaiseHttpException
+        end
+      end
+    end
+  end
+end

data/lib/purple_air_api/V1/errors.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PurpleAirApi
+  module V1
+    # A custom error class for rescuing from all PurpleAir API errors
+    class BaseError < StandardError
+      attr_reader :response_object, :error_type
+
+      # Initialize the error object with error_type and the Faraday response object. PurpleAir returns a human friendly
+      # error message and type which is added here. You can also reference the response to view the raw response
+      # from PurpleAir.
+      # @!method initialize(message, error_type, response_object)
+      # @param message [String] the message you want displayed when the error is raised
+      # @param error_type [String] the error type that PurpleAir includes in the JSON response
+      # @param response_object [Faraday::Env] the Faraday response object
+      def initialize(message, error_type, response_object)
+        super(message)
+        @error_type = error_type
+        @response_object = response_object
+      end
+    end
+
+    # Raised when the PurpleAir API returns the HTTP status code 403
+    class ApiKeyError < BaseError
+    end
+
+    # Raised when the PurpleAir API returns the HTTP status code 415
+    class MissingJsonPayloadError < BaseError
+    end
+
+    # Raised when the PurpleAir API returns the HTTP status code 400. Use the message and error_type on the Error
+    # object to determine additional information regarding the error.
+    class ApiError < BaseError
+    end
+
+    # Raised when the PurpleAir API returns the HTTP status code 404
+    class NotFoundError < BaseError
+    end
+
+    # Raised when the PurpleAir API returns the HTTP status code 500
+    class ServerError < BaseError
+    end
+  end
+end

data/lib/purple_air_api/V1/raise_http_exception.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PurpleAirApi
+  module V1
+    # Handles any HTTP exceptions for 400 and 500 error codes
+    class RaiseHttpException < Faraday::Middleware
+      # A switch statement which determines which error to raise depending on error code
+      def call(env)
+        @app.call(env).on_complete do |response|
+          self.response = response
+          case response[:status].to_i
+          when 400
+            raise ApiError.new(error_message, parsed_response[:error], response)
+          when 403
+            raise ApiKeyError.new(error_message, parsed_response[:error], response)
+          when 404
+            raise NotFoundError.new(error_message, parsed_response[:error], response)
+          when 415
+            raise MissingJsonPayloadError.new(error_message, 'MissingJsonPayloadError', response)
+          when 500
+            raise ServerError.new(error_message, 'ServerError', response)
+          end
+        end
+      end
+
+      # Faraday syntax for implementing middleware
+      def initialize(app)
+        super app
+        @parser = nil
+      end
+
+      private
+
+      attr_accessor :response
+
+      def error_message
+        parsed_response[:description]
+      end
+
+      def parsed_response
+        @parsed_response ||= FastJsonparser.parse(response[:body])
+      rescue FastJsonparser::ParseError
+        unknown_error_message
+      end
+
+      def unknown_error_message
+        { description: 'Something went wrong in the request.' }
+      end
+    end
+  end
+end

data/lib/purple_air_api/V1/sensors/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PurpleAirApi
+  module V1
+    # Raised when the options given are invalid
+    class OptionsError < StandardError
+    end
+  end
+end

data/lib/purple_air_api/V1/sensors/get_sensor.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module PurpleAirApi
+  module V1
+    # Class for requesting sensor data for a single sensor. This will return different response formats from the API.
+    class GetSensor
+      attr_accessor :http_response, :request_options, :index
+      attr_reader :http_client
+
+      # The endpoint URL
+      URL = 'https://api.purpleair.com/v1/sensors/'
+
+      # Calls initializes the class and requests the data from PurpleAir.
+      # @!method call(...)
+
+      def self.call(...)
+        new(...).request
+      end
+
+      # Creates a HTTP friendly options hash depending on your inputs
+      # @!method initialize(client:, **options)
+      # @param client [Faraday::Connection] Your HTTP client initialized in Client
+      # @param options [Hash] Your HTTP options for the request.
+
+      def initialize(client:, sensor_index:, read_key: nil)
+        @http_client = client
+        @request_options = {}
+        create_options_hash(sensor_index, read_key)
+      end
+
+      # Makes a get request to the PurpleAir Get Sensors Data endpoint https://api.purpleair.com/v1/sensors.
+      # @!method request
+      # @return [PurpleAirApi::V1::GetSensors]
+
+      def request
+        self.http_response = http_client.get(url, request_options)
+        self
+      end
+
+      # Delegate to PurpleAirApi::V1::GetSensor.json_response
+
+      def parsed_response
+        json_response
+      end
+
+      # Takes the raw response from PurpleAir and parses the JSON.
+      # @!method json_response
+      # @return [Json]
+      # @example json_response example
+      #   response.json_response
+      #   {
+      #     "api_version": "V1.0.6-0.0.9",
+      #     "time_stamp": 1615053213,
+      #     "sensor": {
+      #         "sensor_index": 20,
+      #         "name": "Oakdale",
+      #         "model": "UNKNOWN",
+      #         "location_type": 0,
+      #         "latitude": 40.6031,
+      #         "longitude": -111.8361,
+      #         "altitude": 4636,
+      #         "last_seen": 1615053181,
+      #         "last_modified": 1575003022,
+      #         "private": 0,
+      #         "channel_state": 1,
+      #         "channel_flags_manual": 2,
+      #         "pm1.0_a": 0.0,
+      #         "pm2.5_a": 0.0,
+      #         "pm10.0_a": 0.0,
+      #         "0.3_um_count_a": 0.0,
+      #         "0.5_um_count_a": 0.0,
+      #         "1.0_um_count_a": 0.0,
+      #         "2.5_um_count_a": 0.0,
+      #         "5.0_um_count_a": 0.0,
+      #         "10.0_um_count_a": 0.0,
+      #         "stats_a": {
+      #             "pm2.5": 0.0,
+      #             "pm2.5_10minute": 0.0,
+      #             "pm2.5_30minute": 0.0,
+      #             "pm2.5_60minute": 0.0,
+      #             "pm2.5_6hour": 0.0,
+      #             "pm2.5_24hour": 0.0,
+      #             "pm2.5_1week": 0.0,
+      #             "time_stamp": 1615053181
+      #         },
+      #         "analog_input": 0.01,
+      #         "primary_id_a": 66984,
+      #         "primary_key_a": "TLKXL2SOJ9M0KGFK",
+      #         "secondary_id_a": 71207,
+      #         "secondary_key_a": "224YRSOGD8TNE5FQ",
+      #         "primary_id_b": 209227,
+      #         "primary_key_b": "3YF75LZ4DL7HDH9O",
+      #         "secondary_id_b": 209228,
+      #         "secondary_key_b": "Y02CNZZDMR15KCMX",
+      #         "hardware": "1.0+PMSX003-O",
+      #         "led_brightness": 0.0,
+      #         "firmware_version": "6.01",
+      #         "rssi": -78.0,
+      #         "icon": 0,
+      #         "channel_flags_auto": 0
+      #     }
+      #   }
+
+      def json_response
+        @json_response ||= FastJsonparser.parse(http_response.body)
+      end
+
+      private
+
+      def create_options_hash(sensor_index, read_key)
+        sensor_index(sensor_index)
+        request_options.merge!(
+          read_key(read_key)
+        )
+      end
+
+      def sensor_index(index)
+        raise OptionsError, 'sensor_index must be an Integer' unless index.instance_of?(Integer)
+
+        self.index = index.to_s
+      end
+
+      def read_key(key)
+        return {} if key.nil?
+
+        raise OptionsError, 'read_key must be a String' unless key.instance_of?(String)
+
+        { read_key: key }
+      end
+
+      def url
+        URL + index
+      end
+    end
+  end
+end

data/lib/purple_air_api/V1/sensors/get_sensors.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module PurpleAirApi
+  module V1
+    # Class for requesting sensor data. This will return different response formats from the API.
+    class GetSensors
+      attr_accessor :request_options, :http_response
+      attr_reader :http_client
+      attr_writer :parsed_response
+
+      # The default value for fields that will be returned by PurpleAir
+      DEFAULT_FIELDS = %w[icon name latitude longitude altitude pm2.5].freeze
+
+      # The default location type for the sensor
+      DEFAULT_LOCATION_TYPE = %w[outside inside].freeze
+
+      # The endpoint URL
+      URL = 'https://api.purpleair.com/v1/sensors'
+
+      # Calls initializes the class and requests the data from PurpleAir.
+      # @!method call(...)
+
+      def self.call(...)
+        new(...).request
+      end
+
+      # Creates a HTTP friendly options hash depending on your inputs
+      # @!method initialize(client:, **options)
+      # @param client [Faraday::Connection] Your HTTP client initialized in Client
+      # @param options [Hash] Your HTTP options for the request.
+
+      def initialize(client:, **options)
+        @http_client = client
+        @request_options = {}
+        create_options_hash(options)
+      end
+
+      # Makes a get request to the PurpleAir Get Sensors Data endpoint https://api.purpleair.com/v1/sensors.
+      # @!method request
+      # @return [PurpleAirApi::V1::GetSensors]
+
+      def request
+        self.http_response = http_client.get(URL, request_options)
+        self
+      end
+
+      # Takes the raw response from PurpleAir and generates a hash indexed by sensor index. You can use this response
+      # like a normal hash object. This GetSensorsClass.parsed_response[:47] would return a hash of data for sensor 47
+      # with each hash key labelling the associated data.
+      # @!method parsed_response
+      # @return [Hash]
+      # @example parsed_response example
+      #   response.parsed_response
+      #   {
+      #     :fields=>["sensor_index", "name", "icon", "latitude", "longitude", "altitude", "pm2.5"],
+      #     :api_version=>"V1.0.6-0.0.9",
+      #     :time_stamp=>1614787814,
+      #     :data_time_stamp=>nil,
+      #     :max_age=>3600,
+      #     :data=>
+      #     {
+      #       20=>{"sensor_index"=>20, "name"=>"Oakdale", "icon"=>0, "latitude"=>40.6031,
+      #            "longitude"=>-111.8361, "altitude"=>4636, "pm2.5"=>0.0},
+      #       47=>{"sensor_index"=>47, "name"=>"OZONE TEST", "icon"=>0, "latitude"=>40.4762,
+      #            "longitude"=>-111.8826, "altitude"=>nil, "pm2.5"=>nil}
+      #     }
+      #   }
+
+      def parsed_response
+        @parsed_response ||= parse_response
+      end
+
+      # Takes the raw response from PurpleAir and parses the JSON.
+      # @!method json_response
+      # @return [Json]
+      # @example json_response example
+      #   response.json_response
+      #   {
+      #     :api_version=>"V1.0.6-0.0.9",
+      #     :time_stamp=>1614787814,
+      #     :data_time_stamp=>1614787807,
+      #     :location_type=>0,
+      #     :max_age=>3600,
+      #     :fields=>["sensor_index", "name", "icon", "latitude", "longitude", "altitude", "pm2.5"],
+      #     :data=>[
+      #               [20, "Oakdale", 0, 40.6031, -111.8361, 4636, 0.0],
+      #               [47, "OZONE TEST", 0, 40.4762, -111.8826, nil, nil]
+      #            ]
+      #   }
+
+      def json_response
+        @json_response ||= FastJsonparser.parse(http_response.body)
+      end
+
+      private
+
+      attr_accessor :data, :data_fields
+
+      def create_options_hash(options)
+        request_options.merge!(
+          fields(options[:fields] || DEFAULT_FIELDS),
+          location_type(options[:location_type]),
+          show_only(options[:show_only]),
+          modified_since(options[:modified_since]),
+          max_age(options[:max_age]),
+          bounding_box(options[:bounding_box]),
+          read_keys(options[:read_keys])
+        )
+      end
+
+      def fields(fields_array)
+        unless fields_array.instance_of?(Array) && fields_array.first.instance_of?(String)
+          raise OptionsError, 'fields must be an array of strings specifying the fields you want returned'
+        end
+
+        { fields: fields_array.join(',') }
+      end
+
+      def show_only(sensor_indices)
+        return {} if sensor_indices.nil?
+
+        unless sensor_indices.instance_of?(Array) && sensor_indices.first.instance_of?(Integer)
+          raise OptionsError,
+                'show_only must be an array of integers specifying the sensor indices you data returned for'
+        end
+
+        { show_only: sensor_indices.join(',') }
+      end
+
+      def location_type(location_type)
+        return {} if location_type.nil?
+
+        unless location_type.instance_of?(Array) && location_type.first.instance_of?(String)
+          raise OptionsError,
+                "location_type must be an array of strings specifying either ['inside'], ['outside'], or both"
+        end
+
+        location_type.map!(&:downcase)
+
+        location_type_parameter(location_type)
+      end
+
+      def location_type_parameter(location_type)
+        return {} if location_type.include?('outside') && location_type.include?('inside')
+        return { location_type: 1 } if location_type.include?('inside')
+        return { location_type: 0 } if location_type.include?('outside')
+      end
+
+      def modified_since(timestamp)
+        return {} if timestamp.nil?
+        raise OptionsError, 'timestamp must be a valid Integer' unless timestamp.instance_of?(Integer)
+
+        { modified_since: timestamp }
+      end
+
+      def max_age(seconds)
+        return {} if seconds.nil?
+        raise OptionsError, 'seconds must be a valid Integer' unless seconds.instance_of?(Integer)
+
+        { max_age: seconds.to_i }
+      end
+
+      def bounding_box(coordinates)
+        return {} if coordinates.nil?
+
+        unless coordinates.instance_of?(Hash) && coordinates[:nw].length == 2 && coordinates[:se].length == 2
+          raise OptionsError, 'coordinates must be a Hash with a :nw and :se array containing [lat, long]'
+        end
+
+        {
+          nwlat: coordinates[:nw][0], nwlng: coordinates[:nw][1], selat: coordinates[:se][0], selng: coordinates[:se][1]
+        }
+      end
+
+      def read_keys(keys)
+        return {} if keys.nil?
+
+        unless keys.instance_of?(Array) && keys.first.instance_of?(String)
+          raise OptionsError, 'read_keys must be an Array of Strings'
+        end
+
+        { read_keys: keys.join(',') }
+      end
+
+      def parse_response
+        response = json_response
+
+        generate_response_hash(response)
+
+        self.data = response[:data]
+        self.data_fields = response[:fields]
+
+        merge_data_hash
+      end
+
+      def generate_response_hash(response_hash)
+        fields, api_version,
+          time_stamp, date_time_stamp, max_age = response_hash.values_at(:fields, :api_version, :time_stamp,
+                                                                         :date_time_stamp, :max_age)
+        self.parsed_response = {
+          fields: fields,
+          api_version: api_version,
+          time_stamp: time_stamp,
+          data_time_stamp: date_time_stamp,
+          max_age: max_age
+        }
+      end
+
+      def merge_data_hash
+        parsed_response.merge!({ data: generate_data_hash })
+      end
+
+      def generate_data_hash
+        data_hash = {}
+        data.each do |sensor|
+          sensor_index = sensor.first
+          data_hash.merge!(sensor_index => {})
+          sensor.each_with_index do |data_point, index|
+            data_hash[sensor_index].merge!(data_fields[index] => data_point)
+          end
+        end
+        data_hash
+      end
+    end
+  end
+end

data/lib/purple_air_api/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module PurpleAirApi
+  # The gem version
+  VERSION = '0.1.0'
+end

data/purple_air_api.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'lib/purple_air_api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'purple_air_api'
+  spec.version       = PurpleAirApi::VERSION
+  spec.authors       = ['Dylan Kiselbach']
+  spec.email         = ['dylankiselbach@gmail.com']
+
+  spec.summary       = 'This is an library to assist in interacting with the PurpleAir API.'
+  spec.description   = 'To use this gem you will need your own read and write key from PurpleAir which can be retrieved
+                        by contacting their support team https://www2.purpleair.com/pages/contact-us.'
+  spec.homepage      = 'https://github.com/dkiselbach/purple_air_api'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/dkiselbach/purple_air_api.'
+  spec.metadata['changelog_uri'] = 'https://github.com/dkiselbach/purple_air_api.'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency 'faraday', '~> 1.3'
+  spec.add_dependency 'fast_jsonparser', '~> 0.5'
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: purple_air_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dylan Kiselbach
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-03-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: fast_jsonparser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+description: |-
+  To use this gem you will need your own read and write key from PurpleAir which can be retrieved
+                          by contacting their support team https://www2.purpleair.com/pages/contact-us.
+email:
+- dylankiselbach@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/purple_air_api.rb
+- lib/purple_air_api/V1/client.rb
+- lib/purple_air_api/V1/errors.rb
+- lib/purple_air_api/V1/raise_http_exception.rb
+- lib/purple_air_api/V1/sensors/errors.rb
+- lib/purple_air_api/V1/sensors/get_sensor.rb
+- lib/purple_air_api/V1/sensors/get_sensors.rb
+- lib/purple_air_api/version.rb
+- purple_air_api.gemspec
+homepage: https://github.com/dkiselbach/purple_air_api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dkiselbach/purple_air_api
+  source_code_uri: https://github.com/dkiselbach/purple_air_api.
+  changelog_uri: https://github.com/dkiselbach/purple_air_api.
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: This is an library to assist in interacting with the PurpleAir API.
+test_files: []