Project

weatherxu

0.0
The project is in a healthy, maintained state
A Ruby SDK for accessing WeatherXu's weather data, including current conditions, forecasts, and historical weather data.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Dependencies

Development

~> 2.0
~> 13.0
~> 3.0
~> 1.21
~> 0.9
 Project Readme

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