Class: PurpleAirApi::V1::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/purple_air_api/V1/client.rb

Overview

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.

Constant Summary collapse

API_URL =

The base URL for the PurpleAir API

'https://api.purpleair.com/v1/'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(read_token: , write_token: ) ⇒ Client

Creates a read and write client to interface with the Purple Air API.

Examples:

generate a client instance

PurpleAirApi::V1::Client.new(read_token: "1234", write_token: "1234")

Parameters:

  • read_token (String) (defaults to: ) —

    The read client you received from PurpleAir

  • write_token (String) (defaults to: ) —

    The write client you received from PurpleAir



21
22
23
24
 
# File 'lib/purple_air_api/V1/client.rb', line 21

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

Instance Attribute Details

#read_client ⇒ Object (readonly)

Returns the value of attribute read_client.



9
10
11
 
# File 'lib/purple_air_api/V1/client.rb', line 9

def read_client
  @read_client
end

#write_client ⇒ Object (readonly)

Returns the value of attribute write_client.



9
10
11
 
# File 'lib/purple_air_api/V1/client.rb', line 9

def write_client
  @write_client
end

Instance Method Details

#request_sensor(sensor_index, read_key: nil) ⇒ PurpleAirApi::GetSensor

Makes a request to the individual sensor SHOW endpoint and returns an instance of the V1::GetSensors class.

Examples:

request sensor data for a few sensors

client = PurpleAirApi::V1::Client.new(read_token: "1234")
response = client.request_sensor(sensor_index: 20)
response_hash = response.parsed_response

Parameters:

  • sensor_index (Integer) —

    The sensor_index for the sensor you want to request data from.

  • read_key (String) (defaults to: nil) —

    The read_key for the sensor you want to request data from if it is a private sensor.

Returns:

  • (PurpleAirApi::GetSensor) 


59
60
61
 
# File 'lib/purple_air_api/V1/client.rb', line 59

def request_sensor(sensor_index:, read_key: nil)
  GetSensor.call(client: read_client, sensor_index: sensor_index, read_key: read_key)
end

#request_sensors(options) ⇒ PurpleAirApi::GetSensors

Makes a request to the sensors INDEX endpoint and returns an instance of the V1::GetSensors class.

Examples:

{ bounding_box: { nw: [37.7790262, -122.4199061], se: [37.6535403, -122.4168664]}}

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

Parameters:

  • options (Hash) —

    A hash of options { :option_name=>value }

Options Hash (options):

  • :show_only (Array<Integer>) —

    An array of indexes for the sensors you want to request.

  • :location_type (Array<String>) —

    An array of strings specifying sensor location.

  • :fields (Array<String>) —

    An array of fields you want returned.

  • :modified_since (Integer) —

    Only return sensors updated since this timestamp.

  • :max_age (Integer) —

    Only return sensors updated in the last n seconds.

  • :bounding_box (Hash<array>) —

    A hash with a :nw and :se array { nw: [lat,long], se: [lat,long] }.

  • :read_keys (Array<String>) —

    An array of read-keys which are required for private devices.

Returns:

  • (PurpleAirApi::GetSensors) 


45
46
47
 
# File 'lib/purple_air_api/V1/client.rb', line 45

def request_sensors(options = {})
  GetSensors.call(client: read_client, **options)
end