{"id":15487869,"url":"https://github.com/dblock/open-weather-ruby-client","last_synced_at":"2025-04-04T22:03:30.714Z","repository":{"id":53510108,"uuid":"259527634","full_name":"dblock/open-weather-ruby-client","owner":"dblock","description":"OpenWeather Ruby Client","archived":false,"fork":false,"pushed_at":"2025-03-23T14:02:54.000Z","size":180,"stargazers_count":36,"open_issues_count":6,"forks_count":23,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T21:02:09.428Z","etag":null,"topics":["openweather","openweather-api"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dblock.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["dblock"]}},"created_at":"2020-04-28T04:05:26.000Z","updated_at":"2025-03-23T14:02:58.000Z","dependencies_parsed_at":"2024-06-21T14:23:54.767Z","dependency_job_id":"ba49aa48-6ddd-43c8-8816-4cb7703448f0","html_url":"https://github.com/dblock/open-weather-ruby-client","commit_stats":{"total_commits":32,"total_committers":3,"mean_commits":"10.666666666666666","dds":0.28125,"last_synced_commit":"7c2fb36a07f5a925b2ae3442eaf0c80b427f75d4"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dblock%2Fopen-weather-ruby-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dblock%2Fopen-weather-ruby-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dblock%2Fopen-weather-ruby-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dblock%2Fopen-weather-ruby-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dblock","download_url":"https://codeload.github.com/dblock/open-weather-ruby-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256104,"owners_count":20909240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openweather","openweather-api"],"created_at":"2024-10-02T06:42:52.545Z","updated_at":"2025-04-04T22:03:30.684Z","avatar_url":"https://github.com/dblock.png","language":"Ruby","funding_links":["https://github.com/sponsors/dblock"],"categories":[],"sub_categories":[],"readme":"OpenWeather Ruby Client\n=======================\n\n[![Gem Version](https://badge.fury.io/rb/open-weather-ruby-client.svg)](https://badge.fury.io/rb/open-weather-ruby-client)\n[![Tests Status](https://github.com/dblock/open-weather-ruby-client/actions/workflows/test.yml/badge.svg)](https://github.com/dblock/open-weather-ruby-client/actions)\n\nA Ruby client for the [OpenWeather API v2.5 and v3.0](https://openweathermap.org/api).\n\nUnlike other clients, including [open-weather](https://github.com/coderhs/ruby_open_weather_map), provides a rich first class interface to OpenWeather models, structured timestamps, built-in metrics conversion for temperature and wind speed, offers more consistent error handling, and is implemented with thorough test coverage using actual OpenWeather data.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Current Weather](#current-weather)\n  - [Current Weather for Several Cities](#current-weather-for-several-cities)\n    - [Cities Within a Rectangle Zone](#cities-within-a-rectangle-zone)\n    - [Cities Within a Circle](#cities-within-a-circle)\n    - [Multiple Cities by Id](#multiple-cities-by-id)\n  - [One Call](#one-call)\n    - [Current and Forecast Weather](#current-and-forecast-weather)\n    - [Historical Weather](#historical-weather)\n  - [Hourly Forecast (Pro)](#hourly-forecast-pro)\n  - [30 Day Forecast (Pro)](#30-day-forecast-pro)\n  - [5 Day Forecast](#5-day-forecast)\n  - [Stations](#stations)\n    - [Register a Station](#register-a-station)\n    - [List Stations](#list-stations)\n    - [Get Station](#get-station)\n    - [Update Station](#update-station)\n    - [Delete Station](#delete-station)\n    - [Create Measurements](#create-measurements)\n    - [Get Measurements](#get-measurements)\n- [Configuration](#configuration)\n  - [Units](#units)\n    - [Converting Temperature](#converting-temperature)\n    - [Converting Wind Speed](#converting-wind-speed)\n  - [Language](#language)\n- [Errors](#errors)\n- [Resources](#resources)\n- [Contributing](#contributing)\n- [Copyright and License](#copyright-and-license)\n\n## Installation\n\nAdd to Gemfile.\n\n```\ngem 'open-weather-ruby-client'\n```\n\nRun `bundle install`.\n\n## Usage\n\nUse an access token obtained from [API Keys](https://home.openweathermap.org/api_keys) on the OpenWeather website after registration.\n\n```ruby\nclient = OpenWeather::Client.new(\n  api_key: \"1a2b3c4d5a6b7c8d9a8b7c6d5a4b3c2d1\"\n)\n```\n\n### Current Weather\n\nReturns [current weather](https://openweathermap.org/current).\n\n```ruby\ndata = client.current_weather(city: 'London') # =\u003e OpenWeather::Models::City::Weather\n\ndata.name # =\u003e 'London'\ndata.dt # =\u003e Time\ndata.main.feels_like # =\u003e 277.73\ndata.main.humidity # =\u003e 81\ndata.main.pressure # =\u003e 1005\ndata.main.temp # =\u003e 282.57\ndata.main.temp_max # =\u003e 283.15, degrees Kelvin\ndata.main.temp_max_c # =\u003e 10, degrees Celcius\ndata.main.temp_max_f # =\u003e 50.0, degrees Farenheit\ndata.main.temp_min # =\u003e 281.48\n```\n\nReturns the current weather in metric units and Russian metadata.\n\n```ruby\ndata = client.current_weather(city: 'Moscow', units: 'metric', lang: 'ru') # =\u003e OpenWeather::Models::City::Weather\n\ndata.name # =\u003e 'Москва'\ndata.main.temp # =\u003e 12\n```\n\nReturns weather by city, optional state (in the US) and optional ISO 3166 country code.\nNames that cannot be resolved will cause the API call to raise a `Faraday::ResourceNotFound` error.\n\n```ruby\nclient.current_city('Sydney')\nclient.current_city('London, UK')\nclient.current_city('London', 'UK')\nclient.current_city('Albany')\nclient.current_city('Albany, New York')\nclient.current_city('Albany, New York', 'US')\nclient.current_city('Albany, NY', 'US')\nclient.current_city('Albany', 'New York', 'US')\nclient.current_city('Albany', 'NY', 'US')\nclient.current_city('Albany', 'NY')  # 2-letter state abbreviation w/o country will raise Faraday::ResourceNotFound\n\nclient.current_weather(city: 'Albany', state: 'NY', country: 'US')\n```\n\nReturns weather by city ID.\n\n```ruby\nclient.current_city_id(2643743) # =\u003e weather in London\nclient.current_weather(id: 2643743) # =\u003e weather in London\n```\n\nReturns weather by latitude and longitude.\n\n```ruby\nclient.current_geo(51.51, -0.13) # =\u003e weather in London\nclient.current_weather(lat: 51.51, lon: -0.13) # =\u003e weather in London\n```\n\nReturns weather by zip code with an optional country code (defaults to US).\n\n```ruby\nclient.current_zip(10018, 'US') # =\u003e weather in New York, 10018\nclient.current_weather(zip: 10018, country: 'US') # =\u003e weather in New York, 10018\n```\n\nSee [OpenWeather::Models::City::Weather](lib/open_weather/models/city/weather.rb) and related [OpenWeather::Models](lib/open_weather/models) for all available properties.\n\n### Current Weather for Several Cities\n\nCollection APIs return [OpenWeather::Models::List](lib/open_weather/models/list.rb), which includes multiple instances of [OpenWeather::Models::City::Weather](lib/open_weather/models/city/weather.rb).\n\n#### Cities Within a Rectangle Zone\n\n```ruby\ndata = client.current_cities_geo_box(12, 32, 15, 37, 10) # =\u003e OpenWeather::Models::List\n\ndata.first.name # 'Birkirkara'\ndata.main.temp # =\u003e 16.23\n```\n\nYou can optionally name parameters.\n\n```ruby\nclient.current_cities_geo_box(lon_left: 12, lat_bottom: 32, lon_right: 15, lat_top: 37, zoom: 10) # =\u003e OpenWeather::Models::List\n```\n\nYou can use server clustering of points with `cluster: true`.\n\n```ruby\nclient.current_cities_geo_box(12, 32, 15, 37, 10, cluster: true) # =\u003e OpenWeather::Models::List\n```\n\n#### Cities Within a Circle\n\n```ruby\ndata = client.current_cities_geo_circle(55.5, 37.5, 10) # =\u003e OpenWeather::Models::List\n\ndata.first.name # 'Shcherbinka'\ndata.main.temp # =\u003e 276.86\n```\n\nYou can optionally name parameters.\n\n```ruby\nclient.current_cities_geo_circle(lat: 55.5, lon: 37.5, cnt: 7) # =\u003e OpenWeather::Models::List\n```\n\n#### Multiple Cities by Id\n\n```ruby\ndata = client.current_cities_id(524901, 703448, 2643743) # =\u003e OpenWeather::Models::List\n\ndata.first.name # 'Moscow'\ndata.main.temp # =\u003e 285.15\n```\n\n### One Call\n\n[One Call API](https://openweathermap.org/api/one-call-api) provides current weather, minute forecast for 1 hour, hourly forecast for 48 hours, daily forecast for 7 days, historical weather data for 5 previous days for any geographical coordinate, and national weather alerts.\n\nSee [OpenWeather::Models::OneCall](lib/open_weather/models/one_call) for all available models and properties.\n\n#### Current and Forecast Weather\n\n```ruby\ndata = client.one_call(lat: 33.441792, lon: -94.037689) # =\u003e OpenWeather::Models::OneCall::Weather\n\ndata.lat # =\u003e 33.44\ndata.lon # =\u003e -94.04\ndata.timezone # =\u003e 'America/Chicago'\ndata.current # =\u003e OpenWeather::Models::OneCall::CurrentWeather\ndata.data # =\u003e Array]OpenWeather::Models::OneCall::CurrentWeather] (on base plan)\ndata.minutely # =\u003e Array[OpenWeather::Models::OneCall::MinutelyWeather]\ndata.hourly # =\u003e Array[OpenWeather::Models::OneCall::HourlyWeather]\ndata.daily # =\u003e Array[OpenWeather::Models::OneCall::DailyWeather]\ndata.alerts # =\u003e Array[OpenWeather::Models::OneCall::Alert]\n```\n\nExclude minutely and hourly data.\n\n```ruby\nclient.one_call(lat: 33.441792, lon: -94.037689, exclude: ['minutely', 'hourly'])\n```\n\n#### Historical Weather\n\n```ruby\ndata = client.one_call(lat: 33.441792, lon: -94.037689, dt: Time.now - 24 * 60 * 60) # =\u003e OpenWeather::Models::OneCall::Weather\n\ndata.lat # =\u003e 33.44\ndata.lon # =\u003e -94.04\ndata.timezone # =\u003e 'America/Chicago'\ndata.current # =\u003e OpenWeather::Models::OneCall::CurrentWeather\ndata.hourly # =\u003e Array[OpenWeather::Models::OneCall::HourlyWeather]\n```\n\n### Hourly Forecast (Pro)\n\nThe [Hourly Forecast API](https://openweathermap.org/api/hourly-forecast) provides hourly weather forecast for 4 days.  Note: This API requires a paid api-key from [OpenWeather.org](https://openweathermap.org/full-price#current).\n\n```ruby\ndata = client.client.hourly(lat: 33.5312, lon: -111.9426, appid: \"\u003cyour api key\u003e\") # =\u003e OpenWeather::Models::Forecast::Hourly\n\ndata.cnt # =\u003e 96 (number of entries)\ndata.city # =\u003e OpenWeather::Models::Forecast::City\ndata.list.first # =\u003e OpenWeather::Models::Forecast::Forecast\ndata.list.first.dt # =\u003e Time\ndata.list.first.main # =\u003e OpenWeather::Models::Forecast::Main\ndata.list.first.weather # =\u003e Array[OpenWeather::Models::Forecast::Weather]\ndata.list.first.clouds # =\u003e OpenWeather::Models::Forecast::Clouds or nil\ndata.list.first.wind # =\u003e OpenWeather::Models::Forecast::Wind or nil\ndata.list.first.visibility # =\u003e 10000\ndata.list.first.pop # =\u003e 0.1 (probability of precipitation from 0.0 to 1.0 (0% to 100%))\ndata.list.first.rain # =\u003e OpenWeather::Models::Forecast::Rain or nil\ndata.list.first.snow # =\u003e OpenWeather::Models::Forecast::Snow or nil\ndata.list.first.sys # =\u003e OpenWeather::Models::Forecast::Sys or nil\ndata.list.first.dt_txt # =\u003e String (Time of data forecasted, ISO, UTC)\n```\n\n### 30 Day Forecast (Pro)\n\nThe [30 Day Forecast API](https://openweathermap.org/api/forecast30) provides daily weather forecast for 30 days.  Note: This API requires a paid api-key from [OpenWeather.org](https://openweathermap.org/full-price#current).\n\n```ruby\ndata = client.client.forecast(lat: 33.5312, lon: -111.9426, appid: \"\u003cyour api key\u003e\") # =\u003e OpenWeather::Models::Forecast::ThirtyDay::ThirtyDay\n\ndata.cnt # =\u003e 30 (number of entries - sometimes this is 29)\ndata.city # =\u003e OpenWeather::Models::Forecast::City\ndata.list.first # =\u003e OpenWeather::Models::Forecast::ThirtyDay::Forecast\ndata.list.first.dt # =\u003e Time - time of data forcasted, UTC\ndata.list.first.sunrise # =\u003e Time - Sunrise time, UTC\ndata.list.first.sunset # =\u003e Time - Sunset time, UTC\ndata.list.first.temp # =\u003e OpenWeather::Models::Forecast::ThirtyDay::Temp\ndata.list.first.feels_like # =\u003e OpenWeather::Models::OneCall::FeelsLike\ndata.list.first.pressure # =\u003e int - Atmospheric pressure on the sea level, hPa\ndata.list.first.humidity # =\u003e int - Humidity, % (e.g. integer 24 means 24% cloudiness)\ndata.list.first.weather # =\u003e Array[OpenWeather::Models::Weather]\ndata.list.first.speed # =\u003e double - Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour\ndata.list.first.deg # =\u003e int - Wind direction, degrees (meteorological)\ndata.list.first.clouds # =\u003e int - Cloudiness, % (e.g. integer 78 means 78% cloudiness)\ndata.list.first.rain # =\u003e double or nil - Precipitation volume, mm. Please note that only mm as units of measurement are available for this parameter\ndata.list.first.snow # =\u003e double or nil - Snow volume, mm. Please note that only mm as units of measurement are available for this parameter\n```\n\n### 5 Day Forecast\n\nThe [5 Day Forecast API](https://openweathermap.org/forecast5) provides weather forecast for 5 days with data every 3 hours by geographic coordinates.\n\n```ruby\ndata = client.client.five_day_forecast(lat: 33.5312, lon: -111.9426, appid: \"\u003cyour api key\u003e\") # =\u003e OpenWeather::Models::Forecast::FiveDay\n\ndata.cnt # =\u003e 40 (number of entries)\ndata.list.first # =\u003e OpenWeather::Models::Forecast::FiveDay::Forecast\ndata.list.first.dt # =\u003e Time\ndata.list.first.main # =\u003e OpenWeather::Models::Main\ndata.list.first.weather # =\u003e Array[OpenWeather::Models::Weather]\ndata.list.first.clouds # =\u003e OpenWeather::Models::Clouds or nil\ndata.list.first.wind # =\u003e OpenWeather::Models::Wind or nil\ndata.list.first.visibility # =\u003e 10000\ndata.list.first.pop # =\u003e 0.1 (probability of precipitation from 0.0 to 1.0 (0% to 100%))\ndata.list.first.rain # =\u003e OpenWeather::Models::Rain or nil\ndata.list.first.snow # =\u003e OpenWeather::Models::Snow or nil\ndata.list.first.sys # =\u003e OpenWeather::Models::Sys or nil\ndata.list.first.dt_txt # =\u003e String (Time of data forecasted, ISO, UTC)\n```\n\n### Stations\n\nThe [Stations API](https://openweathermap.org/stations) lets your manage personal weather stations and measurements.\n\n#### Register a Station\n\nTo register a station, you can call the client method:\n```ruby\ndata = client.register_station(external_id: 'SF_TEST001', ...) # =\u003e OpenWeather::Models::Station\ndata.id # =\u003e '5ed2118acca8ce0001f1aeg1'\ndata.external_id # =\u003e 'SF_TEST001'\n```\nAlternatively, call `register!` on an instance of `Station`:\n```ruby\nmodel = OpenWeather::Models::Station.new(external_id: 'SF_TEST001', ...)\nmodel.register!\nmodel.id # =\u003e '5ed2118acca8ce0001f1aeg1'\n```\n\n#### List Stations\n\nTo list all stations, call the client method:\n```ruby\nclient.list_stations # =\u003e Array[OpenWeather::Models::Station]\n```\n\n#### Get Station\n\nTo get a station, call the client method:\n```ruby\nclient.get_station('5ed2118acca8ce0001f1aeg1') # =\u003e OpenWeather::Models::Station\n```\n\n#### Update Station\n\nTo update a station, call the client method:\n```ruby\nclient.update_station('5ed2118acca8ce0001f1aeg1', external_id: 'SF_TEST002') # =\u003e OpenWeather::Models::Station\n```\nAlternatively, call `update!` on an instance of `Station`:\n```ruby\nmodel = OpenWeather::Models::Station.new(external_id: 'SF_TEST001', ...)\nmodel.register!\nmodel.update!(external_id: 'SF_TEST002')\nmodel.external_id # =\u003e 'SF_TEST002'\n```\n\n#### Delete Station\n\nTo delete a station, call the client method:\n```ruby\ndata = client.delete_station('5ed2118acca8ce0001f1aeg1') # =\u003e nil\n```\n\n#### Create Measurements\n\nTo create measurements, call the client method:\n```ruby\nclient.create_measurements([\n  {\n    \"station_id\": -1,\n    \"dt\": 1479817340,\n    \"temperature\": 18.7,\n    \"wind_speed\": 1.2,\n    \"wind_gust\": 3.4,\n    \"pressure\": 1021,\n    \"humidity\": 87,\n    \"rain_1h\": 2,\n    \"clouds\": [\n      {\n        \"condition\": 'NSC'\n      }\n    ]\n  }\n]) # =\u003e nil\n```\n\n#### Get Measurements\n\nTo get measurements, call the client method with the required parameters:\n```ruby\nclient.get_measurements(\n  station_id: '5ed21a12cca8ce0001f1aef1',\n  type: 'd',\n  limit: 100,\n  from: 1469817340,\n  to: 1591620047\n) # =\u003e Array[OpenWeather::Models::Stations::Measurement]\n```\n\n## Configuration\n\nYou can configure client options, globally.\n\n```ruby\nOpenWeather::Client.configure do |config|\n  config.api_key = '1a2b3c4d5a6b7c8d9a8b7c6d5a4b3c2d1'\n  config.user_agent = 'OpenWeather Ruby Client/1.0'\nend\n```\n\nThe following settings are supported.\n\n| setting      | description                                                |\n| ------------ | ---------------------------------------------------------- |\n| api_key      | Required API key.                                          |\n| lang         | Default language in API responses.                         |\n| units        | Default units in API responses.                            |\n| endpoint     | Defaults to `https://api.openweathermap.org/data`.         |\n| user_agent   | User-agent, defaults to _OpenWeather Ruby Client/version_. |\n| proxy        | Optional HTTP proxy.                                       |\n| ca_path      | Optional SSL certificates path.                            |\n| ca_file      | Optional SSL certificates file.                            |\n| logger       | Optional `Logger` instance that logs HTTP requests.        |\n| timeout      | Optional open/read timeout in seconds.                     |\n| open_timeout | Optional connection open timeout in seconds.               |\n\n### Units\n\nThe OpenWeather API returns responses in `standard`, `metric`, and `imperial` units. You can pass `units` into API requests or configure the desired units globally.\n\n```ruby\ndata = client.weather(id: 2643743, units: 'metric')\ndata.name # =\u003e 'London'\ndata.main.temp # =\u003e 12, degrees Celcius\n```\n\n```ruby\nOpenWeather.configure do |config|\n  config.units = 'metric'\nend\n\ndata = client.weather(id: 2643743)\ndata.name # =\u003e 'London'\ndata.main.temp # =\u003e 12, degrees Celcius\n```\n\n#### Converting Temperature\n\nAPIs that return temperature support conversion between default, metric and imperial units, regardless of what units were requested. The following example requests current weather in metric units in Moscow. Use `_k` for Kelvin, `_c` for Celcius and `_f` for Farenheit.\n\n```ruby\ndata = client.current_weather(city: 'Moscow', units: 'metric') # =\u003e OpenWeather::Models::City::Weather\n\ndata.main.temp_max # =\u003e 12, degrees Celcius, metric as requested\ndata.main.temp_max_c # =\u003e 12, degrees Celcius\ndata.main.temp_max_k # =\u003e 285.15, degrees Kelvin\ndata.main.temp_max_f # =\u003e 53.6, degrees Farenheit\n```\n\n#### Converting Wind Speed\n\nUse `_mps` for wind speed in meters-per-second, and `_mph` for miles-per-second.\n\n```ruby\ndata.wind.speed # =\u003e 3, in meters per second, metric as requested\ndata.main.speed_mph # =\u003e 6.71, miles per hour\ndata.main.speed_mps # 3, meters per second\n```\n\n### Language\n\nThe OpenWeather API returns responses in English and supports many other languages. You can pass `lang` into API requests or configure the desired language globally.\n\n```ruby\ndata = client.weather(id: 2643743, lang: 'ru')\ndata.name # =\u003e 'Лондон'\n```\n\n```ruby\nOpenWeather.configure do |config|\n  config.lang = 'ru'\nend\n\ndata = client.weather(id: 2643743)\ndata.name # =\u003e 'Лондон'\n```\n\n## Errors\n\nAll errors that return HTTP codes 400-600 result in either `Faraday::ResourceNotFound`, `Faraday::ConnectionFailed` or [OpenWeather::Errors::Fault](lib/open_weather/errors/fault.rb) exceptions.\n\n## Resources\n\n* [OpenWeather API Documentation](https://openweathermap.org/api)\n\n## Contributing\n\nSee [CONTRIBUTING](CONTRIBUTING.md).\n\n## Copyright and License\n\nCopyright (c) 2020, [Daniel Doubrovkine](https://twitter.com/dblockdotorg)\n\nThis project is licensed under the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdblock%2Fopen-weather-ruby-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdblock%2Fopen-weather-ruby-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdblock%2Fopen-weather-ruby-client/lists"}