Class: What3Words::API

Inherits:
Object
  • Object
show all
Defined in:
lib/what3words/api.rb

Overview

What3Words v3 API wrapper

Defined Under Namespace

Classes: Error, ResponseError, WordError

Constant Summary collapse

REGEX_3_WORD_ADDRESS = 
/^\p{L}+\.\p{L}+\.\p{L}+$/u.freeze
REGEX_STRICT = 
/^\p{L}{3,}+\.\p{L}{3,}+\.\p{L}{3,}+$/u.freeze
BASE_URL = 
'https://api.what3words.com/v3/'
ENDPOINTS = 
{
  convert_to_coordinates: 'convert-to-coordinates',
  convert_to_3wa: 'convert-to-3wa',
  available_languages: 'available-languages',
  autosuggest: 'autosuggest',
  grid_section: 'grid-section'
}.freeze
WRAPPER_VERSION = 
What3Words::VERSION

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(params) ⇒ API

Returns a new instance of API.



31
32
33
 
# File 'lib/what3words/api.rb', line 31

def initialize(params)
  @key = params.fetch(:key)
end

Instance Attribute Details

#key ⇒ Object (readonly)

Returns the value of attribute key.



35
36
37
 
# File 'lib/what3words/api.rb', line 35

def key
  @key
end

Instance Method Details

#autosuggest(input, params = {}) ⇒ Object 



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/what3words/api.rb', line 78

def autosuggest(input, params = {})
  # Returns a list of 3 word addresses based on user input and other parameters.
  #   @:param string input: The full or partial 3 word address to obtain suggestions for.
  #     At minimum this must be the first two complete words plus at least one character
  #     from the third word.
  #   @:param int n_results: The number of AutoSuggest results to return.
  #     A maximum of 100 results can be specified, if a number greater than this is requested,
  #     this will be truncated to the maximum. The default is 3.
  #   @:param int n_focus_results: Specifies the number of results (must be <= n_results)
  #     within the results set which will have a focus. Defaults to n_results.
  #     This allows you to run autosuggest with a mix of focussed and unfocussed results,
  #     to give you a "blend" of the two.
  #   @:param string clip-to-country: Restricts autosuggest to only return results inside
  #     the countries specified by comma-separated list of uppercase ISO 3166-1
  #     alpha-2 country codes (for example, to restrict to Belgium and the UK,
  #     use clip_to_country="GB,BE").
  #   @:param clip-to-bounding-box: Restrict autosuggest results to a bounding box, specified by coordinates.
  #   @:param clip-to-circle: Restrict autosuggest results to a circle, specified by
  #     the center of the circle, latitude and longitude, and a distance in kilometres which represents the radius.
  #     For convenience, longitude is allowed to wrap around 180 degrees. For example 181 is equivalent to -179.
  #   @:param clip-to-polygon: Restrict autosuggest results to a polygon, specified by a list of coordinates.
  #     The polygon should be closed, i.e. the first element should be repeated as the
  #     last element; also the list should contain at least 4 entries.
  #     The API is currently limited to accepting up to 25 pairs.
  #   @:param string input-type: For power users, used to specify voice input mode.
  #     Can be text (default), vocon-hybrid, nmdp-asr or generic-voice.
  #   @:param string prefer-land: Makes autosuggest prefer results on land to those in the sea.
  #   @:param string language: A supported 3 word address language as an ISO 639-1 2 letter code.
  #     This setting is on by default. Use false to disable this setting and receive more suggestions in the sea.

  # API Reference: https://docs.what3words.com/api/v3/#autosuggest
  request_params = assemble_autosuggest_request_params(input, params)
  response = request! :autosuggest, request_params
  response
end

#available_languages ⇒ Object 



70
71
72
73
74
75
76
 
# File 'lib/what3words/api.rb', line 70

def available_languages
  # Retrieve a list of available 3 word languages.
  # API Reference: https://docs.what3words.com/api/v3/#available-languages
  request_params = assemble_common_request_params({})
  response = request! :available_languages, request_params
  response
end

#convert_to_3wa(position, params = {}) ⇒ Object 



48
49
50
51
52
53
54
55
56
57
 
# File 'lib/what3words/api.rb', line 48

def convert_to_3wa(position, params = {})
  # Take latitude and longitude coordinates and turn them into a 3 word address.
  #   @:param coordinates: the coordinates of the location to convert to 3 word address
  #   @:param string format: Return data format type; can be one of json (the default), geojson
  #   @:param string language: A supported 3 word address language as an ISO 639-1 2 letter code.
  # API Reference: https://docs.what3words.com/api/v3/#convert-to-3wa
  request_params = assemble_convert_to_3wa_request_params(position, params)
  response = request! :convert_to_3wa, request_params
  response
end

#convert_to_coordinates(words, params = {}) ⇒ Object 



37
38
39
40
41
42
43
44
45
46
 
# File 'lib/what3words/api.rb', line 37

def convert_to_coordinates(words, params = {})
  # Take a 3 word address and turn it into a pair of coordinates.
  #   @:param string words: A 3 word address as a string
  #   @:param string format: Return data format type; can be one of json (the default), geojson
  # API Reference: https://docs.what3words.com/api/v3/#convert-to-coordinates
  words_string = get_words_string words
  request_params = assemble_convert_to_coordinates_request_params(words_string, params)
  response = request! :convert_to_coordinates, request_params
  response
end

#deep_symbolize_keys(i) ⇒ Object 



241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/what3words/api.rb', line 241

def deep_symbolize_keys(i)
  if i.is_a? Hash
    ni = {}
    i.each { |k, v| ni[k.respond_to?(:to_sym) ? k.to_sym : k] = deep_symbolize_keys(v) }
  elsif i.is_a? Array
    ni = i.map(&method(:deep_symbolize_keys))
  else
    ni = i
  end

  ni
end

#endpoint(name) ⇒ Object 



259
260
261
 
# File 'lib/what3words/api.rb', line 259

def endpoint(name)
  base_url + ENDPOINTS.fetch(name)
end

#grid_section(bbox, params = {}) ⇒ Object 



59
60
61
62
63
64
65
66
67
68
 
# File 'lib/what3words/api.rb', line 59

def grid_section(bbox, params = {})
  # Returns a section of the 3m x 3m what3words grid for a given area.
  #   @:param bounding-box: Bounding box, specified by the northeast and southwest corner coordinates,
  #     for which the grid should be returned.
  #   @:param string format: Return data format type; can be one of json (the default), geojson
  # API Reference: https://docs.what3words.com/api/v3/#grid-section
  request_params = assemble_grid_request_params(bbox, params)
  response = request! :grid_section, request_params
  response
end