WeatherXu Ruby SDK
Official Ruby SDK for accessing WeatherXu's weather data API.
Installation
Add this line to your application's Gemfile:
gem 'weatherxu'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install weatherxu
Quick Start
require 'weatherxu'
# Initialize the client
client = WeatherXu.new(
api_key: 'YOUR_API_KEY',
units: 'metric'
)
begin
# Get current weather and forecast for New York City
weather = client.get_weather(
lat: 40.7128,
lon: -74.0060,
parts: ['currently', 'hourly', 'daily']
)
# Access current conditions
puts "Current temperature: #{weather.currently.temperature}°C"
# Access hourly forecast
weather.hourly&.each do |hour|
puts "Time: #{hour.forecast_start.strftime('%Y-%m-%d %H:%M')}, " \
"Temperature: #{hour.temperature}°C"
end
# Get historical weather data
end_time = Time.now.to_i
start_time = end_time - (24 * 60 * 60) # 24 hours ago
historical = client.get_historical(
lat: 40.7128,
lon: -74.0060,
start: start_time,
end_time: end_time
)
# Access historical data
historical.hourly.each do |record|
puts "Time: #{record.forecast_start.strftime('%Y-%m-%d %H:%M')}, " \
"Temperature: #{record.temperature}°C"
end
rescue WeatherXu::Error => e
puts "Error: #{e.message}"
puts "Status code: #{e.status_code}" if e.status_code
puts "Error code: #{e.error_code}" if e.error_code
end
Features
- Modern Ruby features and best practices
- Automatic parsing of timestamps to Time objects
- Comprehensive error handling
- Support for both metric and imperial units
- Configurable request timeout
- Automatic retries with exponential backoff
API Reference
Initialization
WeatherXu.new(
api_key: String,
units: String = "metric",
timeout: Integer = 10
)
Methods
get_weather
Get current weather and forecast data for a location.
get_weather(
lat: Float,
lon: Float,
parts: Array<String> = nil,
units: String = nil
) -> WeatherData
Parameters:
-
lat
: Latitude (-90 to 90) -
lon
: Longitude (-180 to 180) -
parts
: Optional array of data blocks to include ('alerts', 'currently', 'hourly', 'daily') -
units
: Optional unit system ('metric' or 'imperial')
get_historical
Get historical weather data for a location.
get_historical(
lat: Float,
lon: Float,
start: Integer,
end_time: Integer,
units: String = nil
) -> HistoricalData
Parameters:
-
lat
: Latitude (-90 to 90) -
lon
: Longitude (-180 to 180) -
start
: Start time (Unix timestamp) -
end_time
: End time (Unix timestamp) -
units
: Optional unit system ('metric' or 'imperial')
Error Handling
The SDK raises WeatherXu::Error
for any API or network-related errors. Each error includes:
- Error message
- HTTP status code (when available)
- API error code (when provided 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
.
Requirements
- Ruby 2.7 or higher