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 = 
/^\/*(?:[^0-9`~!@#$%^&*()+\-_=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]{1,}[.｡。･・︒។։။۔።।][^0-9`~!@#$%^&*()+\-_=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]{1,}[.｡。･・︒។։။۔።।][^0-9`~!@#$%^&*()+\-_=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]{1,}|[<.,>?\/\";:£§º©®\s]+[.｡。･・︒។։။۔።।][^0-9`~!@#$%^&*()+\-_=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]+|[^0-9`~!@#$%^&*()+\-_=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]+([\u0020\u00A0][^0-9`~!@#$%^&*()+\-_=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]+){1,3}[.｡。･・︒។։။۔።।][^0-9`~!@#$%^&*()+\-_=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]+([\u0020\u00A0][^0-9`~!@#$%^&*()+\-_=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]+){1,3}[.｡。･・︒។։။۔።।][^0-9`~!@#$%^&*()+\-_=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]+([\u0020\u00A0][^0-9`~!@#$%^&*()+\-_=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]+){1,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.



29
30
31
 
# File 'lib/what3words/api.rb', line 29

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

Instance Attribute Details

#key ⇒ Object (readonly)

Returns the value of attribute key.



33
34
35
 
# File 'lib/what3words/api.rb', line 33

def key
  @key
end

Instance Method Details

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



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/what3words/api.rb', line 89

def autosuggest(input, params = {})
  """
  Returns a list of 3 word addresses based on user input and other parameters.

  Params
  ------
  :param string input: The full or partial 3 word address to obtain suggestions for.
  :param int n_results: The number of AutoSuggest results to return.
  :param array focus: A location, specified as a latitude,longitude used to refine the results.
  :param int n_focus_results: Specifies the number of results (must be <= n_results) within the results set which will have a focus.
  :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.
  :param array clip_to_bounding_box: Restrict autosuggest results to a bounding box, specified by coordinates.
  :param array 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.
  :param array clip_to_polygon: Restrict autosuggest results to a polygon, specified by a list of coordinates.
  :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.
  :rtype: Hash
  """
  request_params = assemble_autosuggest_request_params(input, params)
  request!(:autosuggest, request_params)
end

#available_languages ⇒ Object 



79
80
81
82
83
84
85
86
87
 
# File 'lib/what3words/api.rb', line 79

def available_languages
  """
  Retrieve a list of available 3 word languages.

  :rtype: Hash
  """
  request_params = assemble_common_request_params({})
  request!(:available_languages, request_params)
end

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



50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/what3words/api.rb', line 50

def convert_to_3wa(position, params = {})
  """
  Take latitude and longitude coordinates and turn them into a 3 word address.

  Params
  ------
  :param array position: 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.
  :rtype: Hash
  """
  request_params = assemble_convert_to_3wa_request_params(position, params)
  request!(:convert_to_3wa, request_params)
end

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



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

def convert_to_coordinates(words, params = {})
  """
  Take a 3 word address and turn it into a pair of coordinates.

  Params
  ------
  :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
  :rtype: Hash
  """
  words_string = get_words_string(words)
  request_params = assemble_convert_to_coordinates_request_params(words_string, params)
  request!(:convert_to_coordinates, request_params)
end

#didYouMean(text) ⇒ Object 



140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/what3words/api.rb', line 140

def didYouMean(text)
  """
  Determines if the string passed in is almost in the form of a three word address.
  This will return True for values such as 'filled-count-soap' and 'filled count soap'

  Params
  ------
  :param string text: text to check
  :rtype: Boolean
  """
  regex_didyoumean = /^\/?[^0-9`~!@#$%^&*()+\-=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]{1,}[.\uFF61\u3002\uFF65\u30FB\uFE12\u17D4\u0964\u1362\u3002:။^_۔։ ,\\\/+'&\\:;|\u3000-]{1,2}[^0-9`~!@#$%^&*()+\-=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]{1,}[.\uFF61\u3002\uFF65\u30FB\uFE12\u17D4\u0964\u1362\u3002:။^_۔։ ,\\\/+'&\\:;|\u3000-]{1,2}[^0-9`~!@#$%^&*()+\-=\[\{\]}\\|'<>.,?\/\";:£§º©®\s]{1,}$/u
  !(text.match(regex_didyoumean).nil?)
end

#findPossible3wa(text) ⇒ Object 



126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/what3words/api.rb', line 126

def findPossible3wa(text)
  """
  Searches the string passed in for all substrings in the form of a three word address.
  This does not validate whether it is a real address as it will return x.x.x as a result

  Params
  ------
  :param string text: text to check
  :rtype: Array
  """
  regex_search = /[^\d`~!@#$%^&*()+\-=\[\]{}\\|'<>.,?\/\";:£§º©®\s]{1,}[.｡。･・︒។։။۔።।][^\d`~!@#$%^&*()+\-=\[\]{}\\|'<>.,?\/\";:£§º©®\s]{1,}[.｡。･・︒។։။۔።।][^\d`~!@#$%^&*()+\-=\[\]{}\\|'<>.,?\/\";:£§º©®\s]{1,}/u
  text.scan(regex_search)
end

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



65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/what3words/api.rb', line 65

def grid_section(bbox, params = {})
  """
  Returns a section of the 3m x 3m what3words grid for a given area.

  Params
  ------
  :param string bbox: Bounding box, specified by the northeast and southwest corner coordinates,
  :param string format: Return data format type; can be one of json (the default), geojson
  :rtype: Hash
  """
  request_params = assemble_grid_request_params(bbox, params)
  request!(:grid_section, request_params)
end

#isPossible3wa(text) ⇒ Object 



112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/what3words/api.rb', line 112

def isPossible3wa(text)
  """
  Determines if the string passed in is the form of a three word address.
  This does not validate whether it is a real address as it returns true for x.x.x

  Params
  ------
  :param string text: text to check
  :rtype: Boolean
  """
  regex_match = REGEX_3_WORD_ADDRESS
  !(text.match(regex_match).nil?)
end

#isValid3wa(text) ⇒ Object 



154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/what3words/api.rb', line 154

def isValid3wa(text)
  """
  Determines if the string passed in is a real three word address. It calls the API
  to verify it refers to an actual place on earth.

  Params
  ------
  :param String text: text to check

  :rtype: Boolean
  """
  if isPossible3wa(text)
    result = autosuggest(text, 'n-results': 1)
    if result[:suggestions] && result[:suggestions].length > 0
      return result[:suggestions][0][:words] == text
    end
  end
  false
end