address_gateway.rb in loqate-0.3.0

- old
+ new
@@ -44,58 +44,104 @@
     #   code e.g. (en, fr, en-gb, en-us etc).
     #
     # @example Retrieving an address in the UK
     #   address = address_gateway.find(countries: 'GB', text: 'Scrubs Lane')
     #
-    # @return [Array<Address>] A list of addresses
+    # @return [Result] A result wrapping a list of addresses
     #
     def find(options)
       response = client.get(FIND_ENDPOINT, options)
 
-      response.errors? && build_errors_from(response.items) || build_address_from(response.items)
+      response.errors? && build_error_from(response.items.first) || build_addresses_from(response.items)
     end
 
     # Returns the full address details based on the id.
     #
     # @param [Hash] options The options to retrieve the address.
     # @option options [String] :id The Id from a Find method to retrieve the details for.
-    # @option options [String] :field_1_format a.
-    # @option options [String] :field_2_format b.
-    # @option options [String] :field_3_format c.
-    # @option options [String] :field_4_format d.
-    # @option options [String] :field_5_format e.
+    # @option options [String] :field_1_format Format of a custom address field.
+    # @option options [String] :field_2_format Format of a custom address field.
+    # @option options [String] :field_3_format Format of a custom address field.
+    # @option options [String] :field_4_format Format of a custom address field.
+    # @option options [String] :field_5_format Format of a custom address field.
     #
     # @example Retrieving the details of an address
     #   detailed_address = gateway.retrieve(id: 'GB|RM|ENG|6RB-NW10')
     #
-    # @return [Array<DetailedAddress>] A list of detailed addresses
+    # @return [Result] A result wrapping a detailed address
     #
     def retrieve(options)
       response = client.get(RETRIEVE_ENDPOINT, options)
 
-      response.errors? && build_errors_from(response.items) || build_detailed_addresses_from(response.items)
+      response.errors? && build_error_from(response.items.first) || build_detailed_address_from(response.items.first)
     end
 
+    # Find addresses and places.
+    #
+    # @param [Hash] options The options to find an address or a list of addresses.
+    # @option options [String] :text The search text to find. Ideally a postcode or the start of the address.
+    # @option options [String] countries A comma separated list of ISO 2 or 3 character country codes to limit
+    #   the search within.
+    # @option options [String] origin A starting location for the search. This can be the name or ISO 2 or 3 character
+    #   code of a country, WGS84 coordinates (comma separated) or IP address to search from.
+    # @option options [String] container A container for the search. This should only be another Id previously returned
+    #   from this service when the Type of the result was not 'Address'.
+    # @option options [Integer] limit The maximum number of results to return.
+    # @option options [String] language The preferred language for results. This should be a 2 or 4 character language
+    #   code e.g. (en, fr, en-gb, en-us etc).
+    #
+    # @example Retrieving addresses in the UK
+    #   addresses = address_gateway.find!(countries: 'GB', text: 'Scrubs Lane')
+    #
+    # @raise [Error] If the result is not a success
+    #
+    # @return [Array<Address>] A list of addresses
+    #
+    def find!(options)
+      unwrap_result_or_raise { find(options) }
+    end
+
+    # Returns the full address details based on the id.
+    #
+    # @param [Hash] options The options to retrieve the address.
+    # @option options [String] :id The Id from a Find method to retrieve the details for.
+    # @option options [String] :field_1_format Format of a custom address field.
+    # @option options [String] :field_2_format Format of a custom address field.
+    # @option options [String] :field_3_format Format of a custom address field.
+    # @option options [String] :field_4_format Format of a custom address field.
+    # @option options [String] :field_5_format Format of a custom address field.
+    #
+    # @example Retrieving the details of an address
+    #   detailed_address = gateway.retrieve!(id: 'GB|RM|ENG|6RB-NW10')
+    #
+    # @raise [Error] If the result is not a success
+    #
+    # @return [DetailedAddress] A detailed address
+    #
+    def retrieve!(options)
+      unwrap_result_or_raise { retrieve(options) }
+    end
+
     private
 
     # @api private
     attr_reader :client, :mapper, :error_mapper
 
     # @api private
-    def build_errors_from(items)
-      errors = error_mapper.map(items)
-      Failure(errors)
+    def build_error_from(item)
+      error = error_mapper.map_one(item)
+      Failure(error)
     end
 
     # @api private
-    def build_address_from(items)
+    def build_addresses_from(items)
       address = mapper.map(items, Address)
       Success(address)
     end
 
     # @api private
-    def build_detailed_addresses_from(items)
-      detailed_address = mapper.map(items, DetailedAddress)
+    def build_detailed_address_from(item)
+      detailed_address = mapper.map_one(item, DetailedAddress)
       Success(detailed_address)
     end
   end
 end