lieu 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e394c13ae4c6fff4a3931320af5dbe933017417e
+  data.tar.gz: 9e3b609e92d29e93fee60ce0bb1ece5d4bf1981a
+SHA512:
+  metadata.gz: 793d79dccd5240f699cb4261f5c714a3a34402a5c88c1d2052158a1593699dade407cff69322c1a34bab82e3b033a12aee502586a078ae4cda9fc0ba472052bf
+  data.tar.gz: df5a98efd715f561f8d0da18788ea6038aab058a6e95de37d445ae397f19bb721a37b9eca40f1ac96b5892dd35934265b974bc84909f534988786221774d7bda

data/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+## Running the test suite
+
+	bundle exec rake spec
+	
+### Code quality
+
+Code quality is checked with [cane](https://github.com/square/cane) configured in `Rakefile`.
+
+Build fails if code quality thresholds **are not met**.
+
+### Code coverage
+
+When running the test suite a test coverage report is generated with [SimpleCov](https://github.com/colszowka/simplecov) in `coverage/index.html`.
+
+Build fails if coverage is below **99%**.
+
+## Writing new tests
+Lieu uses [VCR](https://github.com/vcr/vcr) for recording and playing back API fixtures (in `spec/cassettes`) during test runs.
+
+If you need to record new cassettes you have to provide your Google Places Api key in `ENV['GOOGLE_PLACES_API_KEY']` (stripped automaticaly from the cassette before being saved on disk).
+
+## Documentation
+
+Documentation is generated with [YARD](http://yardoc.org/).
+
+## Workflow
+
+1. Fork [Lieu](https://github.com/sush/lieu)
+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/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) [2013] [Aylic Petit]
+
+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,112 @@
+![Lieu](https://raw.github.com/sush/lieu/master/lieu.png)
+
+> The word *lieu* originally comes from the Latin *locus*, meaning *place*, and its meaning has stayed true to its origins ever since.
+
+Simple Ruby wrapper for the [Google Places API](https://developers.google.com/places/documentation).
+
+**Current version**: [![Gem Version](https://badge.fury.io/rb/lieu.png)](http://badge.fury.io/rb/lieu)
+
+**Build status**:        [![Build Status](https://secure.travis-ci.org/Sush/lieu.png?branch=master)](http://travis-ci.org/Sush/lieu)
+
+**Code metrics**:
+     [![Code Climate](https://codeclimate.com/github/Sush/lieu.png)](https://codeclimate.com/github/Sush/lieu)
+[![Coverage Status](https://coveralls.io/repos/Sush/lieu/badge.png?branch=master)](https://coveralls.io/r/Sush/lieu?branch=master)
+
+**Ruby support**:
+
+- 1.9.2
+- 1.9.3
+- 2.0.0
+
+## Installation
+
+Install via Rubygems
+
+    gem install lieu
+
+or add to your Gemfile
+
+    gem 'lieu', '~> 1.0'
+
+### Configuration
+
+API methods are available as module methods
+
+```ruby
+Lieu.configure do |c|
+  c.api_endpoint = 'http://newendpoint/'
+  c.api_key = 'YOUR_API_KEY'
+  c.sensor = true
+end
+```
+
+or as client instance methods
+
+```ruby
+Lieu::Client.new(
+	api_endpoint: 'http://newendpoint/',
+	api_key: 'YOUR_API_KEY',
+	sensor: true
+)
+```
+
+The `sensor` parameter can be set globally (default to `false`) or can be provided for every request by passing the optional parameter `sensor: true`.
+
+## Authentication
+
+Lieu only supports authentication via an API key.
+
+You can request one following these [steps](https://developers.google.com/places/documentation/#Authentication).
+
+## Usage
+
+
+```ruby
+place = Lieu.details('CmRYAAAA...')
+puts place.name
+# => "Google Sydney"
+
+places = Lieu.text_search('Google Sydney')
+places.first.formatted_address
+# => "529 Kent Street, Sydney NSW, Australia"
+
+# etc…
+```
+
+## Features
+
+Lieu supports all the Google Places API methods:
+
+- [Search](http://rubydoc.info/gems/lieu/Lieu/Client/Search)
+- [Details](http://rubydoc.info/gems/lieu/Lieu/Client/Details)
+- [Actions](http://rubydoc.info/gems/lieu/Lieu/Client/Actions)
+- [Photos](http://rubydoc.info/gems/lieu/Lieu/Client/Photos)
+- [Autocomplete](http://rubydoc.info/gems/lieu/Lieu/Client/Autocomplete)
+- [Query autocomplete](http://rubydoc.info/gems/lieu/Lieu/Client/QueryAutocomplete)
+
+Complete Lieu public API's documentation [here](http://rubydoc.info/gems/lieu/frames).
+
+
+## Similar libraries
+
+- [google_places](https://github.com/marceldegraaf/google_places)
+
+## Versioning
+Lieu follows the principles of [semantic versioning](http://semver.org).
+
+1. Patch level releases contain only bug fixes.
+2. Minor releases contain backward-compatible new features.
+3. Major new releases contain backwards-incompatible changes to the public API.
+
+## Contributing
+
+Pull Requests are welcome !
+
+Please refer to the [Contributing guide](https://github.com/sush/lieu/master/CONTRIBUTING.md) for more details on how to run the test suite and to contribute.
+
+
+## Copyright
+
+Copyright © 2013 Aylic Petit
+
+Released under the terms of the MIT licence. See the [LICENSE](https://github.com/sush/lieu/master/LICENSE) file for more details.

data/Rakefile

@@ -0,0 +1,42 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+begin
+  require 'cane/rake_task'
+
+  desc 'Run cane to check quality metrics'
+  Cane::RakeTask.new(:quality) do |cane|
+    cane.add_threshold 'coverage/.last_run.json', :>=, 99
+    cane.abc_glob = '{lib}/**/*.rb'
+    cane.abc_max = 15
+    cane.style_measure = 105
+    cane.style_exclude = %w[spec/spec_helper.rb]
+    cane.canefile = '.cane'
+  end
+rescue LoadError
+end
+
+namespace :doc do
+  begin
+    require 'yard'
+
+    YARD::Rake::YardocTask.new do |task|
+      task.files   = ['README.md', 'LICENSE.md', 'lib/**/*.rb']
+      task.options = [
+        '--output-dir', 'doc/yard',
+        '--markup', 'markdown'
+      ]
+    end
+  rescue LoadError
+  end
+end
+
+Rake::Task[:spec].enhance do
+  Rake::Task[:quality].invoke
+end
+
+task :test => :spec
+task :default => :spec

data/lib/lieu/client/actions.rb

@@ -0,0 +1,105 @@
+module Lieu
+  class Client
+    # Methods for the Place Actions API
+    #
+    # @see https://developers.google.com/places/documentation/actions
+    module Actions
+      # Add a place.
+      # @param options [Hash] a customizable set of options
+      # @option options [Hash] :location the location of place
+      #   * :lat (String) the place latitude
+      #   * :lng (String) the place longitude
+      # @option options [String] :accuracy the accuracy of location
+      # @option options [String] :name the place name
+      # @option options [Array] :types the place types
+      # @option options [String] :language the place name language
+      # @return [Hashie::Mash] the created place details
+      # @see https://developers.google.com/places/documentation/actions#PlaceReportRequests
+      # @example
+      #   Lieu.add(
+      #     reference: 'place_reference',
+      #     location: {
+      #       lat: '0.00',
+      #       lng: '0.00'
+      #     },
+      #     name: 'Fuubar',
+      #     types: [
+      #       'shoe_store'
+      #     ],
+      #     language: 'fr'
+      #   )
+      def add(options={})
+        post('add', options)
+      end
+
+      # Delete a place.
+      # @param options [Hash] a customizable set of options
+      # @option options [String] :reference the place reference
+      # @return [Boolean] true if removal was successful, false otherwise
+      # @see https://developers.google.com/places/documentation/actions#PlaceReportRequests
+      # @example
+      #   Lieu.delete(reference: 'place_reference')
+      def delete(options={})
+        boolean_from_response(:post, 'delete', options)
+      end
+
+      # Bump a place or an event.
+      # @param options [Hash] a customizable set of options
+      # @option options [String] :reference the place reference
+      # @option options [String] :event_id the event id
+      # @return [Boolean] true if bump was successful, false otherwise
+      # @see https://developers.google.com/places/documentation/actions#bump
+      # @example Bump a place
+      #   Lieu.bump(reference: 'place_reference')
+      # @example Bump an event
+      #   Lieu.bump(reference: 'place_reference', event_id: 'event_id')
+      def bump(options={})
+        boolean_from_response(:post, 'bump', options)
+      end
+
+      # Add an event to a place.
+      # @param options [Hash] a customizable set of options
+      # @option options [String] :reference the place reference
+      # @option options [String] :duration the event duration
+      # @option options [String] :language the event language
+      # @option options [String] :summary the event summary
+      # @option options [String] :url the event url
+      # @return [Hashie::Mash] the created event details
+      # @see https://developers.google.com/places/documentation/actions#event_intro
+      # @example
+      #   Lieu.add_event(
+      #     reference: 'place_reference',
+      #     duration: '15',
+      #     language: 'fr',
+      #     summary: 'Nice event',
+      #     url: 'http://fuubar.com/events/fuubar/'
+      #   )
+      def add_event(options={})
+        post('event/add', options)
+      end
+
+      # Delete an event from a place.
+      # @param options [Hash] a customizable set of options
+      # @option options [String] :reference the place reference
+      # @option options [String] :event_id the event id
+      # @return [Boolean] true if deletion was successful, false otherwise
+      # @see https://developers.google.com/places/documentation/actions#event_intro
+      # @example
+      #   Lieu.delete_event(reference: 'place_reference', event_id: 'event_id')
+      def delete_event(options={})
+        boolean_from_response(:post, 'event/delete', options)
+      end
+
+      # Get an event details.
+      # @param reference [String] the event place reference
+      # @param event_id [String] the event id
+      # @param options [Hash] optionnal parameters
+      # @return [Hashie::Mash] the event details
+      def event_details(reference, event_id, options={})
+        options.merge!(reference: reference, event_id: event_id)
+
+        get('event/details', options).result
+      end
+    end
+  end
+end

data/lib/lieu/client/autocomplete.rb

@@ -0,0 +1,21 @@
+module Lieu
+  class Client
+    # Methods for the Place Autocomplete API
+    #
+    # @see https://developers.google.com/places/documentation/autocomplete
+    module Autocomplete
+      # Search a place.
+      # @param input [String] the search term
+      # @param options [Hash] optional parameters
+      # @return [Array<Hashie::Mash>] a list of predicted places
+      # @see https://developers.google.com/places/documentation/autocomplete#place_autocomplete_requests
+      # @example
+      #   Lieu.autocomplete('Le Zenith Paris')
+      def autocomplete(input, options={})
+        options.merge!(input: input)
+
+        get('autocomplete', options).predictions
+      end
+    end
+  end
+end

data/lib/lieu/client/details.rb

@@ -0,0 +1,21 @@
+module Lieu
+  class Client
+    # Methods for the Place Details API
+    #
+    # @see https://developers.google.com/places/documentation/details
+    module Details
+      # Get a place details.
+      # @param reference [String] the place reference
+      # @param options [Hash] optional parameters
+      # @return [Hashie::Mash] the place details
+      # @see https://developers.google.com/places/documentation/details#PlaceDetailsRequests
+      # @example
+      #   Lieu.details('place_reference')
+      def details(reference, options={})
+        options.merge!(reference: reference)
+
+        get('details', options).result
+      end
+    end
+  end
+end

data/lib/lieu/client/photos.rb

@@ -0,0 +1,23 @@
+module Lieu
+  class Client
+    # Methods for the Place Photos API
+    #
+    # @see https://developers.google.com/places/documentation/photos
+    module Photos
+      # Get a photo.
+      # @param photo_reference [String] the photo reference
+      # @param options [Hash] a customizable set of options
+      # @option options [String] :maxheight the maximum desired height in pixels
+      # @option options [String] :maxwidth the maximum desired width in pixels
+      # @return [String] the raw image
+      # @see https://developers.google.com/places/documentation/photos#place_photo_requests
+      # @example
+      #   Lieu.photo('photo_reference', maxheight: '15', maxwidth: '15')
+      def photo(photo_reference, options={})
+        options.merge!(photoreference: photo_reference, json: false)
+
+        get('photo', options)
+      end
+    end
+  end
+end

data/lib/lieu/client/query_autocomplete.rb

@@ -0,0 +1,21 @@
+module Lieu
+  class Client
+    # Methods for the Query Autocomplete API
+    #
+    # @see https://developers.google.com/places/documentation/query
+    module QueryAutocomplete
+      # Perform a categorical search.
+      # @param input [String] the search term
+      # @param options [Hash] optional parameters
+      # @return [Array<Hashie::Mash>] a list of predicted places
+      # @see https://developers.google.com/places/documentation/query#query_autocomplete_requests
+      # @example
+      #   Lieu.query_autocomplete('Pizza Paris')
+      def query_autocomplete(input, options={})
+        options.merge!(input: input)
+
+        get('queryautocomplete', options).predictions
+      end
+    end
+  end
+end

data/lib/lieu/client/search.rb

@@ -0,0 +1,79 @@
+module Lieu
+  class Client
+    # Methods for the Place Search API
+    #
+    # @see https://developers.google.com/places/documentation/search
+    module Search
+      # Search places within an area.
+      # @param options [Hash] a customizable set of options
+      # @option options [Hash] :location the location to find around
+      #   * :lat (String) the latitude to find around
+      #   * :lng (String) the longitude to find around
+      # @option options [String] :radius the distance (in meters) to search in
+      # @return [Array<Hashie::Mash>] a list of places details
+      # @see https://developers.google.com/places/documentation/search#PlaceSearchRequests
+      # @example
+      #   Lieu.nearby_search(location: {
+      #       lat: '0.00',
+      #       lng: '0.00'
+      #     },
+      #     radius: '500'
+      #   )
+      def nearby_search(options={})
+        options[:location] = format_location(options[:location])
+
+        get('nearbysearch', options).results
+      end
+
+      # Text search places.
+      # @param query [String] the text search term
+      # @param options [Hash] optional parameters
+      # @return [Array<Hashie::Mash>] a list of places details
+      # @see https://developers.google.com/places/documentation/search#TextSearchRequests
+      # @example
+      #   Lieu.text_search('Tour Eiffel')
+      def text_search(query, options={})
+        options.merge!(query: query)
+
+        get('textsearch', options).results
+      end
+
+      # Radar search places within an area.
+      # @param options [Hash] a customizable set of options
+      # @option options [Hash] :location the location to find around
+      #   * :lat (String) the latitude to find around
+      #   * :lng (String) the longitude to find around
+      # @option options [String] :radius the distance (in meters) to search in
+      # @option options [String] :keyword a term to be matched against all content for this place
+      # @option options [String] :name a term to be matched against the names of places
+      # @option options [Array<String>] :types types to restrict the results to
+      # @return [Array<Hashie::Mash>] a list of places minimal details
+      # @see https://developers.google.com/places/documentation/search#RadarSearchRequests
+      # @example
+      #   Lieu.radar_search(location: {
+      #       lat: '0.00',
+      #       lng: '0.00'
+      #     },
+      #     radius: '500',
+      #     keyword: 'Pizza',
+      #     name: 'Express'
+      #   )
+      def radar_search(options={})
+        options[:location] = format_location(options[:location])
+        options[:types] = format_types(options[:types]) if options[:types]
+
+        get('radarsearch', options).results
+      end
+
+      private
+
+      def format_location(location)
+        "#{location[:lat]},#{location[:lng]}"
+      end
+
+      def format_types(types)
+        types.join('|')
+      end
+    end
+  end
+end

data/lib/lieu/client.rb

@@ -0,0 +1,36 @@
+require 'lieu/connection'
+require 'lieu/request'
+
+require 'lieu/client/details'
+require 'lieu/client/search'
+require 'lieu/client/autocomplete'
+require 'lieu/client/query_autocomplete'
+require 'lieu/client/photos'
+require 'lieu/client/actions'
+
+module Lieu
+  # Client for the Google Places API
+  #
+  # @see https://developers.google.com/places/documentation
+  class Client
+    attr_accessor(*Configuration::VALID_OPTIONS)
+
+    def initialize(options={})
+      options = Lieu.options.merge(options)
+
+      Configuration::VALID_OPTIONS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    include Lieu::Connection
+    include Lieu::Request
+
+    include Lieu::Client::Details
+    include Lieu::Client::Search
+    include Lieu::Client::Autocomplete
+    include Lieu::Client::QueryAutocomplete
+    include Lieu::Client::Photos
+    include Lieu::Client::Actions
+  end
+end

data/lib/lieu/configuration.rb

@@ -0,0 +1,45 @@
+module Lieu
+  # Methods for Lieu configuration
+  module Configuration
+    # Configurable options
+    VALID_OPTIONS = [
+      :api_endpoint,
+      :api_key,
+      :sensor
+    ].freeze
+
+    # Default Google Place API endpoint
+    DEFAULT_API_ENDPOINT = 'https://maps.googleapis.com/maps/api/place/'
+
+    attr_accessor(*VALID_OPTIONS)
+
+    # @private
+    def self.extended(base_obj)
+      base_obj.initialize_default_options
+    end
+
+    # Set configuration options using a block
+    def configure
+      yield self
+    end
+
+    # Default options
+    def options
+      VALID_OPTIONS.inject({}){ |o, k| o.merge!(k => send(k)) }
+    end
+
+    # Initialize default options
+    def initialize_default_options
+      self.api_endpoint = DEFAULT_API_ENDPOINT
+      self.api_key = nil
+      self.sensor = false
+    end
+
+    # Reset configuration options to default values
+    def reset!
+      initialize_default_options
+
+      self
+    end
+  end
+end

data/lib/lieu/connection.rb

@@ -0,0 +1,28 @@
+require 'faraday_middleware'
+require 'lieu/response/raise_error'
+
+module Lieu
+  # Faraday connection methods
+  module Connection
+    private
+
+    def connection
+      options = {
+        ssl: { verify: false },
+        url: self.api_endpoint
+      }
+
+      connection = Faraday.new(options) do |conn|
+        conn.response(:mashify)
+        conn.response(:json, content_type: /\bjson$/)
+
+        conn.use(Lieu::Response::RaiseError)
+        conn.use(FaradayMiddleware::FollowRedirects, limit: 3)
+
+        conn.adapter(Faraday.default_adapter)
+      end
+
+      connection
+    end
+  end
+end

data/lib/lieu/error.rb

@@ -0,0 +1,58 @@
+require 'multi_json'
+
+module Lieu
+  # Custom error class
+  class Error < StandardError
+    # Returns the Error based on status and response message.
+    #
+    # @param [Hash] response HTTP response
+    # @return [Lieu::Error]
+    def self.from_response(response)
+      content_type = response[:response_headers]['content-type']
+
+      status =
+        if content_type =~ /json/
+          ::MultiJson.load(response[:body])['status']
+        else
+          response[:status]
+        end
+
+      case status
+      when 'INVALID_REQUEST'
+        raise Lieu::InvalidRequest, status
+      when 'REQUEST_DENIED'
+        raise Lieu::RequestDenied, status
+      when 'NOT_FOUND'
+        raise Lieu::NotFound, status
+      when 'UNKNOWN_ERROR'
+        raise Lieu::UnknownError, status
+      when 'ZERO_RESULTS'
+        raise Lieu::ZeroResults, status
+      when 'OVER_QUERY_LIMIT'
+        raise Lieu::OverQueryLimit, status
+      when 400
+        raise Lieu::InvalidRequest, status
+      when 403
+        raise Lieu::OverQueryLimit, status
+      end
+    end
+  end
+
+  # Raised when API returns INVALID_REQUEST or 400 HTTP code
+  class InvalidRequest < Error; end
+
+  # Raised when API returns REQUEST_DENIED
+  class RequestDenied < Error; end
+
+  # Raised when API returns NOT_FOUND
+  class NotFound < Error; end
+
+  # Raised when API returns UNKNOWN_ERROR
+  class UnknownError < Error; end
+
+  # Raised when API returns ZERO_RESULTS
+  class ZeroResults < Error; end
+
+  # Raised when API returns OVER_QUERY_LIMIT or 403 HTTP code
+  class OverQueryLimit < Error; end
+end