Merge pull request #54 from dblock/add-geocoding-api

Add support for the Geocoding API

Author: dblock

CHANGELOG.md

@@ -1,5 +1,6 @@
-### 0.7.1 (Next)
+### 0.8.0 (Next)
 
+* [#54](https://github.com/dblock/open-weather-ruby-client/pull/54): Add support for the Geocoding API (`geo_direct`, `geo_reverse`, `geo_zip`) - [@dblock](https://github.com/dblock).
 * [#50](https://github.com/dblock/open-weather-ruby-client/pull/50): Fixes `Danger Comment` workflow failing with a `contents: none` permissions error - [@dblock](https://github.com/dblock).
 * [#51](https://github.com/dblock/open-weather-ruby-client/pull/51): Adds test coverage reporting with [coveralls.io](https://coveralls.io) - [@dblock](https://github.com/dblock).
 * [#53](https://github.com/dblock/open-weather-ruby-client/pull/53): Fixed coverage reporting to Coveralls not running on pull requests by switching from `coveralls_reborn`/`COVERALLS_REPO_TOKEN` to `coverallsapp/github-action`/`GITHUB_TOKEN` - [@dblock](https://github.com/dblock).

README.md

@@ -32,6 +32,10 @@ Unlike other clients, including [open-weather](https://github.com/coderhs/ruby_o
     - [Delete Station](#delete-station)
     - [Create Measurements](#create-measurements)
     - [Get Measurements](#get-measurements)
+  - [Geocoding](#geocoding)
+    - [Direct Geocoding](#direct-geocoding)
+    - [Reverse Geocoding](#reverse-geocoding)
+    - [Zip Code Geocoding](#zip-code-geocoding)
 - [Configuration](#configuration)
   - [Units](#units)
     - [Converting Temperature](#converting-temperature)
@@ -380,6 +384,43 @@ client.get_measurements(
 ) # => Array[OpenWeather::Models::Stations::Measurement]
 ```
 
+### Geocoding
+
+The [Geocoding API](https://openweathermap.org/api/geocoding-api) converts city names and zip/post codes to geographical coordinates, and vice versa.
+
+#### Direct Geocoding
+
+To get geographical coordinates for a city name, call the client method:
+```ruby
+client.geo_direct('London', nil, 'GB') # => Array[OpenWeather::Models::GeoLocation]
+```
+Or pass a hash of options.
+```ruby
+client.geo_direct(city: 'London', state: nil, country: 'GB', limit: 5) # => Array[OpenWeather::Models::GeoLocation]
+```
+
+#### Reverse Geocoding
+
+To get a location name for geographical coordinates, call the client method:
+```ruby
+client.geo_reverse(51.5074456, -0.1277653) # => Array[OpenWeather::Models::GeoLocation]
+```
+Or pass a hash of options.
+```ruby
+client.geo_reverse(lat: 51.5074456, lon: -0.1277653, limit: 5) # => Array[OpenWeather::Models::GeoLocation]
+```
+
+#### Zip Code Geocoding
+
+To get geographical coordinates for a zip/post code, call the client method:
+```ruby
+client.geo_zip('94040', 'US') # => OpenWeather::Models::GeoLocationZip
+```
+Or pass a hash of options.
+```ruby
+client.geo_zip(zip: '94040', country: 'US') # => OpenWeather::Models::GeoLocationZip
+```
+
 ## Configuration
 
 You can configure client options, globally.

lib/open_weather/client.rb

@@ -10,6 +10,7 @@ class Client
     include Endpoints::FiveDayForecast
     include Endpoints::OneCall
     include Endpoints::Stations
+    include Endpoints::Geocoding
 
     attr_accessor(*Config::ATTRIBUTES)
 

lib/open_weather/config.rb

@@ -7,6 +7,7 @@ module Config
     ATTRIBUTES = %i[
       endpoint
       pro_endpoint
+      geo_endpoint
       api_key
       proxy
       user_agent
@@ -24,6 +25,7 @@ module Config
     def reset
       self.endpoint = 'https://api.openweathermap.org/data'
       self.pro_endpoint = 'https://pro.openweathermap.org/data'
+      self.geo_endpoint = 'https://api.openweathermap.org/geo'
       self.api_key = nil
       self.user_agent = "OpenWeather Ruby Client/#{OpenWeather::VERSION}"
       self.ca_path = nil

lib/open_weather/endpoints.rb

@@ -6,3 +6,4 @@
 require_relative 'endpoints/hourly'
 require_relative 'endpoints/thirty_day_forecast'
 require_relative 'endpoints/five_day_forecast'
+require_relative 'endpoints/geocoding'

lib/open_weather/endpoints/geocoding.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OpenWeather
+  module Endpoints
+    module Geocoding
+      def geo_direct(name, state = nil, country = nil, options = {})
+        options = name.is_a?(Hash) ? options.merge(name) : options.merge(city: name, state: state, country: country)
+        options[:q] = [
+          options.delete(:city),
+          options.delete(:state),
+          options.delete(:country)
+        ].compact.join(',')
+        options[:endpoint] ||= geo_endpoint
+
+        get('1.0/direct', options).map { |data| OpenWeather::Models::GeoLocation.new(data) }
+      end
+
+      def geo_reverse(lat, lon = nil, options = {})
+        options = lat.is_a?(Hash) ? options.merge(lat) : options.merge(lat: lat, lon: lon)
+        options[:endpoint] ||= geo_endpoint
+
+        get('1.0/reverse', options).map { |data| OpenWeather::Models::GeoLocation.new(data) }
+      end
+
+      def geo_zip(code, country = nil, options = {})
+        options = code.is_a?(Hash) ? options.merge(code) : options.merge(zip: code, country: country)
+        options[:zip] = [
+          options.delete(:zip),
+          options.delete(:country)
+        ].compact.join(',')
+        options[:endpoint] ||= geo_endpoint
+
+        OpenWeather::Models::GeoLocationZip.new(get('1.0/zip', options))
+      end
+    end
+  end
+end

lib/open_weather/models.rb

@@ -15,6 +15,8 @@
 require_relative 'models/one_call'
 require_relative 'models/forecast'
 require_relative 'models/station'
+require_relative 'models/geo_location'
+require_relative 'models/geo_location_zip'
 require_relative 'models/stations/measurement'
 require_relative 'models/stations/temp'
 require_relative 'models/stations/humidity'

lib/open_weather/models/geo_location.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OpenWeather
+  module Models
+    class GeoLocation < Model
+      property 'name' # name of the found location
+      property 'local_names' # name of the found location in different languages
+      property 'lat' # geo location, latitude
+      property 'lon' # geo location, longitude
+      property 'country' # country of the found location
+      property 'state' # state of the found location
+    end
+  end
+end

lib/open_weather/models/geo_location_zip.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module OpenWeather
+  module Models
+    class GeoLocationZip < Model
+      property 'zip' # zip/post code
+      property 'name' # name of the found location
+      property 'lat' # geo location, latitude
+      property 'lon' # geo location, longitude
+      property 'country' # country of the found location
+    end
+  end
+end

lib/open_weather/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenWeather
-  VERSION = '0.7.1'
+  VERSION = '0.8.0'
 end