Class: Loqate::Address::Gateway

Inherits:
Object
  • Object
show all
Includes:
Result::Mixin
Defined in:
lib/loqate/address/gateway.rb

Overview

Address Verification consists of two main API requests: a Find request is used to narrow down a possible list of addresses; and a Retrieve request is used to retrieve a fully formatted address.

A typical address search is made up of a series of Find requests, followed by a Retrieve based on the user selection. Choose a service below to find out how to use each request.

Constant Summary collapse

FIND_ENDPOINT = 
'/Capture/Interactive/Find/v1.00/json3.ws'.freeze
RETRIEVE_ENDPOINT = 
'/Capture/Interactive/Retrieve/v1.00/json3.ws'.freeze

Constants included from Result::Mixin

Result::Mixin::Failure, Result::Mixin::Success

Instance Method Summary collapse

Methods included from Result::Mixin

#Failure, #Success, #unwrap_result_or_raise

Constructor Details

#initialize(client) ⇒ Gateway

Creates an address gateway



27
28
29
30
31
 
# File 'lib/loqate/address/gateway.rb', line 27

def initialize(client)
  @client       = client
  @mapper       = Mappers::GenericMapper.new
  @error_mapper = Mappers::ErrorMapper.new
end

Instance Method Details

#find(options) ⇒ Result

Find addresses and places.

Examples:

Retrieving an address in the UK

address = address_gateway.find(countries: 'GB', text: 'Scrubs Lane')

Options Hash (options):

  • :text (String) —

    The search text to find. Ideally a postcode or the start of the address.

  • countries (String) —

    A comma separated list of ISO 2 or 3 character country codes to limit the search within.

  • origin (String) —

    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.

  • container (String) —

    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’.

  • limit (Integer) —

    The maximum number of results to return.

  • language (String) —

    The preferred language for results. This should be a 2 or 4 character language code e.g. (en, fr, en-gb, en-us etc).



52
53
54
55
56
 
# File 'lib/loqate/address/gateway.rb', line 52

def find(options)
  response = client.get(FIND_ENDPOINT, options)

  response.errors? && build_error_from(response.items.first) || build_addresses_from(response.items)
end

#find!(options) ⇒ Array<Address>

Find addresses and places.

Examples:

Retrieving addresses in the UK

addresses = address_gateway.find!(countries: 'GB', text: 'Scrubs Lane')

Options Hash (options):

  • :text (String) —

    The search text to find. Ideally a postcode or the start of the address.

  • countries (String) —

    A comma separated list of ISO 2 or 3 character country codes to limit the search within.

  • origin (String) —

    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.

  • container (String) —

    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’.

  • limit (Integer) —

    The maximum number of results to return.

  • language (String) —

    The preferred language for results. This should be a 2 or 4 character language code e.g. (en, fr, en-gb, en-us etc).

Raises:

  • (Error) —

    If the result is not a success



100
101
102
 
# File 'lib/loqate/address/gateway.rb', line 100

def find!(options)
  unwrap_result_or_raise { find(options) }
end

#retrieve(options) ⇒ Result

Returns the full address details based on the id.

Examples:

Retrieving the details of an address

detailed_address = gateway.retrieve(id: 'GB|RM|ENG|6RB-NW10')

Options Hash (options):

  • :id (String) —

    The Id from a Find method to retrieve the details for.

  • :field_1_format (String) —

    Format of a custom address field.

  • :field_2_format (String) —

    Format of a custom address field.

  • :field_3_format (String) —

    Format of a custom address field.

  • :field_4_format (String) —

    Format of a custom address field.

  • :field_5_format (String) —

    Format of a custom address field.



73
74
75
76
77
 
# File 'lib/loqate/address/gateway.rb', line 73

def retrieve(options)
  response = client.get(RETRIEVE_ENDPOINT, options)

  response.errors? && build_error_from(response.items.first) || build_detailed_address_from(response.items.first)
end

#retrieve!(options) ⇒ DetailedAddress

Returns the full address details based on the id.

Examples:

Retrieving the details of an address

detailed_address = gateway.retrieve!(id: 'GB|RM|ENG|6RB-NW10')

Options Hash (options):

  • :id (String) —

    The Id from a Find method to retrieve the details for.

  • :field_1_format (String) —

    Format of a custom address field.

  • :field_2_format (String) —

    Format of a custom address field.

  • :field_3_format (String) —

    Format of a custom address field.

  • :field_4_format (String) —

    Format of a custom address field.

  • :field_5_format (String) —

    Format of a custom address field.

Raises:

  • (Error) —

    If the result is not a success



121
122
123
 
# File 'lib/loqate/address/gateway.rb', line 121

def retrieve!(options)
  unwrap_result_or_raise { retrieve(options) }
end