loqate 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fb61fc51df7e0d68f444bbdc456f8dc3908f4615a34ba36aa0a16265518ea86
-  data.tar.gz: 53aa2a20fde0da8a1cc284f56b18dde9edbd8def3c0f3265757ec5c30f388d23
+  metadata.gz: 99e0ea7429e262e3ea0d27b5b97e47069414bc0c7f04306df780884e4827f333
+  data.tar.gz: c6e29931639924647a9a23eb753258c2baf1c7edf650413ebe28ab054d0dc1f2
 SHA512:
-  metadata.gz: be0b4b5a521533eb1f023c60c1cbd5b203fb586333dfc3a3b52bda07fe8b35a57b9d42d94a0eaf4f1a531e3f3ac2ef56917e75b1ca514dbf078c06192dc8c106
-  data.tar.gz: 27f8a174a784a974f755d303ff2df0f8ec370e23781b25b7dc6ad86d2bd096bd959634e4c82506971d8e14b924ad4d8fd5acb5c8c69b7ed8b6b466c94a36d295
+  metadata.gz: 1804077569ad841285a33eeba7edd9ab2a323069220d2782996f65d1f270acf35088a25c96ed29381609919190e230e54bded7fa3464c103fc39666832e8d250
+  data.tar.gz: 332955af60f1623ca8f4249b9cefda5a35a63c4a84aa4488aa674a7ca2776e7259fe1e8d378988c0382a56854f79b087335bcf2d367116a7e4b82346a2767da9

data/.rubocop.yml

@@ -1,3 +1,5 @@
+require: rubocop-rspec
+
 AllCops:
   DisplayCopNames: true
 
@@ -15,6 +17,11 @@ Naming/MethodName:
   Exclude:
     - lib/loqate/result.rb
 
+# ----------------------- RSpec -----------------------
+
+RSpec/ExampleLength:
+  Enabled: false
+
 # ----------------------- Style -----------------------
 
 Style/FrozenStringLiteralComment:

data/.yardstick.yml

@@ -121,8 +121,19 @@ rules:
       - Loqate::Gateway#bank
       - Loqate::Gateway#config
       - Loqate::Gateway#email
+      - Loqate::Gateway#geocoding
       - Loqate::Gateway#initialize
       - Loqate::Gateway#phone
+      - Loqate::Geocoding::Gateway#initialize
+      - Loqate::Geocoding::Direction#segment_number
+      - Loqate::Geocoding::Direction#step_number
+      - Loqate::Geocoding::Direction#action
+      - Loqate::Geocoding::Direction#description
+      - Loqate::Geocoding::Direction#road
+      - Loqate::Geocoding::Direction#step_time
+      - Loqate::Geocoding::Direction#step_distance
+      - Loqate::Geocoding::Direction#total_time
+      - Loqate::Geocoding::Direction#total_distance
       - Loqate::Phone::Gateway#initialize
       - Loqate::Phone::PhoneNumberValidation#country_prefix
       - Loqate::Phone::PhoneNumberValidation#is_valid
@@ -179,6 +190,11 @@ rules:
       - Loqate::Email::Gateway#mapper
       - Loqate::Error#attributes
       - Loqate::Gateway#client
+      - 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::Phone::Gateway#build_error_from
       - Loqate::Phone::Gateway#build_phone_validation_from
       - Loqate::Phone::Gateway#client
@@ -228,6 +244,11 @@ rules:
       - Loqate::Email::Gateway#mapper
       - Loqate::Error#attributes
       - Loqate::Gateway#client
+      - 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::Phone::Gateway#build_error_from
       - Loqate::Phone::Gateway#build_phone_validation_from
       - Loqate::Phone::Gateway#client

data/CHANGELOG.md

@@ -4,6 +4,10 @@ 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.8.0] - 2018-12-10
+### Added
+- Distance service of the Geocoding API
+
 ## [0.7.0] - 2018-12-03
 ### Changed
 - Moved the `Address`, `Email` and `Phone` APIs into their own namespaces
@@ -57,6 +61,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Initial core functionality
 - Codebase maintenance tools
 
+[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
 [0.5.0]: https://github.com/wilsonsilva/loqate/compare/v0.4.0...v0.5.0

data/README.md

@@ -19,6 +19,8 @@ Client to address verification, postcode lookup, & data quality services from Lo
   - [Address API](#address-api)
     - [Finding addresses](#finding-addresses)
     - [Retrieving the details of an address](#retrieving-the-details-of-an-address)
+  - [Geocoding API](#geocoding-api)
+    - [Finding directions](#finding-directions)
   - [Phone API](#phone-api)
     - [Validating a phone number](#validating-a-phone-number)
   - [Email API](#phone-api)
@@ -127,6 +129,19 @@ address.line1       # '148 Warner Road'
 address.postal_code # 'E17 7EA'
 ```
 
+### Geocoding API
+
+The Geocoding API exposes endpoints to perform geocoding operations.
+
+#### Finding directions
+```ruby
+directions = gateway.geocoding.directions!(
+  start: [51.5079532, -0.1266053],
+  finish: [51.5078677, -0.1266825]
+)
+directions.first.description # => 'Leave from Strand/A4'
+```
+
 ### Phone API
 
 The Phone API consists of a single API request:

data/ROADMAP.md

@@ -5,6 +5,7 @@
 - [x] HTTP Client
 - [x] Core Client
 - [ ] Logging
+- [ ] Instrumentation
 - [x] Domain error handling
 - [x] Configuration
 - [x] Unwrap request results

data/lib/loqate/gateway.rb

@@ -1,6 +1,7 @@
 require 'loqate/address/gateway'
 require 'loqate/bank/gateway'
 require 'loqate/email/gateway'
+require 'loqate/geocoding/gateway'
 require 'loqate/phone/gateway'
 
 module Loqate
@@ -34,6 +35,14 @@ module Loqate
       @address ||= Address::Gateway.new(client)
     end
 
+    # Gateway to the Geocoding APIs.
+    #
+    # @return [Geocoding::Gateway] An instance of a geocoding gateway.
+    #
+    def geocoding
+      @geocoding ||= Geocoding::Gateway.new(client)
+    end
+
     # Gateway to the Phone number API.
     #
     # @return [Phone::Gateway] An instance of a phone gateway.

data/lib/loqate/geocoding/direction.rb

@@ -0,0 +1,60 @@
+module Loqate
+  module Geocoding
+    # A result from the directions API call.
+    class Direction < Dry::Struct::Value
+      # A zero based counter indicating the row number.
+      #
+      # @return [Integer]
+      #
+      attribute :segment_number, Types::Strict::Integer
+
+      # A zero based counter indicating the row number.
+      #
+      # @return [Integer]
+      #
+      attribute :step_number, Types::Strict::Integer
+
+      # The type of routing instruction.
+      #
+      # @return [String]
+      #
+      attribute :action, Types::Strict::String
+
+      # Textual description of the routing instruction.
+      #
+      # @return [String]
+      #
+      attribute :description, Types::Strict::String
+
+      # The name of the road to turn onto.
+      #
+      # @return [String]
+      #
+      attribute :road, Types::Strict::String
+
+      # The time in seconds for this part of the route.
+      #
+      # @return [Integer]
+      #
+      attribute :step_time, Types::Strict::Integer
+
+      # The distance in metres for this part of the route.
+      #
+      # @return [Integer]
+      #
+      attribute :step_distance, Types::Strict::Integer
+
+      # The total time in seconds for the route.
+      #
+      # @return [Integer]
+      #
+      attribute :total_time, Types::Strict::Integer
+
+      # The total distance in metres for the route.
+      #
+      # @return [Integer]
+      #
+      attribute :total_distance, Types::Strict::Integer
+    end
+  end
+end

data/lib/loqate/geocoding/gateway.rb

@@ -0,0 +1,106 @@
+require 'loqate/client'
+require 'loqate/result'
+require 'loqate/geocoding/direction'
+require 'loqate/mappers/error_mapper'
+require 'loqate/mappers/generic_mapper'
+
+module Loqate
+  module Geocoding
+    # Retrieves
+    class Gateway
+      DIRECTIONS_ENDPOINT = '/DistancesAndDirections/Interactive/Directions/v2.00/json3.ws'.freeze
+
+      include Result::Mixin
+
+      # Creates a geocoding gateway.
+      #
+      # @param [Client] client The client responsible for the HTTP interactions
+      #
+      def initialize(client)
+        @client       = client
+        @mapper       = Mappers::GenericMapper.new
+        @error_mapper = Mappers::ErrorMapper.new
+      end
+
+      # Returns the directions between two or more points.
+      #
+      # @param [Hash] options The options to find directions.
+      # @option options [String|Array<String>] :start The coordinates (latitude, longitude or easting, northing) of
+      #   the start of the route. A postcode is also valid.
+      # @option options [String|Array<String>] :finish The coordinates (latitude, longitude or easting, northing) of
+      #   the finish of the route. A postcode is also valid.
+      # @option options [String|Array<String>] :way_points The coordinates (latitude, longitude or easting, northing)
+      #   of any waypoints. Postcodes are also valid.
+      # @option options [String] :distance_type Specifies how the distances between the stores are calculated. It can
+      #   either be 'Fastest' or 'Shortest'.
+      # @option options [String] :start_day The day of the week the route is to start on. Provide this parameter
+      #   only if you wish to utilise superior 'Speed Profiles' historic traffic speed data over time for avoiding
+      #   rush hours and such.
+      # @option options [String] :start_time The time of day the route is to start on, measured in whole minutes
+      #   from midnight. (E.g. 8:30am is entered as 510.) Provide this parameter only if you wish to utilise
+      #   superior 'Speed Profiles' historic traffic speed data over time for avoiding rush hours and such.
+      #
+      # @example Finding directions using latitude and longitude coordinates
+      #   directions = geocoding_gateway.directions(
+      #     start: ['51.5211057', '-0.0989496'],
+      #     finish: ['51.5213087', '-0.0981853']
+      #   )
+      #
+      # @example Finding directions using easting and northing coordinates
+      #   directions = geocoding_gateway.directions(
+      #     start: [381600, 259400],
+      #     finish: [380600, 258400],
+      #   )
+      #
+      # @example Finding directions using postcodes
+      #   directions = geocoding_gateway.directions(
+      #     start: 'EC1A 4JA',
+      #     finish: 'EC1A 4ER'
+      #   )
+      #
+      # @example Finding directions using waypoints
+      #   directions = geocoding_gateway.directions(
+      #     start: 'EC1A 4JA',
+      #     finish: 'EC1A 4ER',
+      #     way_points: ['EC1A 4JQ']
+      #   )
+      #
+      # @example Finding directions in a given time
+      #   directions = geocoding_gateway.directions(
+      #     start: ['51.5211057', '-0.0989496'],
+      #     finish: ['51.5213087', '-0.0981853']
+      #     start_day: 'Monday',
+      #     start_time: 510
+      #   )
+      #
+      # @return [Result] A result wrapping a list of directions.
+      #
+      def directions(options)
+        %i[start finish way_points].each do |key|
+          options[key] = options[key].join(',') if options[key].respond_to?(:join)
+        end
+
+        response = client.get(DIRECTIONS_ENDPOINT, options)
+
+        response.errors? && build_error_from(response.items.first) || build_directions_from(response.items)
+      end
+
+      private
+
+      # @api private
+      attr_reader :client, :mapper, :error_mapper
+
+      # @api private
+      def build_error_from(item)
+        error = error_mapper.map_one(item)
+        Failure(error)
+      end
+
+      # @api private
+      def build_directions_from(item)
+        direction = mapper.map(item, Direction)
+        Success(direction)
+      end
+    end
+  end
+end

data/lib/loqate/version.rb

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

metadata

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