what3words Ruby wrapper

Use the what3words API in your Ruby app (see http://developer.what3words.com/api)

Installation

Add this line to your application's Gemfile:

    gem 'what3words', '~> 2.2'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install what3words

Usage

See https://docs.what3words.com/api/v2/ for all parameters that can be passed to the API calls

If not using Bundler, require it:

    require 'what3words'

Then:

    what3words = What3Words::API.new(:key => "YOURAPIKEY")

Forward Geocode : convert a 3 word address into GPS coordinates (WGS-84)

    what3words.forward 'prom.cape.pump'
    # => {:crs=>{:properties=>{:type=>"ogcwkt", :href=>"http://spatialreference.org/ref/epsg/4326/ogcwkt/"}, :type=>"link"}, :bounds=>{:southwest=>{:lng=>-0.195426, :lat=>51.484449}, :northeast=>{:lng=>-0.195383, :lat=>51.484476}}, :words=>"prom.cape.pump", :map=>"http://w3w.co/prom.cape.pump", :language=>"en", :geometry=>{:lng=>-0.195405, :lat=>51.484463}, :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}

API

Forward Geocoding

Convert a 3 word address into GPS coordinates and return 3 words for the same position in a different language

    what3words.forward "prom.cape.pump", :lang => "fr"
    # => {:crs=>{:properties=>{:type=>"ogcwkt", :href=>"http://spatialreference.org/ref/epsg/4326/ogcwkt/"}, :type=>"link"}, :bounds=>{:southwest=>{:lng=>-0.195426, :lat=>51.484449}, :northeast=>{:lng=>-0.195383, :lat=>51.484476}}, :words=>"concevoir.époque.amasser", :map=>"http://w3w.co/concevoir.époque.amasser", :language=>"fr", :geometry=>{:lng=>-0.195405, :lat=>51.484463}, :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}

Supported keyword params for forward call:

lang (defaults to language of 3 words) - optional language code (only use this if you want to return 3 words in a different language to the language submitted)
format Return data format type; can be one of json (the default), geojson or xml
display Return display type; can be one of full (the default) or terse

Reverse Geocoding

Reverse Geocode : Convert position(latitude) information to a 3 word address

    what3words.reverse [51.484463, -0.195405]
    # => {:crs=>{:properties=>{:type=>"ogcwkt", :href=>"http://spatialreference.org/ref/epsg/4326/ogcwkt/"}, :type=>"link"}, :bounds=>{:southwest=>{:lng=>-0.195426, :lat=>51.484449}, :northeast=>{:lng=>-0.195383, :lat=>51.484476}}, :words=>"prom.cape.pump", :map=>"http://w3w.co/prom.cape.pump", :language=>"en", :geometry=>{:lng=>-0.195405, :lat=>51.484463}, :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}
    ```

Convert position information to a 3 word address in a specific language

```ruby
    what3words.reverse [51.484463, -0.195405], :lang => :fr
    # => {:crs=>{:properties=>{:type=>"ogcwkt", :href=>"http://spatialreference.org/ref/epsg/4326/ogcwkt/"}, :type=>"link"}, :bounds=>{:southwest=>{:lng=>-0.195426, :lat=>51.484449}, :northeast=>{:lng=>-0.195383, :lat=>51.484476}}, :words=>"concevoir.époque.amasser", :map=>"http://w3w.co/concevoir.époque.amasser", :language=>"fr", :geometry=>{:lng=>-0.195405, :lat=>51.484463}, :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}

Supported keyword params for reverse call:

lang (defaults to en) - optional language code
format Return data format type; can be one of json (the default), geojson or xml
display Return display type; can be one of full (the default) or terse

Autosuggest

Returns a list of 3 word addresses based on user input and other parameters.

This resource provides corrections for the following types of input error:

typing errors
spelling errors
misremembered words (e.g. singular vs. plural)
words in the wrong order

The autosuggest resource determines possible corrections to the supplied 3 word address string based on the probability of the input errors listed above and returns a ranked list of suggestions. This resource can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned.

Single and Multilingual Variants

AutoSuggest is provided via 2 variant resources; single language and multilingual.

The single language autosuggest method requires a language to be specified.

The multilingual autosuggest_ml method requires a language to be specified. This will ensure that the autosuggest-ml resource will look for suggestions in this language, in addition to any other languages that yield relevant suggestions.

see https://docs.what3words.com/api/v2/#autosuggest for detailed information

Gets suggestions in italian for this address

    what3words.autosuggest "trovò.calore.perder", "it"
    # => {:suggestions=>[{:score=>12, :country=>"ma", :words=>"trovò.calore.perdere", :rank=>1, :geometry=>{:lng=>-6.665638, :lat=>34.318065}, :place=>"Kenitra, Gharb-Chrarda-Beni Hssen"}, {:score=>12, :country=>"ca", :words=>"trovò.calore.perderò", :rank=>2, :geometry=>{:lng=>-65.036149, :lat=>45.846472}, :place=>"Salisbury, New Brunswick"}, {:score=>17, :country=>"ve", :words=>"trovò.calore.prede", :rank=>3, :geometry=>{:lng=>-70.280645, :lat=>7.24527}, :place=>"Guasdualito, Apure"}], :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}

    what3words.autosuggest_ml "trovò.calore.perder", "it"

Supported keyword params for autosuggest and autosuggest_ml call:

format Return data format type; can be one of json (the default), geojson or xml
display Return display type; can be one of full (the default) or terse

Standardblend

Returns a blend of the three most relevant 3 word address candidates for a given location, based on a full or partial 3 word address.

The specified 3 word address may either be a full 3 word address or a partial 3 word address containing the first 2 words in full and at least 1 character of the 3rd word. The standardblend resource provides the search logic that powers the search box on map.what3words.com and in the what3words mobile apps.

Single and Multilingual Variants

AutoSuggest is provided via 2 variant resources; single language and multilingual.

The single language standardblend method requires a language to be specified.

The multilingual standardblend_ml method requires a language to be specified. This will ensure that the standardblend-ml resource will look for suggestions in this language, in addition to any other languages that yield relevant suggestions.

see https://docs.what3words.com/api/v2/#standardblend for detailed information

Gets blends in italian for this address

    what3words.standardblend "trovò.calore.perder", "it"
    # => {:blends=>[{:country=>"ma", :words=>"trovò.calore.perdere", :rank=>1, :language=>"it", :geometry=>{:lng=>-6.665638, :lat=>34.318065}, :place=>"Kenitra, Gharb-Chrarda-Beni Hssen"}, {:country=>"ca", :words=>"trovò.calore.perderò", :rank=>2, :language=>"it", :geometry=>{:lng=>-65.036149, :lat=>45.846472}, :place=>"Salisbury, New Brunswick"}, {:country=>"ve", :words=>"trovò.calore.prede", :rank=>3, :language=>"it", :geometry=>{:lng=>-70.280645, :lat=>7.24527}, :place=>"Guasdualito, Apure"}], :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}

    what3words.standardblend_ml "trovò.calore.perder", "it"

Supported keyword params for standardblend and standardblend_ml call:

format Return data format type; can be one of json (the default), geojson or xml
display Return display type; can be one of full (the default) or terse

Grid

Returns a section of the 3m x 3m what3words grid for a given area.

see https://docs.what3words.com/api/v2/#grid for detailed information

Gets grid for these bounding box northeast 52.208867,0.117540, southwest 52.207988,0.116126

    what3words.grid "52.208867,0.117540,52.207988,0.116126"
    # => {:lines=>[{:start=>{:lng=>0.11612600000001, :lat=>52.208009918068}, :end=>{:lng=>0.11753999999999, :lat=>52.208009918068}}, ___...___ , :end=>{:lng=>0.11752023935234, :lat=>52.208867}}], :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}

Supported keyword params for grid call:

format Return data format type; can be one of json (the default), geojson or xml
display Return display type; can be one of full (the default) or terse

Get Languages

Get list of available 3 word languages

    what3words.languages
    # => {{:languages=>[{:code=>"de", :name=>"German", :native_name=>"Deutsch"}, {:code=>"mn", :name=>"Mongolian", :native_name=>"Mонгол"}, {:code=>"fi", :name=>"Finnish", :native_name=>"Suomi"}, {:code=>"ru", :name=>"Russian", :native_name=>"Русский"}, {:code=>"sv", :name=>"Swedish", :native_name=>"Svenska"}, {:code=>"pt", :name=>"Portuguese", :native_name=>"Português"}, {:code=>"sw", :name=>"Swahili", :native_name=>"Kiswahili"}, {:code=>"en", :name=>"English", :native_name=>"English"}, {:code=>"it", :name=>"Italian", :native_name=>"Italiano"}, {:code=>"fr", :name=>"French", :native_name=>"Français"}, {:code=>"es", :name=>"Spanish", :native_name=>"Español"}, {:code=>"ar", :name=>"Arabic", :native_name=>"العربية"}, {:code=>"pl", :name=>"Polish", :native_name=>"Polski"}, {:code=>"tr", :name=>"Turkish", :native_name=>"Türkçe"}], :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}

See http://developer.what3words.com for the original API call documentation

Testing

Prerequisite : we are using bundler $ gem install bundler
W3W-API-KEY : For safe storage of your API key on your computer, you can define that API key using your system’s environment variables.

$ export W3W_API_KEY=<Secret API Key>

on your cloned folder

$ cd w3w-ruby-wrapper
$ bundle update
$ rake rubocop spec

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Contributing

Anyone and everyone is welcome to contribute.

Fork it (http://github.com/what3words/w3w-ruby-wrapper and click "Fork")
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Don't forget to update README and bump version using semver
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Revision History

v2.2.0 03/01/18 - Enforce Ruby 2.4 Support - Thanks to PR from Dimitrios Zorbas @Zorbash
v2.1.1 22/05/17 - Update gemspec to use rubocop 0.48.1, and fixes spec accordingly
v2.1.0 28/03/17 - Added multilingual version of autosuggest and standardblend
v2.0.4 27/03/17 - Updated README with languages method result updated from live result
v2.0.3 24/10/16 - Fixed display in assemble_common_request_params
v2.0.2 10/06/16 - Added travis-ci builds
v2.0.0 10/06/16 - Updated wrapper to use what3words API v2

Licensing

The MIT License (MIT)

A copy of the license is available in the repository's license file.

pzgz/w3w-ruby-wrapper