loqate 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99e0ea7429e262e3ea0d27b5b97e47069414bc0c7f04306df780884e4827f333
-  data.tar.gz: c6e29931639924647a9a23eb753258c2baf1c7edf650413ebe28ab054d0dc1f2
+  metadata.gz: 18b2de06a287567be0f1ccce8dc27723ed9ff5a786ffa4d2dbfa365be936bb60
+  data.tar.gz: cc2ca8285a696744a06967f66809afc2bf045a88a4d47b507f0b5ab70bb2eb30
 SHA512:
-  metadata.gz: 1804077569ad841285a33eeba7edd9ab2a323069220d2782996f65d1f270acf35088a25c96ed29381609919190e230e54bded7fa3464c103fc39666832e8d250
-  data.tar.gz: 332955af60f1623ca8f4249b9cefda5a35a63c4a84aa4488aa674a7ca2776e7259fe1e8d378988c0382a56854f79b087335bcf2d367116a7e4b82346a2767da9
+  metadata.gz: 8de9e9a790722ce940c8859ea30176f09685daf9904c49ecd432fa3aad0b9e94a1f7120f0fb55886c7c1b18510ee15f8ed156d100bdf51b0fd3c6afb0c7c5d5b
+  data.tar.gz: 7c36a6013d07df700d6cc42a16746d8207a4a95ded5aae5dff3a33bf3275bfbd5a594fd9f3d50451afc381d1867baa24a5bc928733e47562f31a4e2638eaf970

data/.yardstick.yml

@@ -81,6 +81,16 @@ rules:
       - Loqate::Bank::CardValidation#card_type
       - Loqate::Bank::Gateway#build_branch_from
       - Loqate::Bank::Gateway#initialize
+      - Loqate::Geocoding::Country#country_name
+      - Loqate::Geocoding::Country#country_iso2
+      - Loqate::Geocoding::Country#country_iso3
+      - Loqate::Geocoding::Country#country_iso_number
+      - Loqate::Geocoding::Gateway#position_to_country!
+      - Loqate::Geocoding::Gateway#directions!
+      - Loqate::Geocoding::Gateway#geocode!
+      - Loqate::Geocoding::Location#name
+      - Loqate::Geocoding::Location#latitude
+      - Loqate::Geocoding::Location#longitude
       - Loqate::Bank::InternationalAccountValidation#correct?
       - Loqate::Bank::InternationalAccountValidation#is_correct
       - Loqate::Email::BatchEmailValidation#account
@@ -124,6 +134,7 @@ rules:
       - Loqate::Gateway#geocoding
       - Loqate::Gateway#initialize
       - Loqate::Gateway#phone
+      - Loqate::Geocoding::Gateway#directions
       - Loqate::Geocoding::Gateway#initialize
       - Loqate::Geocoding::Direction#segment_number
       - Loqate::Geocoding::Direction#step_number
@@ -190,6 +201,8 @@ rules:
       - Loqate::Email::Gateway#mapper
       - Loqate::Error#attributes
       - Loqate::Gateway#client
+      - Loqate::Geocoding::Gateway#build_country_from
+      - Loqate::Geocoding::Gateway#build_location_from
       - Loqate::Geocoding::Gateway#error_mapper
       - Loqate::Geocoding::Gateway#client
       - Loqate::Geocoding::Gateway#mapper
@@ -244,11 +257,13 @@ rules:
       - Loqate::Email::Gateway#mapper
       - Loqate::Error#attributes
       - Loqate::Gateway#client
+      - Loqate::Geocoding::Gateway#build_country_from
       - Loqate::Geocoding::Gateway#error_mapper
       - Loqate::Geocoding::Gateway#client
       - Loqate::Geocoding::Gateway#mapper
       - Loqate::Geocoding::Gateway#build_error_from
       - Loqate::Geocoding::Gateway#build_directions_from
+      - Loqate::Geocoding::Gateway#build_location_from
       - Loqate::Phone::Gateway#build_error_from
       - Loqate::Phone::Gateway#build_phone_validation_from
       - Loqate::Phone::Gateway#client

data/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2018-12-11
+### Added
+- Geocoding service of the Geocoding API
+- A service to calculate the country a given location is within
+
 ## [0.8.0] - 2018-12-10
 ### Added
 - Distance service of the Geocoding API
@@ -61,6 +66,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Initial core functionality
 - Codebase maintenance tools
 
+[0.9.0]: https://github.com/wilsonsilva/loqate/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/wilsonsilva/loqate/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/wilsonsilva/loqate/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/wilsonsilva/loqate/compare/v0.5.0...v0.6.0

data/README.md

@@ -21,6 +21,8 @@ Client to address verification, postcode lookup, & data quality services from Lo
     - [Retrieving the details of an address](#retrieving-the-details-of-an-address)
   - [Geocoding API](#geocoding-api)
     - [Finding directions](#finding-directions)
+    - [Geocoding a location](#geocoding-a-location)
+    - [Finding a country based on coordinates](#finding-a-country-based-on-coordinates)
   - [Phone API](#phone-api)
     - [Validating a phone number](#validating-a-phone-number)
   - [Email API](#phone-api)
@@ -142,6 +144,18 @@ directions = gateway.geocoding.directions!(
 directions.first.description # => 'Leave from Strand/A4'
 ```
 
+#### Geocoding a location
+```ruby
+location = gateway.geocoding.geocode!(country: 'US', location: '90210')
+location.name # => 'Beverly Hills, CA 90210'
+```
+
+#### Finding a country based on coordinates
+```ruby
+country = gateway.geocoding.position_to_country!(latitude: 52.1321, longitude: -2.1001)
+country.country_name # => 'United Kingdom'
+```
+
 ### Phone API
 
 The Phone API consists of a single API request:

data/ROADMAP.md

@@ -9,9 +9,12 @@
 - [x] Domain error handling
 - [x] Configuration
 - [x] Unwrap request results
-- [ ] Validate request parameters
 - [ ] API/Service versioning
-- [ ] Integration with RSpec
+
+## Extended
+- [ ] Validate request parameters before submitting a request
+- [ ] Integration with RSpec (Mocks and Matchers)
+- [ ] Implement Google Open Location Code in the Geocoding API (https://github.com/google/open-location-code)
 
 ## APIs
 

data/lib/loqate/geocoding/country.rb

@@ -0,0 +1,30 @@
+module Loqate
+  module Geocoding
+    # A result from the position to country API call.
+    class Country < Dry::Struct::Value
+      # The name of the country where the position belongs to.
+      #
+      # @return [String]
+      #
+      attribute :country_name, Types::Strict::String
+
+      # The ISO2 of the country.
+      #
+      # @return [String]
+      #
+      attribute :country_iso2, Types::Strict::String
+
+      # The ISO3 of the country.
+      #
+      # @return [String]
+      #
+      attribute :country_iso3, Types::Strict::String
+
+      # The ISO number of the country.
+      #
+      # @return [Integer]
+      #
+      attribute :country_iso_number, Types::Strict::Integer
+    end
+  end
+end

data/lib/loqate/geocoding/gateway.rb

@@ -1,14 +1,18 @@
 require 'loqate/client'
 require 'loqate/result'
+require 'loqate/geocoding/country'
 require 'loqate/geocoding/direction'
+require 'loqate/geocoding/location'
 require 'loqate/mappers/error_mapper'
 require 'loqate/mappers/generic_mapper'
 
 module Loqate
   module Geocoding
-    # Retrieves
+    # Performs API requests to the geocoding services.
     class Gateway
       DIRECTIONS_ENDPOINT = '/DistancesAndDirections/Interactive/Directions/v2.00/json3.ws'.freeze
+      GEOCODE_ENDPOINT = '/Geocoding/International/Geocode/v1.10/json3.ws'.freeze
+      POSITION_TO_COUNTRY_ENDPOINT = '/Geocoding/International/PositionToCountry/v1.00/json3.ws'.freeze
 
       include Result::Mixin
 
@@ -85,6 +89,81 @@ module Loqate
         response.errors? && build_error_from(response.items.first) || build_directions_from(response.items)
       end
 
+      # Returns the directions between two or more points.
+      #
+      # @raise [Error] If the result is not a success
+      #
+      # @see Loqage::Geocoding::Geocoding#directions
+      #
+      # @return [Array<Direction>] A list of directions.
+      #
+      def directions!(options)
+        unwrap_result_or_raise { directions(options) }
+      end
+
+      # Returns the WGS84 latitude and longitude for the given location. Supports most international locations.
+      #
+      # @param [Hash] options The options to geocode.
+      # @option options [String] :country The name or ISO 2 or 3 character code for the country to search in.
+      #   Most country names will be recognised but the use of the ISO country code is recommended for clarity.
+      # @option options [String] :location The location to geocode. This can be a postal code or place name.
+      #
+      # @example
+      #   result = geocoding_gateway.geocode(country: 'US', location: '90210')
+      #
+      # @return [Result] A result wrapping a location.
+      #
+      def geocode(options)
+        response = client.get(GEOCODE_ENDPOINT, options)
+
+        response.errors? && build_error_from(response.items.first) || build_location_from(response.items.first)
+      end
+
+      # Returns the WGS84 latitude and longitude for the given location. Supports most international locations.
+      #
+      # @raise [Error] If the result is not a success
+      #
+      # @see Loqate::Geocoding::Geocoding#geocode
+      #
+      # @return [Location] A location.
+      #
+      def geocode!(options)
+        unwrap_result_or_raise { geocode(options) }
+      end
+
+      # Returns the country based on the WGS84 latitude and longitude supplied. No result is returned if
+      # the coordinates are in international waters.
+      #
+      # @param [Hash] options The coordinates of the position to search against.
+      # @option options [Float] :latitude The latitude of the position to search against.
+      # @option options [Float] :longitude The longitude of the position to search against.
+      #
+      # @example
+      #   result = geocoding_gateway.position_to_country(latitude: 52.1321, longitude: -2.1001)
+      #
+      # @return [Result|nil] A result wrapping a country.
+      #
+      def position_to_country(options)
+        response = client.get(POSITION_TO_COUNTRY_ENDPOINT, options)
+
+        return Success(nil) if response.items.empty?
+
+        response.errors? && build_error_from(response.items.first) || build_country_from(response.items.first)
+      end
+
+      # Returns the country based on the WGS84 latitude and longitude supplied. No result is returned if
+      # the coordinates are in international waters.
+      #
+      # @raise [Error] If the result is not a success
+      #
+      # @see Loqate::Geocoding::Geocoding#position_to_country
+      #
+      # @return [Country] A country.
+      #
+      def position_to_country!(options)
+        unwrap_result_or_raise { position_to_country(options) }
+      end
+
       private
 
       # @api private
@@ -97,10 +176,22 @@ module Loqate
       end
 
       # @api private
-      def build_directions_from(item)
-        direction = mapper.map(item, Direction)
+      def build_directions_from(items)
+        direction = mapper.map(items, Direction)
         Success(direction)
       end
+
+      # @api private
+      def build_location_from(item)
+        location = mapper.map_one(item, Location)
+        Success(location)
+      end
+
+      # @api private
+      def build_country_from(item)
+        country = mapper.map_one(item, Country)
+        Success(country)
+      end
     end
   end
 end

data/lib/loqate/geocoding/location.rb

@@ -0,0 +1,24 @@
+module Loqate
+  module Geocoding
+    # A result from the geocode API call.
+    class Location < Dry::Struct::Value
+      # The name of the location found.
+      #
+      # @return [String]
+      #
+      attribute :name, Types::Strict::String
+
+      # The WGS84 latitude of the found location.
+      #
+      # @return [Float]
+      #
+      attribute :latitude, Types::Strict::Float
+
+      # The WGS84 longitude of the found location.
+      #
+      # @return [Float]
+      #
+      attribute :longitude, Types::Strict::Float
+    end
+  end
+end

data/lib/loqate/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: loqate
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Wilson Silva
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-12-10 00:00:00.000000000 Z
+date: 2018-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-struct
@@ -361,8 +361,10 @@ files:
 - lib/loqate/email/gateway.rb
 - lib/loqate/error.rb
 - lib/loqate/gateway.rb
+- lib/loqate/geocoding/country.rb
 - lib/loqate/geocoding/direction.rb
 - lib/loqate/geocoding/gateway.rb
+- lib/loqate/geocoding/location.rb
 - lib/loqate/mappers/error_mapper.rb
 - lib/loqate/mappers/generic_mapper.rb
 - lib/loqate/phone/gateway.rb