https://github.com/weatherxu/weatherxu-ruby
Official Ruby SDK for WeatherXu
https://github.com/weatherxu/weatherxu-ruby
api forecast rails ruby weather
Last synced: 5 months ago
JSON representation
Official Ruby SDK for WeatherXu
- Host: GitHub
- URL: https://github.com/weatherxu/weatherxu-ruby
- Owner: weatherxu
- License: mit
- Created: 2025-01-29T21:10:13.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-29T21:10:32.000Z (over 1 year ago)
- Last Synced: 2025-12-03T16:59:06.309Z (7 months ago)
- Topics: api, forecast, rails, ruby, weather
- Language: Ruby
- Homepage: https://weatherxu.com/
- Size: 5.86 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# WeatherXu Ruby SDK
Official Ruby SDK for accessing WeatherXu's weather data API.
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'weatherxu'
```
And then execute:
```bash
$ bundle install
```
Or install it yourself as:
```bash
$ gem install weatherxu
```
## Quick Start
```ruby
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
```ruby
WeatherXu.new(
api_key: String,
units: String = "metric",
timeout: Integer = 10
)
```
### Methods
#### get_weather
Get current weather and forecast data for a location.
```ruby
get_weather(
lat: Float,
lon: Float,
parts: Array = 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.
```ruby
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