AleAir — Air Quality for Major Cities

A small Ruby gem that wraps the World Air Quality Index (WAQI) public API and returns parsed, ready-to-use air-quality data for a given city. No external dependencies — just Ruby standard library.

Add to your Gemfile:

gem 'ale_air'

Then:

bundle install

Or install directly:

gem install ale_air

You need a free WAQI API token. Request one at https://aqicn.org/data-platform/token/.

require 'ale_air'

client = AleAir::FetchJSON.new('YOUR_TOKEN')

if client.air_quality('Helsinki')
  puts client.descriptive_text
  # => "Air quality: 42 AQI Good @ Kallio 12:00 +02:00"
else
  warn "Lookup failed: #{client.message}"
end

After a call to #air_quality, the client exposes:

AleAir::FetchJSON.new(
  'YOUR_TOKEN',
  base_url: 'https://api.waqi.info', # override for testing
  open_timeout: 5,                   # seconds
  read_timeout: 10                   # seconds
)

#air_quality always returns true or false. On failure, status is set to "error" and message contains the reason:

client = AleAir::FetchJSON.new('bad-token')
client.air_quality('Helsinki') # => false
client.status                  # => "error"
client.message                 # => "Invalid key"

Error classes are also defined under AleAir:: for callers that prefer to raise: AleAir::Error, AleAir::MissingTokenError, AleAir::InvalidTokenError, AleAir::ApiError, AleAir::NetworkError.

bundle install
bundle exec rspec       # run the test suite
bundle exec rubocop     # run the linter
bundle exec rake        # run both (default task)

Tests use WebMock to stub the WAQI API — no real network access is required.

Bug reports and pull requests are welcome on GitHub at https://github.com/FistOfTheNorthStar/ale_air.

1. Fork the repo
2. Create a feature branch
3. Add tests for your change
4. Ensure bundle exec rake is green
5. Open a pull request

Released under the MIT License.