loqate 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18b2de06a287567be0f1ccce8dc27723ed9ff5a786ffa4d2dbfa365be936bb60
-  data.tar.gz: cc2ca8285a696744a06967f66809afc2bf045a88a4d47b507f0b5ab70bb2eb30
+  metadata.gz: c32e6dafdb5718d79353dc403a5be5b67449fee4a9e1e5e0dfe1449d6d5989b9
+  data.tar.gz: 8a5d0e9b5573f40554e9faba5b11718b6824e71d9da3f5531b951b1fbec988c8
 SHA512:
-  metadata.gz: 8de9e9a790722ce940c8859ea30176f09685daf9904c49ecd432fa3aad0b9e94a1f7120f0fb55886c7c1b18510ee15f8ed156d100bdf51b0fd3c6afb0c7c5d5b
-  data.tar.gz: 7c36a6013d07df700d6cc42a16746d8207a4a95ded5aae5dff3a33bf3275bfbd5a594fd9f3d50451afc381d1867baa24a5bc928733e47562f31a4e2638eaf970
+  metadata.gz: e526913afe9f0cbd20e2e1da861bef024cde0f0c98628a40705a4e1387019d9edce0c8f4e573bc398b8b04f15788dae4c783044ec5f3ec4084fe6d7bc7ed42e8
+  data.tar.gz: ae6f0884d34bb364c6b4eca12ae12a04471a8b00115d3bb469a5ade95dc8057b87afc6c820aeefba63d741e65edd2f47c6984cbc926b97c38ea220ae1252205a

data/.yardstick.yml

@@ -13,263 +13,12 @@ rules:
     enabled: true
     exclude: []
   ExampleTag:
-    enabled: true
+    enabled: false
     exclude:
-      - Loqate::Address::Address#==
-      - Loqate::Address::Address#attributes
-      - Loqate::Address::Address#description
-      - Loqate::Address::Address#highlight
-      - Loqate::Address::Address#id
-      - Loqate::Address::Address#initialize
-      - Loqate::Address::Address#text
-      - Loqate::Address::Address#type
-      - Loqate::Address::Gateway#initialize
-      - Loqate::APIResult#errors?
-      - Loqate::APIResult#initialize
-      - Loqate::APIResult#items
-      - Loqate::Bank::AccountValidation#bank
-      - Loqate::Bank::AccountValidation#bank_bic
-      - Loqate::Bank::AccountValidation#branch
-      - Loqate::Bank::AccountValidation#branch_bic
-      - Loqate::Bank::AccountValidation#chaps_supported
-      - Loqate::Bank::AccountValidation#contact_address_line1
-      - Loqate::Bank::AccountValidation#contact_address_line2
-      - Loqate::Bank::AccountValidation#contact_fax
-      - Loqate::Bank::AccountValidation#contact_phone
-      - Loqate::Bank::AccountValidation#contact_post_town
-      - Loqate::Bank::AccountValidation#contact_postcode
-      - Loqate::Bank::AccountValidation#correct?
-      - Loqate::Bank::AccountValidation#corrected_account_number
-      - Loqate::Bank::AccountValidation#corrected_sort_code
-      - Loqate::Bank::AccountValidation#faster_payments_supported
-      - Loqate::Bank::AccountValidation#iban
-      - Loqate::Bank::AccountValidation#is_correct
-      - Loqate::Bank::AccountValidation#is_direct_debit_capable
-      - Loqate::Bank::AccountValidation#status_information
-      - Loqate::Bank::BatchAccountValidation#bank
-      - Loqate::Bank::BatchAccountValidation#bank_bic
-      - Loqate::Bank::BatchAccountValidation#branch
-      - Loqate::Bank::BatchAccountValidation#branch_bic
-      - Loqate::Bank::BatchAccountValidation#contact_address_line1
-      - Loqate::Bank::BatchAccountValidation#contact_address_line2
-      - Loqate::Bank::BatchAccountValidation#contact_fax
-      - Loqate::Bank::BatchAccountValidation#contact_phone
-      - Loqate::Bank::BatchAccountValidation#contact_post_town
-      - Loqate::Bank::BatchAccountValidation#contact_postcode
-      - Loqate::Bank::BatchAccountValidation#correct?
-      - Loqate::Bank::BatchAccountValidation#corrected_account_number
-      - Loqate::Bank::BatchAccountValidation#corrected_sort_code
-      - Loqate::Bank::BatchAccountValidation#iban
-      - Loqate::Bank::BatchAccountValidation#is_correct
-      - Loqate::Bank::BatchAccountValidation#is_direct_debit_capable
-      - Loqate::Bank::BatchAccountValidation#original_account_number
-      - Loqate::Bank::BatchAccountValidation#original_sort_code
-      - Loqate::Bank::BatchAccountValidation#status_information
-      - Loqate::Bank::Branch#bank
-      - Loqate::Bank::Branch#bank_bic
-      - Loqate::Bank::Branch#branch
-      - Loqate::Bank::Branch#branch_bic
-      - Loqate::Bank::Branch#chaps_supported
-      - Loqate::Bank::Branch#contact_address_line1
-      - Loqate::Bank::Branch#contact_address_line2
-      - Loqate::Bank::Branch#contact_fax
-      - Loqate::Bank::Branch#contact_phone
-      - Loqate::Bank::Branch#contact_post_town
-      - Loqate::Bank::Branch#contact_postcode
-      - Loqate::Bank::Branch#faster_payments_supported
-      - Loqate::Bank::CardValidation#card_number
-      - 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
-      - Loqate::Email::BatchEmailValidation#domain
-      - Loqate::Email::BatchEmailValidation#email_address
-      - Loqate::Email::BatchEmailValidation#invalid?
-      - Loqate::Email::BatchEmailValidation#is_disposible
-      - Loqate::Email::BatchEmailValidation#is_system_mailbox
-      - Loqate::Email::BatchEmailValidation#status
-      - Loqate::Email::BatchEmailValidation#unknown?
-      - Loqate::Email::BatchEmailValidation#unverified?
-      - Loqate::Email::BatchEmailValidation#valid?
-      - Loqate::Configuration#api_key
-      - Loqate::Configuration#host
-      - Loqate::Configuration#initialize
-      - Loqate::Configuration#language
-      - Loqate::Address::DetailedAddress#==
-      - Loqate::Address::DetailedAddress#initialize
-      - Loqate::Email::Gateway#initialize
-      - Loqate::Email::EmailValidation#domain
-      - Loqate::Email::EmailValidation#duration
-      - Loqate::Email::EmailValidation#email_address
-      - Loqate::Email::EmailValidation#invalid?
-      - Loqate::Email::EmailValidation#is_complainer_or_fraud_risk
-      - Loqate::Email::EmailValidation#is_disposable_or_temporary
-      - Loqate::Email::EmailValidation#response_code
-      - Loqate::Email::EmailValidation#response_message
-      - Loqate::Email::EmailValidation#timeout?
-      - Loqate::Email::EmailValidation#user_account
-      - Loqate::Email::EmailValidation#valid?
-      - Loqate::Email::EmailValidation#valid_domain?
-      - Loqate::Error#cause
-      - Loqate::Error#description
-      - Loqate::Error#id
-      - Loqate::Error#initialize
-      - Loqate::Error#resolution
-      - Loqate::Gateway#address
-      - Loqate::Gateway#bank
-      - Loqate::Gateway#config
-      - Loqate::Gateway#email
-      - 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
-      - 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
-      - Loqate::Phone::PhoneNumberValidation#national_format
-      - Loqate::Phone::PhoneNumberValidation#network_code
-      - Loqate::Phone::PhoneNumberValidation#network_country
-      - Loqate::Phone::PhoneNumberValidation#network_name
-      - Loqate::Phone::PhoneNumberValidation#number_type
-      - Loqate::Phone::PhoneNumberValidation#phone_number
-      - Loqate::Phone::PhoneNumberValidation#request_processed
-      - Loqate::Phone::PhoneNumberValidation#valid?
-      - Loqate::Result#code
-      - Loqate::Result#value
-      - Loqate::Result::Failure#error
-      - Loqate::Result::Failure#failure?
-      - Loqate::Result::Failure#success?
-      - Loqate::Result::Success#failure?
-      - Loqate::Result::Success#success?
   ReturnTag:
-    enabled: true
-    exclude:
-      - Loqate::Address::Address#==
-      - Loqate::Address::Address#attributes
-      - Loqate::Address::Address#description
-      - Loqate::Address::Address#highlight
-      - Loqate::Address::Address#id
-      - Loqate::Address::Address#text
-      - Loqate::Address::Address#type
-      - Loqate::Address::Gateway#build_addresses_from
-      - Loqate::Address::Gateway#build_detailed_address_from
-      - Loqate::Address::Gateway#build_error_from
-      - Loqate::Address::Gateway#client
-      - Loqate::Address::Gateway#error_mapper
-      - Loqate::Address::Gateway#mapper
-      - Loqate::Bank::Gateway#build_account_validation_from
-      - Loqate::Bank::Gateway#build_account_validations_from
-      - Loqate::Bank::Gateway#build_branch_from
-      - Loqate::Bank::Gateway#build_card_validation_from
-      - Loqate::Bank::Gateway#build_error_from
-      - Loqate::Bank::Gateway#build_int_acc_validation_from
-      - Loqate::Bank::Gateway#client
-      - Loqate::Bank::Gateway#error_mapper
-      - Loqate::Bank::Gateway#mapper
-      - Loqate::Client#authenticate_params
-      - Loqate::Client#configuration
-      - Loqate::Client#format_params
-      - Loqate::Client#headers
-      - Loqate::Address::DetailedAddress#==
-      - Loqate::Email::Gateway#build_email_validation_from
-      - Loqate::Email::Gateway#build_email_validations_from
-      - Loqate::Email::Gateway#build_error_from
-      - Loqate::Email::Gateway#client
-      - Loqate::Email::Gateway#error_mapper
-      - 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
-      - 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
-      - Loqate::Phone::Gateway#error_mapper
-      - Loqate::Phone::Gateway#mapper
-      - Loqate::Result::Failure#error
-      - Loqate::Util#camelize
-      - Loqate::Util#underscore
-      - Loqate::Util.camelize
-      - Loqate::Util.underscore
+    enabled: false
   Summary::Presence:
-    enabled: true
-    exclude:
-      - Loqate::Address::Address#==
-      - Loqate::Address::Address#attributes
-      - Loqate::Address::Address#description
-      - Loqate::Address::Address#highlight
-      - Loqate::Address::Address#id
-      - Loqate::Address::Address#text
-      - Loqate::Address::Address#type
-      - Loqate::Address::Gateway#build_addresses_from
-      - Loqate::Address::Gateway#build_detailed_address_from
-      - Loqate::Address::Gateway#build_error_from
-      - Loqate::Address::Gateway#client
-      - Loqate::Address::Gateway#error_mapper
-      - Loqate::Address::Gateway#mapper
-      - Loqate::Bank::Gateway#build_account_validation_from
-      - Loqate::Bank::Gateway#build_account_validations_from
-      - Loqate::Bank::Gateway#build_branch_from
-      - Loqate::Bank::Gateway#build_card_validation_from
-      - Loqate::Bank::Gateway#build_error_from
-      - Loqate::Bank::Gateway#build_int_acc_validation_from
-      - Loqate::Bank::Gateway#client
-      - Loqate::Bank::Gateway#error_mapper
-      - Loqate::Bank::Gateway#mapper
-      - Loqate::Client#authenticate_params
-      - Loqate::Client#configuration
-      - Loqate::Client#format_params
-      - Loqate::Client#headers
-      - Loqate::Address::DetailedAddress#==
-      - Loqate::Address::DetailedAddress#initialize
-      - Loqate::Email::Gateway#build_email_validation_from
-      - Loqate::Email::Gateway#build_email_validations_from
-      - Loqate::Email::Gateway#build_error_from
-      - Loqate::Email::Gateway#client
-      - Loqate::Email::Gateway#error_mapper
-      - 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
-      - Loqate::Phone::Gateway#error_mapper
-      - Loqate::Phone::Gateway#mapper
-      - Loqate::Result::Failure#error
+    enabled: false
   Summary::Length:
     enabled: false
   Summary::Delimiter:

data/CHANGELOG.md

@@ -4,6 +4,13 @@ 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.10.0] - 2018-12-12
+### Added
+- A service to find the nearest places around a given coordinate
+
+### Changed
+- Disabled the Yardstick rules `ExampleTag`, `ReturnTag` and `Summary::Presence`.
+
 ## [0.9.0] - 2018-12-11
 ### Added
 - Geocoding service of the Geocoding API
@@ -66,6 +73,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Initial core functionality
 - Codebase maintenance tools
 
+[0.10.0]: https://github.com/wilsonsilva/loqate/compare/v0.9.0...v0.10.0
 [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

data/README.md

@@ -23,6 +23,7 @@ Client to address verification, postcode lookup, & data quality services from Lo
     - [Finding directions](#finding-directions)
     - [Geocoding a location](#geocoding-a-location)
     - [Finding a country based on coordinates](#finding-a-country-based-on-coordinates)
+    - [Finding nearest places](#finding-nearest-places)
   - [Phone API](#phone-api)
     - [Validating a phone number](#validating-a-phone-number)
   - [Email API](#phone-api)
@@ -156,6 +157,17 @@ country = gateway.geocoding.position_to_country!(latitude: 52.1321, longitude: -
 country.country_name # => 'United Kingdom'
 ```
 
+#### Finding nearest places
+```ruby
+nearest_places = gateway.geocoding.retrieve_nearest_places!(
+  centre_point: [-33.440113067627, 149.578567504883],
+  maximum_items: 5,
+  maximum_radius: 10,
+  filter_options: 'HideVillages'
+)
+nearest_places.first.location # => 'South Bathurst, NSW, Australia'
+```
+
 ### Phone API
 
 The Phone API consists of a single API request:

data/lib/loqate/geocoding/gateway.rb

@@ -3,6 +3,7 @@ require 'loqate/result'
 require 'loqate/geocoding/country'
 require 'loqate/geocoding/direction'
 require 'loqate/geocoding/location'
+require 'loqate/geocoding/place'
 require 'loqate/mappers/error_mapper'
 require 'loqate/mappers/generic_mapper'
 
@@ -13,6 +14,7 @@ module Loqate
       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
+      NEAREST_PLACES_ENDPOINT = '/Geocoding/International/RetrieveNearestPlaces/v1.00/json3.ws'.freeze
 
       include Result::Mixin
 
@@ -141,7 +143,7 @@ module Loqate
       # @example
       #   result = geocoding_gateway.position_to_country(latitude: 52.1321, longitude: -2.1001)
       #
-      # @return [Result|nil] A result wrapping a country.
+      # @return [Result] A result wrapping a country or wrapping nil if no country is found.
       #
       def position_to_country(options)
         response = client.get(POSITION_TO_COUNTRY_ENDPOINT, options)
@@ -164,6 +166,52 @@ module Loqate
         unwrap_result_or_raise { position_to_country(options) }
       end
 
+      # Calculates the nearest places of interest of a given category to a given location.
+      #
+      # @param [Hash] options The coordinates of the position to search against.
+      # @option options [String] :country The ISO3 character code for the country to search in. This parameter is
+      #   optional, but if you wish to use a place for the centre point the country code must be provided.
+      # @option options [String] :centre_point A postcode or coordinates (latitude, longitude) of the centre of the
+      #   search. Can also be a place name (corresponding country code must be provided).
+      # @option options [Integer] :maximum_items The maximum number of items to return. If 0, all items are returned.
+      # @option options [Float] :maximum_radius The maximum search distance in KM between the origin and a point of
+      #   interest. If blank or 0, all items are returned.
+      # @option options [Float] :filter_options The type of filter to apply where the search returns a list of towns.
+      #
+      # @example Retrieving the nearest places around a coordinate
+      #   result = geocoding_gateway.retrieve_nearest_places(
+      #     centre_point: [-33.440113067627, 149.578567504883],
+      #     maximum_items: 5,
+      #     maximum_radius: 10
+      #   )
+      #
+      # @example Retrieving the nearest places around a postcode
+      #   result = geocoding_gateway.retrieve_nearest_places(
+      #     centre_point: 'NW10 6RB',
+      #     maximum_items: 5,
+      #     maximum_radius: 10
+      #   )
+      #
+      # @return [Result] A result wrapping a list of places.
+      #
+      def retrieve_nearest_places(options)
+        response = client.get(NEAREST_PLACES_ENDPOINT, options)
+
+        response.errors? && build_error_from(response.items.first) || build_places_from(response.items)
+      end
+
+      # Calculates the nearest places of interest of a given category to a given location.
+      #
+      # @raise [Error] If the result is not a success
+      #
+      # @see Loqate::Geocoding::Geocoding#retrieve_nearest_places
+      #
+      # @return [Array<Place>] A list of places.
+      #
+      def retrieve_nearest_places!(options)
+        unwrap_result_or_raise { retrieve_nearest_places(options) }
+      end
+
       private
 
       # @api private
@@ -192,6 +240,12 @@ module Loqate
         country = mapper.map_one(item, Country)
         Success(country)
       end
+
+      # @api private
+      def build_places_from(items)
+        places = mapper.map(items, Place)
+        Success(places)
+      end
     end
   end
 end

data/lib/loqate/geocoding/place.rb

@@ -0,0 +1,30 @@
+module Loqate
+  module Geocoding
+    # A result from the API call to find the nearest places.
+    class Place < Dry::Struct::Value
+      # The postcode that is nearest to the given location.
+      #
+      # @return [String]
+      #
+      attribute :location, Types::Strict::String
+
+      # The distance in KM from the CentrePoint to this record.
+      #
+      # @return [Float]
+      #
+      attribute :distance, Types::Coercible::Float
+
+      # The WGS84 latitude coordinate of the location.
+      #
+      # @return [Float]
+      #
+      attribute :latitude, Types::Coercible::Float
+
+      # The WGS84 longitude coordinate of the location.
+      #
+      # @return [Float]
+      #
+      attribute :longitude, Types::Coercible::Float
+    end
+  end
+end

data/lib/loqate/version.rb

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

metadata

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