mapbox_directions 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 499d139ed0106ee1428d94f915bd25e856af786b
+  data.tar.gz: 11282aac7616703f4be00af438f3af4303c3daac
+SHA512:
+  metadata.gz: 46fe7a87a9d0c4040867266f8644c1095de40fc1c66dd645d403d7f97facc454902918ff142c77fc09f53c7bdf5dccf38149d9cb11975529d6423487d8630de8
+  data.tar.gz: b4091582b7fecb8eafe012139cf7171243d6effb776f22222ad6bc1fb694ba9993ee9390cc4393b7edb96821d95e4ee36eb6b9f8e857bffd5e71dd26dda8974e

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--require spec_helper
+--require byebug
+--format documentation

data/.travis.yml

@@ -0,0 +1,14 @@
+script: CODECLIMATE_REPO_TOKEN=5e7eb3ca9f5744cce3649045cd4887324323c2ffc7b6b3a3be7de1bbb064ddbf bundle exec rspec
+language: ruby
+cache: bundler
+rvm:
+- 2.0.0
+- 2.1.0
+- 2.1.1
+- 2.1.2
+- 2.1.3
+- 2.1.4
+- 2.1.5
+- 2.2.0
+- 2.2.1
+- 2.2.2

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem "codeclimate-test-reporter", group: :test, require: false
+
+# Specify your gem's dependencies in mapbox_directions.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,5 @@
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 yonelacort
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# MapboxDirections
+
+[![Build Status](https://travis-ci.org/allyapp/mapbox_directions.svg?branch=master)](https://travis-ci.org/allyapp/mapbox_directions)
+[![Code Climate](https://codeclimate.com/github/allyapp/mapbox_directions/badges/gpa.svg)](https://codeclimate.com/github/allyapp/mapbox_directions)
+[![Test Coverage](https://codeclimate.com/github/allyapp/mapbox_directions/badges/coverage.svg)](https://codeclimate.com/github/allyapp/mapbox_directions/coverage)
+
+Ruby wrapper for the MapBox Directions Service.
+
+Here you can find the documentation of the API interface:
+https://www.mapbox.com/developers/api/directions/
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mapbox_directions'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mapbox_directions
+
+## Usage
+
+Here's the list of supported parameters and the possible values. Note that parameters that are not optional are required:
+
+- **access_token**: public token provided by MapBox.
+- **mode**: mode of transport applied to process the routing.
+Values: ``driving``, ``cycling``or``walking``.
+- **origin**: origin decimal coordinates where the route starts.
+Format: ``"#{lng},#{lat}"``
+- **destination**: destination decimal coordinates where the route ends.
+Format: ``"#{lng},#{lat}"``
+- **geometry**(optional): format for route geometry.
+Values ``geojson``(default), ``polyline``and ``false`` to omit geometry.
+- **alternatives**(optional): whether to get more than one route as an alternative or not.
+Values: ``true``(default) or ``false`` as a Boolean.
+- **instructions**(optional): format for route instructions.
+Values: ``text``(default) or ``html``.
+
+
+```ruby
+require "mapbox_directions"
+
+parameters = {
+  access_token: "<your_access_token>",
+  mode:         "driving",       # %w(driving cycling walking)
+  origin:       "-122.42,37.78", # "#{lng},#{lat}"
+  destination:  "-77.03,38.91",  # "#{lng},#{lat}"
+  geometry:     "polyline",      # %w(polyline geojson false)
+  alternatives: false,           # true or false
+  instructions: "text",          # %w(text html)
+}
+MapboxDirections.directions(parameters)
+```
+
+### Response body
+
+```ruby
+MapboxDirections.directions(parameters)
+```
+
+Will return a ``MapboxDirections::Response`` that will be composed by:
+- **origin**(``MapboxDirections::Location``): Origin location of the route.
+- **destination**(``MapboxDirections::Location``): Destination location of the route.
+- **waypoints**
+- **routes**(``MapboxDirections::Route``): Array of routes returned.
+- **message**: Informative message.
+- **error**: Informative error message.
+
+``MapboxDirections::Location``:
+- **name**
+- **lat**
+- **lng**
+
+``MapboxDirections::Route``:
+- **distance**
+- **duration**
+- **summary**
+- **geometry**
+- **steps**(``Array[MapboxDirections::Step]``)
+- Methods:
+  - **transform_polyline_precision(precision = 1e5)**: When geometry is polyline, polyline representation format are built with precision 6 (``1e6``).
+  In order to get the polyline string transformed into another precision use this method passing the desired precision, which by default is 5 ``1e5``.
+  To know more about how polyline are built from coordinates:
+  https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+
+
+``MapboxDirections::Step``:
+- **distance**
+- **duration**
+- **way_name**
+- **direction**
+- **heading**
+- **maneuver**(``MapboxDirections::Maneuver``)
+- Methods:
+  - **lat**: Latitude of the maneuver point.
+  - **lng**: Longitude of the maneuver point.
+
+``MapboxDirections::Maneuver``:
+  - **type**
+  - **location**
+  - **instruction**
+  - Methods:
+    - **lat**: Latitude of the maneuver point.
+    - **lng**: Longitude of the maneuver point.
+
+
+For more information about what the values of these attributes contain, please look at the [documentation](https://www.mapbox.com/developers/api/directions/).
+
+### Exceptions
+
+Exceptions are triggered to give immediate feedback when there's something wrong in the parameters passed that won't allow to get a successful response.
+
+- **``MapboxDirections::MissingAccessTokenError``**: When the access token is not passed in the parameters or its value is ``nil``
+
+
+- **``MapboxDirections::InvalidAccessTokenError``**: When the access token is passed in the parameters but it's invalid
+
+- **``MapboxDirections::CoordinatesFormatError``**: When the decimal coordinates are passed bad formatted given the requirements.
+
+
+- **``MapboxDirections::UnsupportedTransportModeError``**: When the mode of transport is different that the ones that the service supports.
+
+
+If the exception raise is an undesired behaviour in the context where the code is being executed, they can be rescued one by one or all at once follows:
+```ruby
+require "mapbox_directions"
+
+def directions(parameters)
+  MapboxDirections.directions(parameters)
+rescue MapboxDirections::Error
+  # Handle exception
+end
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/mapbox_directions/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/mapbox_directions.rb

@@ -0,0 +1,12 @@
+require "mapbox_directions/version"
+require "mapbox_directions/parametizer"
+require "mapbox_directions/response_parser"
+require "mapbox_directions/client"
+
+module MapboxDirections
+  module_function
+
+  def directions(options)
+    Client.new(options).directions
+  end
+end

data/lib/mapbox_directions/client.rb

@@ -0,0 +1,43 @@
+require "faraday"
+require_relative "./parametizer"
+require_relative "./model"
+require_relative "./response_parser"
+
+module MapboxDirections
+  class Client
+    BASE_URL = "https://api.tiles.mapbox.com"
+    PATH     = "/v4/directions"
+
+    def initialize(options)
+      @options = options
+    end
+
+    def directions
+      response = Faraday.get(directions_url, parametizer.params_hash)
+      parse_response(response)
+    end
+
+    private
+
+    def parse_response(response)
+      body = JSON.parse(response.body)
+
+      case response.status
+      when 200
+        ResponseParser.directions(body)
+      when 401
+        raise InvalidAccessTokenError
+      else
+        Response.new(message: body["message"], error: body["error"])
+      end
+    end
+
+    def directions_url
+      "#{BASE_URL}#{PATH}/#{parametizer.profile}/#{parametizer.waypoints}.json"
+    end
+
+    def parametizer
+      @parametizer ||= Parametizer.new(@options)
+    end
+  end
+end

data/lib/mapbox_directions/error.rb

@@ -0,0 +1,7 @@
+module MapboxDirections
+  class Error < StandardError; end
+  class CoordinatesFormatError < Error; end
+  class UnsupportedTransportModeError < Error; end
+  class MissingAccessTokenError < Error; end
+  class InvalidAccessTokenError < Error; end
+end

data/lib/mapbox_directions/model.rb

@@ -0,0 +1,6 @@
+require_relative "./model/point"
+require_relative "./model/location"
+require_relative "./model/maneuver"
+require_relative "./model/step"
+require_relative "./model/route"
+require_relative "./model/response"

data/lib/mapbox_directions/model/location.rb

@@ -0,0 +1,19 @@
+require 'forwardable'
+
+module MapboxDirections
+  class Location
+    extend Forwardable
+    delegate %i(lat lng) => :@point
+
+    attr_reader :point, :name
+
+    def self.from_geojson(geojson)
+      new(point: Point.from_geojson(geojson), name: geojson["properties"]["name"])
+    end
+
+    def initialize(attrs)
+      @point = attrs[:point] || Point.new(attrs[:lat], attrs[:lng])
+      @name  = attrs[:name]
+    end
+  end
+end

data/lib/mapbox_directions/model/maneuver.rb

@@ -0,0 +1,14 @@
+module MapboxDirections
+  class Maneuver
+    extend Forwardable
+    delegate %i(lat lng) => :@location
+
+    attr_reader :type, :location, :instruction
+
+    def initialize(attrs)
+      @type        = attrs[:type]
+      @location    = attrs[:location]
+      @instruction = attrs[:instruction]
+    end
+  end
+end

data/lib/mapbox_directions/model/point.rb

@@ -0,0 +1,17 @@
+require_relative "./point"
+
+module MapboxDirections
+  class Point
+    attr_reader :lat, :lng
+
+    def self.from_geojson(geojson)
+      coords = geojson["geometry"]["coordinates"]
+      new(coords.last, coords.first)
+    end
+
+    def initialize(lat, lng)
+      @lat = lat
+      @lng = lng
+    end
+  end
+end

data/lib/mapbox_directions/model/response.rb

@@ -0,0 +1,16 @@
+require_relative "./route"
+
+module MapboxDirections
+  class Response
+    attr_reader :origin, :destination, :waypoints, :routes, :message, :error
+
+    def initialize(attrs)
+      @origin      = attrs[:origin]
+      @destination = attrs[:destination]
+      @waypoints   = attrs[:waypoints] || []
+      @routes      = attrs[:routes] || []
+      @message     = attrs[:message]
+      @error       = attrs[:error]
+    end
+  end
+end

data/lib/mapbox_directions/model/route.rb

@@ -0,0 +1,24 @@
+require_relative "./location"
+require "polylines"
+
+module MapboxDirections
+  class Route
+    POLYLINE_PRECISION = 1e6
+
+    attr_reader :distance, :duration, :summary, :geometry, :steps
+
+    def initialize(attrs)
+      @distance = attrs[:distance]
+      @duration = attrs[:duration]
+      @summary  = attrs[:summary]
+      @geometry = attrs[:geometry]
+      @steps    = attrs[:steps]
+    end
+
+    def transform_polyline_precision(precision = 1e5)
+      return @geometry unless @geometry.is_a?(String)
+      line_coordinates = Polylines::Decoder.decode_polyline(@geometry, POLYLINE_PRECISION)
+      Polylines::Encoder.encode_points(line_coordinates, precision)
+    end
+  end
+end

data/lib/mapbox_directions/model/step.rb

@@ -0,0 +1,19 @@
+require_relative "./maneuver"
+
+module MapboxDirections
+  class Step
+    extend Forwardable
+    delegate %i(lat lng) => :@maneuver
+
+    attr_reader :distance, :duration, :way_name, :direction, :heading, :maneuver
+
+    def initialize(attrs)
+      @distance  = attrs[:distance]
+      @duration  = attrs[:duration]
+      @way_name  = attrs[:way_name]
+      @direction = attrs[:direction]
+      @heading   = attrs[:heading]
+      @maneuver  = attrs[:maneuver]
+    end
+  end
+end

data/lib/mapbox_directions/parametizer.rb

@@ -0,0 +1,50 @@
+require_relative "./error"
+
+module MapboxDirections
+  class Parametizer
+    ACCEPTED_PARAMS = %w(access_token geometry alternatives instructions)
+    TRANSPORT_MODES = %w(driving cycling walking)
+    ALLOWED_VALUES  = {
+      geometry:     %w(polyline geojson false),
+      alternatives: [true, false],
+      instructions: %w(text html)
+    }
+
+    def initialize(options)
+      @options = options
+    end
+
+    def params_hash
+      raise MissingAccessTokenError unless filtered_params[:access_token]
+      filtered_params
+    end
+
+    def profile
+      raise UnsupportedTransportModeError unless TRANSPORT_MODES.include?(@options[:mode])
+      "mapbox.#{@options[:mode]}"
+    end
+
+    def waypoints
+      raise CoordinatesFormatError if invalid_waypoints?
+      "#{@options[:origin]};#{@options[:destination]}"
+    end
+
+    private
+
+    def filtered_params
+      @filtered_params ||= @options.select { |key, value| valid_key_value?(key, value) }
+    end
+
+    def invalid_waypoints?
+      invalid_coordinates?(@options[:origin]) || invalid_coordinates?(@options[:destination])
+    end
+
+    def invalid_coordinates?(coordinates)
+      /^(\-?\d*(\.\d+)?),(\-?\d*(\.\d+)?)$/.match(coordinates).nil?
+    end
+
+    def valid_key_value?(key, value)
+      key == :access_token || ACCEPTED_PARAMS.include?(key.to_s) && ALLOWED_VALUES[key].include?(value)
+    end
+  end
+end