google_maps_service 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dc96e3ee965d73c64abc9bb90649c0d328c6c372
-  data.tar.gz: f4da7866e12df9d983e8b93e4572f6094dfc42b8
+  metadata.gz: fb00f53441211719da0e59680a1186a109615495
+  data.tar.gz: 6075646a6a52b3cd64abce441479b1f80e967cbc
 SHA512:
-  metadata.gz: 08a82eb2e0d70161128a3045bb329d351ded380709626420c89a99d7b949ba3c5a0eb31d2f17206cc40123f7566a776c57cbd2b86652ef347c3beccb9120008e
-  data.tar.gz: 6e28ceff3bbada51ae762ea0d1875c644dec83250199e39815a1695cfe1c0cb382f9bcdd7ced9a3b205144eae10b9f20c5015d2bb0fd69c3fdfe3f3d609b66f8
+  metadata.gz: a0007fe257d673c7011097aefc8436664e3a450c7cb9a26d772b5ef72b6818ac52342614572fcf014f5f433ee0ef6ee17a7c2fed98b307d685d3b1807ca8662e
+  data.tar.gz: 24a6947fc3683cd5e58886376bc293a3c3c395952cb021435e001b2c2c4dab3131cace9191c99b999a353fd391667e92cda0b053b4b2dd06d73125a38790acda

data/.yardopts

@@ -0,0 +1,11 @@
+--hide-void-return
+--no-private
+--verbose
+--markup-provider=redcarpet
+--markup=markdown
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+LICENSE

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.4.0
+
+* Use required positional and optional named parameters (_breaking changes_)
+* Documentation with examples
+* Documentation using markdown syntax
+* Use OpenSSL instead Ruby-HMAC to sign url
+* Customizeable HTTP client
+* Fix QPS bug: ensure number of queue items is the given value
+
+## 0.3.0
+
+* QPS: Query per second
+* Refactor lib
+
+## 0.2.0
+
+* Support Ruby >= 2.0.0
+* Auto-retry connection when the request is failed and possible
+* Restructure test (rspec) directory
+* Refactor lib
+
+## 0.1.0
+
+* Initial release.
+* Support Ruby >= 2.2
+* [Google Maps Web Service API](https://developers.google.com/maps/documentation/webservices/) scope:
+    - [Directions API](https://developers.google.com/maps/documentation/directions/)
+    - [Distance Matrix API](https://developers.google.com/maps/documentation/distancematrix/)
+    - [Elevation API](https://developers.google.com/maps/documentation/elevation/)
+    - [Geocoding API](https://developers.google.com/maps/documentation/geocoding/)
+    - [Time Zone API](https://developers.google.com/maps/documentation/timezone/)
+    - [Roads API](https://developers.google.com/maps/documentation/roads/)

data/README.md

@@ -1,47 +1,59 @@
-# Ruby Client for Google Maps Services
+# Ruby gem for Google Maps APIs
 
-[![Gem Version](https://badge.fury.io/rb/google_maps_service.svg)](http://badge.fury.io/rb/google_maps_service) [![Build Status](https://travis-ci.org/edwardsamuel/google-maps-services-ruby.svg?branch=master)](https://travis-ci.org/edwardsamuel/google-maps-services-ruby) [![Dependency Status](https://gemnasium.com/edwardsamuel/google-maps-services-ruby.svg)](https://gemnasium.com/edwardsamuel/google-maps-services-ruby) [![Code Climate](https://codeclimate.com/github/edwardsamuel/google-maps-services-ruby/badges/gpa.svg)](https://codeclimate.com/github/edwardsamuel/google-maps-services-ruby) [![Coverage Status](https://coveralls.io/repos/edwardsamuel/google-maps-services-ruby/badge.svg?branch=master&service=github)](https://coveralls.io/github/edwardsamuel/google-maps-services-ruby?branch=master)
+[![Gem Version](https://badge.fury.io/rb/google_maps_service.svg)](http://badge.fury.io/rb/google_maps_service) [![Build Status](https://travis-ci.org/edwardsamuel/google-maps-services-ruby.svg?branch=master)](https://travis-ci.org/edwardsamuel/google-maps-services-ruby) [![Dependency Status](https://gemnasium.com/edwardsamuel/google-maps-services-ruby.svg)](https://gemnasium.com/edwardsamuel/google-maps-services-ruby) [![Code Climate](https://codeclimate.com/github/edwardsamuel/google-maps-services-ruby/badges/gpa.svg)](https://codeclimate.com/github/edwardsamuel/google-maps-services-ruby) [![Coverage Status](https://coveralls.io/repos/edwardsamuel/google-maps-services-ruby/badge.svg?branch=master&service=github)](https://coveralls.io/github/edwardsamuel/google-maps-services-ruby?branch=master) [![Inch CI](https://inch-ci.org/github/edwardsamuel/google-maps-services-ruby.svg?branch=master)](https://inch-ci.org/github/edwardsamuel/google-maps-services-ruby?branch=master)
 
-*This is porting of [Python Client for Google Maps Services](https://github.com/googlemaps/google-maps-services-python).*
+![Analytics](https://ga-beacon.appspot.com/UA-66926725-1/google-maps-services-ruby/readme?pixel)
+
+*This gem is ported from [Python Client for Google Maps Services](https://github.com/googlemaps/google-maps-services-python).*
 
 ## Description
 
 Use Ruby? Want to [geocode][Geocoding API] something? Looking for [directions][Directions API]?
-Maybe [matrices of directions][Distance Matrix API]? This library brings the [Google Maps API Web
+Maybe [matrices of directions][Distance Matrix API]? This gem brings the [Google Maps API Web
 Services] to your Ruby application.
-![Analytics](https://ga-beacon.appspot.com/UA-66926725-1/google-maps-services-ruby/readme?pixel)
 
-The Ruby Client for Google Maps Services is a Ruby Client library for the following Google Maps APIs:
+The Ruby gem for Google Maps Web Service APIs is a gem for the following Google Maps APIs:
 
- - [Directions API]
- - [Distance Matrix API]
- - [Elevation API]
- - [Geocoding API]
- - [Time Zone API]
- - [Roads API]
+ - [Google Maps Directions API][Directions API]
+ - [Google Maps Distance Matrix API][Distance Matrix API]
+ - [Google Maps Elevation API][Elevation API]
+ - [Google Maps Geocoding API][Geocoding API]
+ - [Google Maps Time Zone API][Time Zone API]
+ - [Google Maps Roads API][Roads API]
 
 Keep in mind that the same [terms and conditions](https://developers.google.com/maps/terms) apply
-to usage of the APIs when they're accessed through this library.
+to usage of the APIs when they're accessed through this gem.
 
-## Support
 
-This library is community supported. We're comfortable enough with the stability and features of
-the library that we want you to build real production applications on it. We will try to support,
-through Stack Overflow, the public and protected surface of the library and maintain backwards
-compatibility in the future; however, while the library is in version 0.x, we reserve the right
-to make backwards-incompatible changes. If we do remove some functionality (typically because
-better functionality exists or if the feature proved infeasible), our intention is to deprecate
-and give developers a year to update their code.
+## Features
 
-If you find a bug, or have a feature suggestion, please [log an issue][issues]. If you'd like to
-contribute, please read [How to Contribute](#contributing).
+### Rate Limiting
+
+Never sleep between requests again! By default, requests are sent at the expected rate limits for
+each web service, typically 10 queries per second for free users. If you want to speed up or slowdown requests, you can do that too, using `queries_per_second` options while initializing API client.
+
+### Retry on Failure
+
+Automatically retry when intermittent failures occur. That is, when any of the retriable 5xx errors
+are returned from the API.
+
+### Keys *and* Client IDs
+
+Maps API for Work customers can use their [client ID and secret][clientid] to authenticate. Free
+customers can use their [API key][apikey], too.
+
+Note: Currently, [Roads API] does not accept client ID. It requires API key to authenticate the request.
+
+### Ruby Hash/Array as API Result
+
+This gem return a Ruby Hash/Array object as the API result. The result format structure is same as in Google Maps API documentation.
 
 ## Requirements
 
  - Ruby 2.0 or later.
- - A Google Maps API key.
+ - A Google Maps API credentials (API keys or client IDs)
 
-### API keys
+### Obtain API keys
 
 Each Google Maps Web Service requires an API key or Client ID. API keys are
 freely available with a Google Account at https://developers.google.com/console.
@@ -72,58 +84,287 @@ Your API key should be 40 characters long, and begin with `AIza`.
 
 ## Installation
 
-    $ gem install google_maps_service
+Add this line to your application's Gemfile:
+
+    gem 'google_maps_service'
+
+And then execute:
 
-## Developer Documentation
+    bundle install
 
-View the [reference documentation](http://www.rubydoc.info/gems/google_maps_service)
+Or install it yourself as:
 
-Additional documentation for the included web services is available at
-https://developers.google.com/maps/.
+    gem install google_maps_service
 
- - [Directions API]
- - [Distance Matrix API]
- - [Elevation API]
- - [Geocoding API]
- - [Time Zone API]
- - [Roads API]
+In your Ruby code, add this line to load this gem:
+
+    require 'google_maps_service'
 
 ## Usage
 
-This example uses the [Geocoding API].
+Before you request Google Maps API, you must configure the client.
+
+You can view the [reference documentation](http://www.rubydoc.info/gems/google_maps_service).
+
+### Configure client
+
+```ruby
+require 'google_maps_service'
+
+# Setup API keys
+gmaps = GoogleMapsService::Client.new(key: 'Add your key here')
+
+# Setup client IDs
+gmaps = GoogleMapsService::Client.new(
+    client_id: 'Add your client id here',
+    client_secret: 'Add your client secret here'
+)
+
+# More complex setup
+gmaps = GoogleMapsService::Client.new(
+    key: 'Add your key here',
+    retry_timeout: 20,      # Timeout for retrying failed request
+    queries_per_second: 10  # Limit total request per second
+)
+```
+You can also set up the client globally.
+
+```ruby
+require 'google_maps_service'
+
+# Setup global parameters
+GoogleMapsService.configure do |config|
+  config.key = 'Add your key here'
+  config.retry_timeout = 20
+  config.queries_per_second = 10
+end
+
+# Initialize client using global parameters
+gmaps = GoogleMapsService::Client.new
+```
+
+For more examples and detail (setup **proxy**, **timeout**, **caching**, etc.) while initializing the client, check out [Client documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/Client#initialize-instance_method).
+
+### Latitude/longitude pairs format
+
+Some APIs require latitude/longitude pair(s) as their parameter(s). This gem accept various format of latitude/longitude pairs:
+
+```ruby
+# Array
+latlng = [40.714224, -73.961452]
+
+# Hash with symbolized keys
+latlng = {lat: 40.714224, lng: -73.961452}
+latlng = {latitude: 40.714224, longitude: -73.961452}
+
+# Hash with string keys
+latlng = {'lat' => 40.714224, 'lng' => -73.961452}
+latlng = {'latitude' => 40.714224, 'longitude' => -73.961452}
+```
+
+### Directions API
+
+```ruby
+# Simple directions
+routes = gmaps.directions(
+    '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA',
+    '2400 Amphitheatre Parkway, Mountain View, CA 94043, USA',
+    mode: 'walking',
+    alternatives: false)
+```
+
+Sample result:
+
+```ruby
+[{
+  :bounds=>{
+    :northeast=>{:lat=>37.4238004, :lng=>-122.084314},
+    :southwest=>{:lat=>37.42277989999999, :lng=>-122.0882019}
+  },
+  :copyrights=>"Map data ©2015 Google",
+  :legs=>[
+    {
+      :distance=>{:text=>"0.2 mi", :value=>393},
+      :duration=>{:text=>"5 mins", :value=>287},
+      :end_address=>"2400 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
+      :end_location=>{:lat=>37.4238004, :lng=>-122.0882019},
+      :start_address=>"1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
+      :start_location=>{:lat=>37.42277989999999, :lng=>-122.084314},
+      :steps=>[
+        {
+          :distance=>{:text=>"223 ft", :value=>68},
+          :duration=>{:text=>"1 min", :value=>49},
+          :end_location=>{:lat=>37.4228653, :lng=>-122.0850785},
+          :html_instructions=>"Head <b>west</b>",
+          :polyline=>{:points=>"kclcF|qchVEdAGx@ALAJ"},
+          :start_location=>{:lat=>37.42277989999999, :lng=>-122.084314},
+          :travel_mode=>"WALKING"
+        }, {
+          :distance=>{:text=>"108 ft", :value=>33},
+          :duration=>{:text=>"1 min", :value=>23},
+          :end_location=>{:lat=>37.423161, :lng=>-122.0850102},
+          :html_instructions=>"Turn <b>right</b> toward <b>Amphitheatre Pkwy</b>",
+          :maneuver=>"turn-right",
+          :polyline=>{:points=>"}clcFvvchVg@IQC"},
+          :start_location=>{:lat=>37.4228653, :lng=>-122.0850785},
+          :travel_mode=>"WALKING"
+        }, {
+          :distance=>{:text=>"407 ft", :value=>124},
+          :duration=>{:text=>"2 mins", :value=>90},
+          :end_location=>{:lat=>37.423396, :lng=>-122.0863768},
+          :html_instructions=>"Turn <b>left</b> onto <b>Amphitheatre Pkwy</b>",
+          :maneuver=>"turn-left",
+          :polyline=>{:points=>"welcFhvchVEf@Eb@C\\EZGp@Il@CRAJAJ"},
+          :start_location=>{:lat=>37.423161, :lng=>-122.0850102},
+          :travel_mode=>"WALKING"
+        }, {
+          :distance=>{:text=>"0.1 mi", :value=>168},
+          :duration=>{:text=>"2 mins", :value=>125},
+          :end_location=>{:lat=>37.4238004, :lng=>-122.0882019},
+          :html_instructions=>
+            "Slight <b>right</b> to stay on <b>Amphitheatre Pkwy</b><div style=\"font-size:0.9em\">Destination will be on the right</div>",
+          :maneuver=>"turn-slight-right",
+          :polyline=>{:points=>"gglcFz~chVGJADAD?DIh@MhAWhBOxACT"},
+          :start_location=>{:lat=>37.423396, :lng=>-122.0863768},
+          :travel_mode=>"WALKING"
+        }
+      ],
+      :via_waypoint=>[]
+    }
+  ],
+  :overview_polyline=>{:points=>"kclcF|qchVQxCy@MKjA[xCE^IVMz@y@bH"},
+  :summary=>"Amphitheatre Pkwy",
+  :warnings=>["Walking directions are in beta.    Use caution – This route may be missing sidewalks or pedestrian paths."],
+  :waypoint_order=>[]
+}]
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/Directions), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/directions_spec.rb), and [Google Maps Directions API documentation][Directions API].
+
+### Distance Matrix API
+
+```ruby
+# Multiple parameters distance matrix
+origins = ["Bobcaygeon ON", [41.43206, -81.38992]]
+destinations = [[43.012486, -83.6964149], {lat: 42.8863855, lng: -78.8781627}]
+matrix = gmaps.distance_matrix(origins, destinations,
+    mode: 'driving',
+    language: 'en-AU',
+    avoid: 'tolls',
+    units: 'imperial')
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/DistanceMatrix), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/distance_matrix_spec.rb), and [Google Maps Distance Matrix API documentation][Distance Matrix API].
+
+### Elevation API
 
 ```ruby
-gmaps = GoogleMapsService::Client.new(key: 'Add Your Key here')
+# Elevation of some locations
+locations = [[40.714728, -73.998672], [-34.397, 150.644]]
+results = gmaps.elevation(locations)
+
+# Elevation along path
+locations = [[40.714728, -73.998672], [-34.397, 150.644]]
+results = gmaps.elevation_along_path(locations, 5)
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/Elevation), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/elevation_spec.rb), and [Google Maps Elevation API documentation][Elevation API].
 
-# Geocoding and address
-geocode_result = gmaps.geocode(address: '1600 Amphitheatre Parkway, Mountain View, CA')
+### Geocoding API
+
+```ruby
+# Geocoding an address
+results = gmaps.geocode('1600 Amphitheatre Parkway, Mountain View, CA')
 
 # Look up an address with reverse geocoding
-reverse_geocode_result = gmaps.reverse_geocode(latlng: [40.714224, -73.961452])
-
-# Request directions via public transit
-now = Time.now
-directions_result = gmaps.directions(origin: "Sydney Town Hall",
-                                     destination: "Parramatta, NSW",
-                                     mode: "transit",
-                                     departure_time: now)
+results = gmaps.reverse_geocode([40.714224, -73.961452])
 ```
 
-For more usage examples, check out [the tests](spec/).
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/Geocoding), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/geocoding_spec.rb), and [Google Maps Geocoding API documentation][Geocoding API].
 
-## Contributing
+### Roads API
+
+```ruby
+# Snap to roads
+path = [
+    [-33.8671, 151.20714],
+    [-33.86708, 151.20683000000002],
+    [-33.867070000000005, 151.20674000000002],
+    [-33.86703, 151.20625]
+]
+results = gmaps.snap_to_roads(path, interpolate: true)
+
+# Snapped speed limits
+path = [
+    [-33.8671, 151.20714],
+    [-33.86708, 151.20683000000002],
+    [-33.867070000000005, 151.20674000000002],
+    [-33.86703, 151.20625]
+]
+results = gmaps.snapped_speed_limits(path)
+
+# Speed limits
+place_ids = [
+  'ChIJ0wawjUCuEmsRgfqC5Wd9ARM',
+  'ChIJ6cs2kkCuEmsRUfqC5Wd9ARM'
+]
+results = gmaps.speed_limits(place_ids)
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/Roads), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/roads_spec.rb), and [Google Maps Roads API documentation][Roads API].
+
+### Time Zone API
 
-1. Fork it ( https://github.com/edwardsamuel/google-maps-services-ruby/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
+```ruby
+# Current time zone
+timezone = gmaps.timezone([39.603481, -119.682251])
+
+# Time zone at certain time
+timezone = gmaps.timezone([39.603481, -119.682251], timestamp: Time.at(1608))
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/TimeZone), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/time_zone_spec.rb), and [Google Maps Time Zone API documentation][Time Zone API].
+
+### Polyline encoder/decoder
+
+[Google Encoded Polyline] is a lossy compression algorithm that allows you to store a series of coordinates as a single string. This format is used in some APIs:
+
+  - [Directions API] encodes the result path.
+  - [Elevation API] also accepts the encoded polyline as request parameter.
+
+To handle Google Encoded Polyline, this gem provides encoder/decoder:
+
+```ruby
+require 'google_maps_service/polyline' # Or, require 'google_maps_service' is enough
 
+# Decode polyline
+encoded_path = '_p~iF~ps|U_ulLnnqC_mqNvxq`@'
+path = GoogleMapsService::Polyline.decode(encoded_path)
+#=> [{:lat=>38.5, :lng=>-120.2}, {:lat=>40.7, :lng=>-120.95}, {:lat=>43.252, :lng=>-126.45300000000002}]
+
+# Encode polyline
+path = [[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]]
+encoded_path = GoogleMapsService::Polyline.encode(path)
+#=> "_p~iF~ps|U_ulLnnqC_mqNvxq`@"
+```
+
+## Issues and feature suggestions
+
+If you find a bug, or have a feature suggestion, please [log an issue][issues]. If you'd like to
+contribute, please read [How to Contribute](#contributing).
+
+## Contributing
+
+1. Fork it (https://github.com/edwardsamuel/google-maps-services-ruby/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.
 
 [apikey]: https://developers.google.com/maps/faq#keysystem
 [clientid]: https://developers.google.com/maps/documentation/business/webservices/auth
 
-[Google Maps API Web Services]: https://developers.google.com/maps/documentation/webservices/
+[Google Maps API Web Services]: https://developers.google.com/maps/web-services/overview/
 [Directions API]: https://developers.google.com/maps/documentation/directions/
 [Distance Matrix API]: https://developers.google.com/maps/documentation/distancematrix/
 [Elevation API]: https://developers.google.com/maps/documentation/elevation/
@@ -131,4 +372,6 @@ For more usage examples, check out [the tests](spec/).
 [Time Zone API]: https://developers.google.com/maps/documentation/timezone/
 [Roads API]: https://developers.google.com/maps/documentation/roads/
 
+[Google Encoded Polyline]: https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+
 [issues]: https://github.com/edwardsamuel/google-maps-services-ruby/issues