Class: Loqate::Geocoding::Gateway

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

Overview

Performs API requests to the geocoding services.

Constant Summary collapse

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

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 a geocoding gateway.

Parameters:

  • client (Client) —

    The client responsible for the HTTP interactions



25
26
27
28
29
 
# File 'lib/loqate/geocoding/gateway.rb', line 25

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

Instance Method Details

#directions(options) ⇒ Result

Returns the directions between two or more points.

Examples:

Finding directions using latitude and longitude coordinates

directions = geocoding_gateway.directions(
  start: ['51.5211057', '-0.0989496'],
  finish: ['51.5213087', '-0.0981853']
)

Finding directions using easting and northing coordinates

directions = geocoding_gateway.directions(
  start: [381600, 259400],
  finish: [380600, 258400],
)

Finding directions using postcodes

directions = geocoding_gateway.directions(
  start: 'EC1A 4JA',
  finish: 'EC1A 4ER'
)

Finding directions using waypoints

directions = geocoding_gateway.directions(
  start: 'EC1A 4JA',
  finish: 'EC1A 4ER',
  way_points: ['EC1A 4JQ']
)

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
)

Parameters:

  • options (Hash) —

    The options to find directions.

Options Hash (options):

  • :start (String|Array<String>) —

    The coordinates (latitude, longitude or easting, northing) of the start of the route. A postcode is also valid.

  • :finish (String|Array<String>) —

    The coordinates (latitude, longitude or easting, northing) of the finish of the route. A postcode is also valid.

  • :way_points (String|Array<String>) —

    The coordinates (latitude, longitude or easting, northing) of any waypoints. Postcodes are also valid.

  • :distance_type (String) —

    Specifies how the distances between the stores are calculated. It can either be ‘Fastest’ or ‘Shortest’.

  • :start_day (String) —

    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.

  • :start_time (String) —

    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.

Returns:

  • (Result) —

    A result wrapping a list of directions.



84
85
86
87
88
89
90
91
92
 
# File 'lib/loqate/geocoding/gateway.rb', line 84

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

#directions!(options) ⇒ Array<Direction>

Returns the directions between two or more points.

Returns:

  • (Array<Direction>) —

    A list of directions.

Raises:

  • (Error) —

    If the result is not a success

See Also:

  • Loqage::Geocoding::Geocoding#directions


102
103
104
 
# File 'lib/loqate/geocoding/gateway.rb', line 102

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

#geocode(options) ⇒ Result

Returns the WGS84 latitude and longitude for the given location. Supports most international locations.

Examples:

result = geocoding_gateway.geocode(country: 'US', location: '90210')

Parameters:

  • options (Hash) —

    The options to geocode.

Options Hash (options):

  • :country (String) —

    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.

  • :location (String) —

    The location to geocode. This can be a postal code or place name.

Returns:

  • (Result) —

    A result wrapping a location.



118
119
120
121
122
 
# File 'lib/loqate/geocoding/gateway.rb', line 118

def geocode(options)
  response = client.get(GEOCODE_ENDPOINT, options)

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

#geocode!(options) ⇒ Location

Returns the WGS84 latitude and longitude for the given location. Supports most international locations.

Returns:

Raises:

  • (Error) —

    If the result is not a success

See Also:

  • Loqate::Geocoding::Geocoding#geocode


132
133
134
 
# File 'lib/loqate/geocoding/gateway.rb', line 132

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

#position_to_country(options) ⇒ Result

Returns the country based on the WGS84 latitude and longitude supplied. No result is returned if the coordinates are in international waters.

Examples:

result = geocoding_gateway.position_to_country(latitude: 52.1321, longitude: -2.1001)

Parameters:

  • options (Hash) —

    The coordinates of the position to search against.

Options Hash (options):

  • :latitude (Float) —

    The latitude of the position to search against.

  • :longitude (Float) —

    The longitude of the position to search against.

Returns:

  • (Result) —

    A result wrapping a country or wrapping nil if no country is found.



148
149
150
151
152
153
154
 
# File 'lib/loqate/geocoding/gateway.rb', line 148

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

#position_to_country!(options) ⇒ Country

Returns the country based on the WGS84 latitude and longitude supplied. No result is returned if the coordinates are in international waters.

Returns:

Raises:

  • (Error) —

    If the result is not a success

See Also:

  • Loqate::Geocoding::Geocoding#position_to_country


165
166
167
 
# File 'lib/loqate/geocoding/gateway.rb', line 165

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

#retrieve_nearest_places(options) ⇒ Result

Calculates the nearest places of interest of a given category to a given location.

Examples:

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
)

Retrieving the nearest places around a postcode

result = geocoding_gateway.retrieve_nearest_places(
  centre_point: 'NW10 6RB',
  maximum_items: 5,
  maximum_radius: 10
)

Parameters:

  • options (Hash) —

    The coordinates of the position to search against.

Options Hash (options):

  • :country (String) —

    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.

  • :centre_point (String) —

    A postcode or coordinates (latitude, longitude) of the centre of the search. Can also be a place name (corresponding country code must be provided).

  • :maximum_items (Integer) —

    The maximum number of items to return. If 0, all items are returned.

  • :maximum_radius (Float) —

    The maximum search distance in KM between the origin and a point of interest. If blank or 0, all items are returned.

  • :filter_options (Float) —

    The type of filter to apply where the search returns a list of towns.

Returns:

  • (Result) —

    A result wrapping a list of places.



197
198
199
200
201
 
# File 'lib/loqate/geocoding/gateway.rb', line 197

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

#retrieve_nearest_places!(options) ⇒ Array<Place>

Calculates the nearest places of interest of a given category to a given location.

Returns:

  • (Array<Place>) —

    A list of places.

Raises:

  • (Error) —

    If the result is not a success

See Also:

  • Loqate::Geocoding::Geocoding#retrieve_nearest_places


211
212
213
 
# File 'lib/loqate/geocoding/gateway.rb', line 211

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