google_maps_apis 1.0.0

data/lib/google_maps_apis/services/directions.rb

@@ -0,0 +1,101 @@
+require_relative '../validator'
+
+module GoogleMapsApis::Services
+
+  # Performs requests to the Google Maps Directions API.
+  module Directions
+
+    # Get directions between an origin point and a destination point.
+    #
+    # @example Simple directions
+    #   routes = client.directions('Sydney', 'Melbourne')
+    #
+    # @example Complex bicycling directions
+    #   routes = client.directions('Sydney', 'Melbourne',
+    #       mode: 'bicycling',
+    #       avoid: ['highways', 'tolls', 'ferries'],
+    #       units: 'metric',
+    #       region: 'au')
+    #
+    # @example Public transportation directions
+    #    an_hour_from_now = Time.now - (1.0/24)
+    #    routes = client.directions('Sydney Town Hall', 'Parramatta, NSW',
+    #        mode: 'transit',
+    #        arrival_time: an_hour_from_now)
+    #
+    # @example Walking with alternative routes
+    #    routes = client.directions('Sydney Town Hall', 'Parramatta, NSW',
+    #       mode: 'walking',
+    #       alternatives: true)
+    #
+    # @param [String, Hash, Array] origin The address or latitude/longitude value from which you wish
+    #         to calculate directions.
+    # @param [String, Hash, Array] destination The address or latitude/longitude value from which
+    #     you wish to calculate directions.
+    # @param [String] mode Specifies the mode of transport to use when calculating
+    #     directions. One of `driving`, `walking`, `bicycling` or `transit`.
+    # @param [Array<String>, Array<Hash>, Array<Array>] waypoints Specifies an array of waypoints. Waypoints alter a
+    #     route by routing it through the specified location(s).
+    # @param [Boolean] alternatives If True, more than one route may be returned in the
+    #     response.
+    # @param [Array, String] avoid Indicates that the calculated route(s) should avoid the
+    #     indicated features.
+    # @param [String] language The language in which to return results.
+    # @param [String] units Specifies the unit system to use when displaying results.
+    #     `metric` or `imperial`.
+    # @param [String] region The region code, specified as a ccTLD (_top-level domain_)
+    #     two-character value.
+    # @param [Integer, DateTime] departure_time Specifies the desired time of departure.
+    # @param [Integer, DateTime] arrival_time Specifies the desired time of arrival for transit
+    #     directions. Note: you can not specify both `departure_time` and
+    #     `arrival_time`.
+    # @param [Boolean] optimize_waypoints Optimize the provided route by rearranging the
+    #     waypoints in a more efficient order.
+    # @param [String, Array<String>] transit_mode Specifies one or more preferred modes of transit.
+    #     This parameter may only be specified for requests where the mode is
+    #     transit. Valid values are `bus`, `subway`, `train`, `tram` or `rail`.
+    #     `rail` is equivalent to `["train", "tram", "subway"]`.
+    # @param [String] transit_routing_preference Specifies preferences for transit
+    #     requests. Valid values are `less_walking` or `fewer_transfers`.
+    #
+    # @return [Array] Array of routes.
+    def directions(origin, destination,
+        mode: nil, waypoints: nil, alternatives: false, avoid: nil,
+        language: nil, units: nil, region: nil, departure_time: nil,
+        arrival_time: nil, optimize_waypoints: false, transit_mode: nil,
+        transit_routing_preference: nil)
+
+      params = {
+        origin: GoogleMapsApis::Convert.waypoint(origin),
+        destination: GoogleMapsApis::Convert.waypoint(destination)
+      }
+
+      params[:mode] = GoogleMapsApis::Validator.travel_mode(mode) if mode
+
+      if waypoints = waypoints
+        waypoints = GoogleMapsApis::Convert.as_list(waypoints)
+        waypoints = waypoints.map { |waypoint| GoogleMapsApis::Convert.waypoint(waypoint) }
+        waypoints = ['optimize:true'] + waypoints if optimize_waypoints
+
+        params[:waypoints] = GoogleMapsApis::Convert.join_list("|", waypoints)
+      end
+
+      params[:alternatives] = 'true' if alternatives
+      params[:avoid] = GoogleMapsApis::Convert.join_list('|', avoid) if avoid
+      params[:language] = language if language
+      params[:units] = units if units
+      params[:region] = region if region
+      params[:departure_time] = GoogleMapsApis::Convert.time(departure_time) if departure_time
+      params[:arrival_time] = GoogleMapsApis::Convert.time(arrival_time) if arrival_time
+
+      if departure_time and arrival_time
+        raise ArgumentError, 'Should not specify both departure_time and arrival_time.'
+      end
+
+      params[:transit_mode] = GoogleMapsApis::Convert.join_list("|", transit_mode) if transit_mode
+      params[:transit_routing_preference] = transit_routing_preference if transit_routing_preference
+
+      return get('/maps/api/directions/json', params)[:routes]
+    end
+  end
+end

data/lib/google_maps_apis/services/distance_matrix.rb

@@ -0,0 +1,85 @@
+require_relative '../validator'
+
+module GoogleMapsApis::Services
+
+  # Performs requests to the Google Maps Distance Matrix API.
+  module DistanceMatrix
+
+    # Gets travel distance and time for a matrix of origins and destinations.
+    #
+    # @example Simple distance matrix
+    #   origins = ["Perth, Australia", "Sydney, Australia",
+    #              "Melbourne, Australia", "Adelaide, Australia",
+    #              "Brisbane, Australia", "Darwin, Australia",
+    #              "Hobart, Australia", "Canberra, Australia"]
+    #   destinations = ["Uluru, Australia",
+    #                   "Kakadu, Australia",
+    #                   "Blue Mountains, Australia",
+    #                   "Bungle Bungles, Australia",
+    #                   "The Pinnacles, Australia"]
+    #   matrix = client.distance_matrix(origins, destinations)
+    #
+    # @example Complex distance matrix
+    #   origins = ["Bobcaygeon ON", [41.43206, -81.38992]]
+    #   destinations = [[43.012486, -83.6964149], {lat: 42.8863855, lng: -78.8781627}]
+    #   matrix = client.distance_matrix(origins, destinations,
+    #       mode: 'driving',
+    #       language: 'en-AU',
+    #       avoid: 'tolls',
+    #       units: 'imperial')
+    #
+    # @param [Array] origins One or more addresses and/or lat/lon pairs,
+    #         from which to calculate distance and time. If you pass an address
+    #         as a string, the service will geocode the string and convert it to
+    #         a lat/lon coordinate to calculate directions.
+    # @param [Array] destinations One or more addresses and/or lat/lon pairs, to
+    #         which to calculate distance and time. If you pass an address as a
+    #         string, the service will geocode the string and convert it to a
+    #         lat/lon coordinate to calculate directions.
+    # @param [String] mode Specifies the mode of transport to use when calculating
+    #         directions. Valid values are `driving`, `walking`, `transit` or `bicycling`.
+    # @param [String] language The language in which to return results.
+    # @param [String] avoid Indicates that the calculated route(s) should avoid the
+    #     indicated features. Valid values are `tolls`, `highways` or `ferries`.
+    # @param [String] units Specifies the unit system to use when displaying results.
+    #     Valid values are `metric` or `imperial`.
+    # @param [Integer, DateTime] departure_time Specifies the desired time of departure.
+    # @param [Integer, DateTime] arrival_time Specifies the desired time of arrival for transit
+    #     directions. Note: you can not specify both `departure_time` and `arrival_time`.
+    # @param [String, Array<String>] transit_mode Specifies one or more preferred modes of transit.
+    #     This parameter may only be specified for requests where the mode is
+    #     transit. Valid values are `bus`, `subway`, `train`, `tram`, or `rail`.
+    #     `rail` is equivalent to `["train", "tram", "subway"]`.
+    # @param [String] transit_routing_preference Specifies preferences for transit
+    #     requests. Valid values are `less_walking` or `fewer_transfers`.
+    #
+    # @return [Hash] Matrix of distances. Results are returned in rows, each row
+    #     containing one origin paired with each destination.
+    def distance_matrix(origins, destinations,
+        mode: nil, language: nil, avoid: nil, units: nil,
+        departure_time: nil, arrival_time: nil, transit_mode: nil,
+        transit_routing_preference: nil)
+      params = {
+        origins: GoogleMapsApis::Convert.waypoints(origins),
+        destinations: GoogleMapsApis::Convert.waypoints(destinations)
+      }
+
+      params[:language] = language if language
+      params[:mode] = GoogleMapsApis::Validator.travel_mode(mode) if mode
+      params[:avoid] = GoogleMapsApis::Validator.avoid(avoid) if avoid
+
+      params[:units] = units if units
+      params[:departure_time] = GoogleMapsApis::Convert.time(departure_time) if departure_time
+      params[:arrival_time] = GoogleMapsApis::Convert.time(arrival_time) if arrival_time
+
+      if departure_time and arrival_time
+        raise ArgumentError, 'Should not specify both departure_time and arrival_time.'
+      end
+
+      params[:transit_mode] = GoogleMapsApis::Convert.join_list('|', transit_mode) if transit_mode
+      params[:transit_routing_preference] = transit_routing_preference if transit_routing_preference
+
+      return get('/maps/api/distancematrix/json', params)
+    end
+  end
+end

data/lib/google_maps_apis/services/elevation.rb

@@ -0,0 +1,58 @@
+module GoogleMapsApis::Services
+
+  # Performs requests to the Google Maps Elevation API.
+  module Elevation
+
+    # Provides elevation data for locations provided on the surface of the
+    # earth, including depth locations on the ocean floor (which return negative
+    # values).
+    #
+    # @example Single point elevation
+    #   results = client.elevation({latitude: 40.714728, longitude: -73.998672})
+    #
+    # @example Multiple points elevation
+    #   locations = [[40.714728, -73.998672], [-34.397, 150.644]]
+    #   results = client.elevation(locations)
+    #
+    # @param [Array] locations A single latitude/longitude hash, or an array of
+    #         latitude/longitude hash from which you wish to calculate
+    #         elevation data.
+    #
+    # @return [Array] Array of elevation data responses
+    def elevation(locations)
+      params = {
+        locations: GoogleMapsApis::Convert.waypoints(locations)
+      }
+
+      return get('/maps/api/elevation/json', params)[:results]
+    end
+
+    # Provides elevation data sampled along a path on the surface of the earth.
+    #
+    # @example Elevation along path
+    #   locations = [[40.714728, -73.998672], [-34.397, 150.644]]
+    #   results = client.elevation_along_path(locations, 5)
+    #
+    # @param [String, Array] path A encoded polyline string, or a list of
+    #         latitude/longitude pairs from which you wish to calculate
+    #         elevation data.
+    # @param [Integer] samples The number of sample points along a path for which to
+    #         return elevation data.
+    #
+    # @return [Array] Array of elevation data responses
+    def elevation_along_path(path, samples)
+      if path.kind_of?(String)
+        path = "enc:%s" % path
+      else
+        path = GoogleMapsApis::Convert.waypoints(path)
+      end
+
+      params = {
+        path: path,
+        samples: samples
+      }
+
+      return get('/maps/api/elevation/json', params)[:results]
+    end
+  end
+end

data/lib/google_maps_apis/services/geocoding.rb

@@ -0,0 +1,85 @@
+require 'google_maps_apis/convert'
+
+module GoogleMapsApis::Services
+
+  # Performs requests to the Google Maps Geocoding API.
+  module Geocoding
+
+    # Geocoding is the process of converting addresses
+    # (like `"1600 Amphitheatre Parkway, Mountain View, CA"`) into geographic
+    # coordinates (like latitude 37.423021 and longitude -122.083739), which you
+    # can use to place markers or position the map.
+    #
+    # @example Geocode an address
+    #   results = client.geocode('Sydney')
+    #
+    # @example Geocode a component only
+    #   results = client.geocode(nil, components: {administrative_area: 'TX', country: 'US'})
+    #
+    # @example Geocode an address and component
+    #   results = client.geocode('Sydney', components: {administrative_area: 'TX', country: 'US'})
+    #
+    # @example Multiple parameters
+    #   results = client.geocode('Sydney',
+    #       components: {administrative_area: 'TX', country: 'US'},
+    #       bounds: {
+    #         northeast: {lat: 32.7183997, lng: -97.26864001970849},
+    #         southwest: {lat: 32.7052583, lng: -97.27133798029149}
+    #       },
+    #       region: 'us')
+    #
+    # @param [String] address The address to geocode. You must specify either this value and/or `components`.
+    # @param [Hash] components A component filter for which you wish to obtain a geocode,
+    #                    for example: `{'administrative_area': 'TX','country': 'US'}`
+    # @param [String, Hash] bounds The bounding box of the viewport within which to bias geocode
+    #                results more prominently. Accept string or hash with `northeast` and `southwest` keys.
+    # @param [String] region The region code, specified as a ccTLD (_top-level domain_)
+    #                two-character value.
+    # @param [String] language The language in which to return results.
+    #
+    # @return [Array] Array of geocoding results.
+    def geocode(address, components: nil, bounds: nil, region: nil, language: nil)
+      params = {}
+
+      params[:address] = address if address
+      params[:components] = GoogleMapsApis::Convert.components(components) if components
+      params[:bounds] = GoogleMapsApis::Convert.bounds(bounds) if bounds
+      params[:region] = region if region
+      params[:language] = language if language
+
+      return get('/maps/api/geocode/json', params)[:results]
+    end
+
+    # Reverse geocoding is the process of converting geographic coordinates into a
+    # human-readable address.
+    #
+    # @example Simple lat/lon pair
+    #   client.reverse_geocode({lat: 40.714224, lng: -73.961452})
+    #
+    # @example Multiple parameters
+    #   client.reverse_geocode([40.714224, -73.961452],
+    #       location_type: ['ROOFTOP', 'RANGE_INTERPOLATED'],
+    #       result_type: ['street_address', 'route'],
+    #       language: 'es')
+    #
+    # @param [Hash, Array] latlng The latitude/longitude value for which you wish to obtain
+    #                the closest, human-readable address.
+    # @param [String, Array<String>] location_type One or more location types to restrict results to.
+    # @param [String, Array<String>] result_type One or more address types to restrict results to.
+    # @param [String] language The language in which to return results.
+    #
+    # @return [Array] Array of reverse geocoding results.
+    def reverse_geocode(latlng, location_type: nil, result_type: nil, language: nil)
+      params = {
+        latlng: GoogleMapsApis::Convert.latlng(latlng)
+      }
+
+      params[:result_type] = GoogleMapsApis::Convert.join_list('|', result_type) if result_type
+      params[:location_type] = GoogleMapsApis::Convert.join_list('|', location_type) if location_type
+      params[:language] = language if language
+
+      return get('/maps/api/geocode/json', params)[:results]
+    end
+
+  end
+end

data/lib/google_maps_apis/services/places.rb

@@ -0,0 +1,20 @@
+require 'google_maps_apis/convert'
+
+module GoogleMapsApis::Services
+
+  # Performs requests to the Google Maps Geocoding API.
+  module Places
+    def places_autocomplete(input, components: nil, bounds: nil, types: nil, region: nil, language: nil)
+      params = {}
+
+      params[:input] = input
+      params[:components] = GoogleMapsApis::Convert.components(components) if components
+      params[:bounds] = GoogleMapsApis::Convert.bounds(bounds) if bounds
+      params[:region] = region if region
+      params[:language] = language if language
+      params[:types] = types if types
+
+      return get('/maps/api/place/autocomplete/json', params)[:predictions]
+    end
+  end
+end

data/lib/google_maps_apis/services/roads.rb

@@ -0,0 +1,187 @@
+require 'multi_json'
+
+module GoogleMapsApis::Services
+
+  # Performs requests to the Google Maps Roads API.
+  module Roads
+
+    # Base URL of Google Maps Roads API
+    ROADS_BASE_URL = "https://roads.googleapis.com"
+
+    # Snaps a path to the most likely roads travelled.
+    #
+    # Takes up to 100 GPS points collected along a route, and returns a similar
+    # set of data with the points snapped to the most likely roads the vehicle
+    # was traveling along.
+    #
+    # @example Single point snap
+    #   results = client.snap_to_roads([40.714728, -73.998672])
+    #
+    # @example Multi points snap
+    #   path = [
+    #       [-33.8671, 151.20714],
+    #       [-33.86708, 151.20683000000002],
+    #       [-33.867070000000005, 151.20674000000002],
+    #       [-33.86703, 151.20625]
+    #   ]
+    #   results = client.snap_to_roads(path, interpolate: true)
+    #
+    # @param [Array] path The path to be snapped. Array of latitude/longitude pairs.
+    # @param [Boolean] interpolate Whether to interpolate a path to include all points
+    #         forming the full road-geometry. When true, additional interpolated
+    #         points will also be returned, resulting in a path that smoothly
+    #         follows the geometry of the road, even around corners and through
+    #         tunnels.  Interpolated paths may contain more points than the
+    #         original path.
+    #
+    # @return [Array] Array of snapped points.
+    def snap_to_roads(path, interpolate: false)
+      path = GoogleMapsApis::Convert.waypoints(path)
+
+      params = {
+        path: path
+      }
+
+      params[:interpolate] = 'true' if interpolate
+
+      return get('/v1/snapToRoads', params,
+                 base_url: ROADS_BASE_URL,
+                 accepts_client_id: false,
+                 custom_response_decoder: method(:extract_roads_body))[:snappedPoints]
+    end
+
+    # Returns the posted speed limit (in km/h) for given road segments.
+    #
+    # @example Multi places snap
+    #   place_ids = [
+    #     'ChIJ0wawjUCuEmsRgfqC5Wd9ARM',
+    #     'ChIJ6cs2kkCuEmsRUfqC5Wd9ARM'
+    #   ]
+    #   results = client.speed_limits(place_ids)
+    #
+    # @param [String, Array<String>] place_ids The Place ID of the road segment. Place IDs are returned
+    #         by the snap_to_roads function. You can pass up to 100 Place IDs.
+    #
+    # @return [Array] Array of speed limits.
+    def speed_limits(place_ids)
+      params = GoogleMapsApis::Convert.as_list(place_ids).map { |place_id| ['placeId', place_id] }
+
+      return get('/v1/speedLimits', params,
+                 base_url: ROADS_BASE_URL,
+                 accepts_client_id: false,
+                 custom_response_decoder: method(:extract_roads_body))[:speedLimits]
+    end
+
+    # Returns the posted speed limit (in km/h) for given road segments.
+    #
+    # The provided points will first be snapped to the most likely roads the
+    # vehicle was traveling along.
+    #
+    # @example Multi points snap
+    #   path = [
+    #       [-33.8671, 151.20714],
+    #       [-33.86708, 151.20683000000002],
+    #       [-33.867070000000005, 151.20674000000002],
+    #       [-33.86703, 151.20625]
+    #   ]
+    #   results = client.snapped_speed_limits(path)
+    #
+    # @param [Hash, Array] path The path of points to be snapped. A list of (or single)
+    #         latitude/longitude tuples.
+    #
+    # @return [Hash] A hash with both a list of speed limits and a list of the snapped
+    #         points.
+    def snapped_speed_limits(path)
+      path = GoogleMapsApis::Convert.waypoints(path)
+
+      params = {
+        path: path
+      }
+
+      return get('/v1/speedLimits', params,
+                 base_url: ROADS_BASE_URL,
+                 accepts_client_id: false,
+                 custom_response_decoder: method(:extract_roads_body))
+    end
+
+    # Returns the nearest road segments for provided points.
+    # The points passed do not need to be part of a continuous path.
+    #
+    # @example Single point snap
+    #   results = client.nearest_roads([40.714728, -73.998672])
+    #
+    # @example Multi points snap
+    #   points = [
+    #       [-33.8671, 151.20714],
+    #       [-33.86708, 151.20683000000002],
+    #       [-33.867070000000005, 151.20674000000002],
+    #       [-33.86703, 151.20625]
+    #   ]
+    #   results = client.nearest_roads(points)
+    #
+    # @param [Array] points The points to be used for nearest road segment lookup. Array of latitude/longitude pairs
+    #                       which do not need to be a part of continuous part.
+    #                       Takes up to 100 independent coordinates, and returns the closest road segment for each point.
+    #
+    # @return [Array] Array of snapped points.
+
+    def nearest_roads(points)
+      points = GoogleMapsApis::Convert.waypoints(points)
+
+      params = {
+        points: points
+      }
+
+      return get('/v1/nearestRoads', params,
+                 base_url: ROADS_BASE_URL,
+                 accepts_client_id: false,
+                 custom_response_decoder: method(:extract_roads_body))[:snappedPoints]
+    end
+
+
+
+    private
+      # Extracts a result from a Roads API HTTP response.
+      def extract_roads_body(response)
+        begin
+          body = MultiJson.load(response.body, :symbolize_keys => true)
+        rescue
+          unless response.status == 200
+            check_response_status(response)
+          end
+          raise GoogleMapsApis::Error::ApiError.new(response), 'Received a malformed response.'
+        end
+
+        check_roads_body_error(response, body)
+
+        unless response.status == 200
+          raise GoogleMapsApis::Error::ApiError.new(response)
+        end
+        return body
+      end
+
+      # Check response body for error status.
+      #
+      # @param [Faraday::Response] response Response object.
+      # @param [Hash] body Response body.
+      def check_roads_body_error(response, body)
+        error = body[:error]
+        return unless error
+
+        case error[:status]
+          when 'INVALID_ARGUMENT'
+            if error[:message] == 'The provided API key is invalid.'
+              raise GoogleMapsApis::Error::RequestDeniedError.new(response), error[:message]
+            end
+            raise GoogleMapsApis::Error::InvalidRequestError.new(response), error[:message]
+          when 'PERMISSION_DENIED'
+            raise GoogleMapsApis::Error::RequestDeniedError.new(response), error[:message]
+          when 'RESOURCE_EXHAUSTED'
+            raise GoogleMapsApis::Error::RateLimitError.new(response), error[:message]
+          else
+            raise GoogleMapsApis::Error::ApiError.new(response), error[:message]
+        end
+      end
+
+  end
+end

data/lib/google_maps_apis/services/time_zone.rb

@@ -0,0 +1,41 @@
+require 'date'
+
+module GoogleMapsApis::Services
+
+  # Performs requests to the Google Maps TimeZone API."""
+  module TimeZone
+
+    # Get time zone for a location on the earth, as well as that location's
+    # time offset from UTC.
+    #
+    # @example Current time zone
+    #   timezone = client.timezone([39.603481, -119.682251])
+    #
+    # @example Time zone at certain time
+    #   timezone = client.timezone([39.603481, -119.682251], timestamp: Time.at(1608))
+    #
+    # @param [Hash, Array] location The latitude/longitude value representing the location to
+    #     look up.
+    # @param [Integer, DateTime] timestamp Timestamp specifies the desired time as seconds since
+    #     midnight, January 1, 1970 UTC. The Time Zone API uses the timestamp to
+    #     determine whether or not Daylight Savings should be applied. Times
+    #     before 1970 can be expressed as negative values. Optional. Defaults to
+    #     `Time.now`.
+    # @param [String] language The language in which to return results.
+    #
+    # @return [Hash] Time zone object.
+    def timezone(location, timestamp: Time.now, language: nil)
+      location = GoogleMapsApis::Convert.latlng(location)
+      timestamp = GoogleMapsApis::Convert.time(timestamp)
+
+      params = {
+        location: location,
+        timestamp: timestamp
+      }
+
+      params[:language] = language if language
+
+      return get('/maps/api/timezone/json', params)
+    end
+  end
+end

data/lib/google_maps_apis/services.rb

@@ -0,0 +1,6 @@
+module GoogleMapsApis
+
+  # Collections of Google Maps Web Services
+  module Services
+  end
+end

data/lib/google_maps_apis/url.rb

@@ -0,0 +1,64 @@
+require 'base64'
+require 'uri'
+
+module GoogleMapsApis
+
+  # Helper for handling URL.
+  module Url
+    module_function
+
+    # Returns a base64-encoded HMAC-SHA1 signature of a given string.
+    #
+    # @param [String] secret The key used for the signature, base64 encoded.
+    # @param [String] payload The payload to sign.
+    #
+    # @return [String] Base64-encoded HMAC-SHA1 signature
+    def sign_hmac(secret, payload)
+      secret = secret.encode('ASCII')
+      payload = payload.encode('ASCII')
+
+      # Decode the private key
+      raw_key = Base64.urlsafe_decode64(secret)
+
+      # Create a signature using the private key and the URL
+      digest = OpenSSL::Digest.new('sha1')
+      raw_signature = OpenSSL::HMAC.digest(digest, raw_key, payload)
+
+      # Encode the signature into base64 for url use form.
+      signature =  Base64.urlsafe_encode64(raw_signature)
+      return signature
+    end
+
+    # URL encodes the parameters.
+    # @param [Hash, Array<Array>] params The parameters
+    # @return [String]
+    def urlencode_params(params)
+      unquote_unreserved(URI.encode_www_form(params))
+    end
+
+    # Un-escape any percent-escape sequences in a URI that are unreserved
+    # characters. This leaves all reserved, illegal and non-ASCII bytes encoded.
+    #
+    # @param [String] uri
+    #
+    # @return [String]
+    def unquote_unreserved(uri)
+      parts = uri.split('%')
+
+      (1..parts.length-1).each do |i|
+        h = parts[i][0..1]
+
+        if h =~ /^([\h]{2})(.*)/ and c = $1.to_i(16).chr and UNRESERVED_SET.include?(c)
+          parts[i] = c + $2
+        else
+          parts[i] = '%' + parts[i]
+        end
+      end
+
+      parts.join
+    end
+
+    # The unreserved URI characters (RFC 3986)
+    UNRESERVED_SET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~"
+  end
+end