oldbill 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format Fuubar

data/Gemfile

@@ -0,0 +1,18 @@
+source "http://rubygems.org"
+
+gemspec
+
+# Will automatically pull in this gem and all its
+# dependencies specified in the gemspec
+gem "oldbill", :path => File.expand_path("..", __FILE__)
+gem "yard"
+
+# These are development dependencies 
+group :test do
+  gem "rake"
+  gem "rspec", "2.5.0"
+  gem 'vcr',                '~> 1.5', :require => false
+  gem 'webmock',            '~> 1.6', :require => false
+  gem "autotest"
+end
+

data/README.rdoc

@@ -0,0 +1,82 @@
+= OldBill
+
+OldBill gives you a nice ruby wrapper for the {police.uk API}[http://police.uk]
+
+== Idiomatic Ruby
+== Concrete classes and methods modelling Police data
+
+== Quickstart
+
+  @session = OldBill.session.create(:username => "username", :password => "password")
+  
+  @session.locate(52.6397278, -1.1322921).crimes_by_month
+
+=== Defaults:
+
+    caching                    # => true (boolean)
+    expires_in                 # => 60*60*24 (seconds)
+    cache                      # => Moneta::Memory.new "(Moneta Supported Cache) http://github.com/wycats/moneta
+    server                     # => "api-stage.carboncalculated.com" (string)
+    api_version                #=>  "v1" (string)
+    logging                    # => true (boolean)
+    
+== This is overriding the defaults
+
+    @session = OldBill::Session.create(
+      :username => "username",
+      :password => "password"
+      :cache => Moneta::S3.new(:access_key_id => ENV['AWS_ACCESS_KEY_ID'], :secret_access_key => ENV['AWS_SECRET_ACCESS_KEY'], :bucket => 'carbon')
+      :expires_in => 60*60*24*14
+    )
+    
+    This has created a session with S3 Moneta cache that expires in 14 days
+
+== Resources
+
+<b>Police API</b> for code: http://policeapi2.rkh.co.uk/api/docs/
+
+<b>Gemcutter</b> for the gem: http://gemcutter.org/gems/oldbill
+
+== Using OldBill
+
+  The API is separated into 2 area neighbourhoods and crime
+  
+=== Forces
+
+  @session = OldBill.session.create(:username => "username", :password => "password")
+  @session.forces
+  
+=== Crimes
+
+  @session = OldBill.session.create(:username => "username", :password => "password")
+  
+  @session.crimes_by_month("leicestershire", "C01")
+  
+  @session.street_level_crimes(52.6397278, -1.1322921)
+  
+  @session.crime_categories
+
+=== Neighbourhoods
+
+  @session = OldBill.session.create(:username => "username", :password => "password")
+  
+  @session.neighbourhoods("leicestershire")
+  
+  @session.neighbourhood("leicestershire", "C01")
+  
+  You can then call methods on the neighbourhood
+  
+  @session.neighbourhood("leicestershire", "C01").street_level_crimes
+  @session.neighbourhood("leicestershire", "C01").crimes_by_month
+  @session.neighbourhood("leicestershire", "C01").events
+  @session.neighbourhood("leicestershire", "C01").police_officers
+  
+== Locate A Neighbourhood
+
+  @session = OldBill.session.create(:username => "username", :password => "password")
+  @session.locate(52.6397278, -1.1322921)
+  
+  @session.locate(52.6397278, -1.1322921).events
+  @session.locate(52.6397278, -1.1322921).crimes_by_month
+  @session.locate(52.6397278, -1.1322921).police_officers
+  @session.locate(52.6397278, -1.1322921).full_neighbourhood.street_level_crimes

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/autotest/discover.rb

@@ -0,0 +1 @@
+Autotest.add_discovery { ["rspec2"] }

data/lib/oldbill/api/crime.rb

@@ -0,0 +1,46 @@
+module OldBill
+  module Api
+    module Crime
+      
+      # @return [Array<Hashie::Dash>] #id #name
+      def forces
+        api_call(:get, "/forces") do |response|
+          response.map{|category| Hashie::Mash.new(merge_session!(category))}
+        end
+      end
+      
+      # @return [OldBill::Force>] #id #name
+      def force(force, params = {})
+        api_call(:get, "/forces/#{force}", params) do |response|
+          OldBill::V2::Force.new(merge_session!(response))
+        end
+      end
+      
+      # @param [String] force
+      # @param [String] neighbourhood
+      # @return [Array<OldBill::CrimeByMonth>]
+      def crimes_by_month(force, neighbourhood, params = {})
+        api_call(:get, "/#{force}/#{neighbourhood}/crime", params) do |response|
+          (response.empty? ? [] : response["crimes"].map{|crime_by_month| OldBill::V2::CrimeByMonth.new(merge_session!({:month => crime_by_month[0]}.merge(crime_by_month[1])))})
+        end
+      end
+
+      # @param [Float] Latitude of the requested crime area
+      # @param [Float] Longitude of the requested crime area
+      # @return [Array<OldBill::Crimes::StreetLevel>]
+      def street_level_crimes(lat, lng, params = {})
+        api_call(:get, "/crimes-street/all-crime", params.merge!({:lat => lat, :lng => lng})) do |response|
+          response.map{|street_crime| OldBill::V2::Crimes::StreetLevel.new(merge_session!(street_crime))}
+        end
+      end
+      
+      # @return [Array<Hashie::Dash>] #url #name
+      def crime_categories
+        api_call(:get, "/crime-categories") do |response|
+          response.map{|category| Hashie::Mash.new(merge_session!(category))}
+        end
+      end
+      
+    end
+  end
+end

data/lib/oldbill/api/neighbourhood.rb

@@ -0,0 +1,56 @@
+module OldBill
+  module Api
+    module Neighbourhood
+      
+      
+      # @param [String] force
+      # @return [Array<OldBill::Neighbourhood>] only partially loaded
+      def neighbourhoods(force, params = {})
+        api_call(:get, "/#{force}/neighbourhoods", params) do |response|
+          response.map{|neighbourhood| OldBill::V2::Neighbourhood.new(merge_session!(neighbourhood.merge({:force => force, :fully_loaded => false}))) }
+        end
+      end
+      
+      # @param [String] force
+      # @param [String] neighbourhood
+      # @return [Array<OldBill::Neighbourhood>]
+      def neighbourhood(force, neighbourhood, params = {})
+        api_call(:get, "/#{force}/#{neighbourhood}", params) do |response|
+          OldBill::V2::Neighbourhood.new(merge_session!(response.merge({:force => force, :fully_loaded => true})))
+        end
+      end
+      
+      # @param [String] force
+      # @param [String] neighbourhood
+      # @return [Array<OldBill::V2::Neighbourhoods::Event>]
+      def events(force, neighbourhood, params = {})
+        api_call(:get, "/#{force}/#{neighbourhood}/events", params) do |response|
+          response.map{|event| OldBill::V2::Neighbourhoods::Event.new(merge_session!(event))}
+        end
+      end
+      
+      
+      # @param [String] force
+      # @param [String] neighbourhood
+      # @return [Array<OldBill::V2::Neighbourhoods::PoliceOfficer>]
+      def police_officers(force, neighbourhood, params = {})
+        api_call(:get, "/#{force}/#{neighbourhood}/people", params) do |response|
+           response.map{|event| OldBill::V2::Neighbourhoods::PoliceOfficer.new(merge_session!(event))}
+         end
+      end
+      
+      
+      # @param [Float] lat
+      # @param [Float] lng
+      # @return [OldBill::V2::Neighbourhoods::Locator]
+      def locate(lat, lng, params = {})
+        api_call(:get, "/locate-neighbourhood", params.merge!({:q => "#{lat},#{lng}"})) do |response|
+           OldBill::V2::Neighbourhoods::Locator.new(merge_session!(response))
+         end
+       rescue NotFoundError
+         nil
+      end
+      
+    end
+  end
+end

data/lib/oldbill/errors.rb

@@ -0,0 +1,24 @@
+module OldBill
+  
+  # Raised when OldBill server cannot be found
+  class ServerNotFound < StandardError; end
+  
+  # Raised when OldBill returns the HTTP status code 400
+  class BadRequestError < StandardError; end
+  
+  # Raised when OldBill returns the HTTP status code 401
+  class UnauthorizedRequestError < StandardError; end
+  
+  # Raised when OldBill returns the HTTP status code 403
+  class ForbiddenError < StandardError; end
+  
+  # Raised when OldBill returns the HTTP status code 404
+  class NotFoundError < StandardError; end
+  
+  # Raised when OldBill returns the HTTP status code 405
+  class MethodNotAllowedError < StandardError; end
+  
+  # Raised when OldBill returns the HTTP status code 500
+  class InternalServerError < StandardError; end
+    
+end

data/lib/oldbill/service.rb

@@ -0,0 +1,43 @@
+module OldBill
+  class Service
+    include HTTParty
+    format :json
+    headers = {'Accept' => 'application/json'}
+    
+    # api not used is in server 
+    def initialize(server, api_version, username, password, logging = false)
+      self.class.base_uri server
+      self.class.send(:debug_output) if logging
+      self.class.basic_auth username, password
+    end
+    
+    def get(path, params = {})
+      perform_request(:get, path, params)
+    end
+      
+    private
+    def perform_request(type, path, params)
+      response = self.class.send(type, path, :query => params)
+      check_response(response)
+      response
+    rescue Errno::ECONNREFUSED, SocketError
+      raise OldBill::ServerNotFound, "Police API Server could not be found"
+    end
+    
+    # checking the status code of the response; if we are not authenticated
+    # then authenticate the session
+    # @raise [OldBill:BadRequestError] if the status code is 400
+    # @raise [OldBill:UnauthorizedRequestError] if a we get a 401
+    def check_response(response)
+      case response.code
+        when 400 then raise OldBill::BadRequestError.new "Not enough parameters to produce a valid response."
+        when 401 then raise OldBill::UnauthorizedRequestError.new "The username password could not be recognised and the request is not authorized."
+        when 403 then raise OldBill::ForbiddenError.new "The requested method is not available you do not have access"
+        when 404 then raise OldBill::NotFoundError.new "A method was requested that is not available in the API version specified"
+        when 405 then raise OldBill::MethodNotAllowedError.new "The HTTP request that was made requested an API method that can not process the HTTP method used."
+        when 500 then raise OldBill::InternalServerError.new "Internal Server Error"
+      end
+    end
+  
+  end
+end

data/lib/oldbill/session.rb

@@ -0,0 +1,85 @@
+require 'active_support/core_ext/object/to_query'
+module OldBill
+  class Session
+            
+    # accessors
+    attr_accessor :cache, :caching, :logging, :server, :expires_in, :api_version
+    
+    include OldBill::Api::Crime
+    include OldBill::Api::Neighbourhood
+    
+    # creating a session one must supply the api_key as this is always required basically
+    # @param [Hash] options
+    # @return [OldBill::Session]
+    def self.create(options = {})
+      username = options.delete(:username)
+      password = options.delete(:password)
+      raise ArgumentError.new("You need a username password") unless username && password
+      new(username, password, options)
+    end
+    
+    # @param [String] api_key
+    # @param [Hash] options
+    # default options
+    #   caching => true
+    #   expires_in => 60*60*24
+    #   cache => Moneta::Memory.new
+    #   server => "policeapi2.rkh.co.uk/api/" server has api version hmm should be param!
+    #   api_version => 2
+    #   logging => true
+    def initialize(username, password, options)
+      @username = username
+      @password = password
+      if @caching = options[:caching].nil? ? true : options.delete(:caching)
+        @expires_in = options.delete(:expires_in) || 60*60*24
+        @cache = options.delete(:cache) || Moneta::Memory.new 
+      end
+      @server = options.delete(:server) || "policeapi2.rkh.co.uk/api"
+      @api_version = options.delete(:api_version) || 2
+      @logging = options[:logging].nil? ? false : options.delete(:logging)
+    end
+    
+    def api_call(method, path, params ={}, &proc)
+      if cache = caching? && (@cache[cache_key(path, params)])
+        return cache
+      else
+        result = service.send(method, path, params)
+        result = yield result if block_given?
+        store_call(result, path, params || {}) if caching?
+        result
+      end
+    end
+    
+    def service 
+      @service ||= OldBill::Service.new(@server, @api_version, @username, @password, @logging)
+    end
+    
+    def caching?
+      @caching
+    end
+      
+    protected
+    # @param [String] path
+    # @param [Hash] params
+    # @return [String] the cache key from the path and the params
+    def cache_key(path, params = {})
+      parts = []
+      parts << path
+      parts << params.to_query
+      parts.join("/")
+    end
+    
+    # @param [Object] result
+    # @param [String] path
+    # @param [Hash] params
+    def store_call(result, path, params)
+      key = cache_key(path, params ||{})
+      @cache.store(key, result, :expires_in => @expires_in)
+    end
+    
+    def merge_session!(hash)
+      hash.merge({:session => self})
+    end
+            
+  end
+end

data/lib/oldbill/v2/crime_by_month.rb

@@ -0,0 +1,30 @@
+module OldBill
+  module V2
+    class CrimeByMonth < Hashie::Trash
+      
+      def self.property(property_name, options = {})
+        if options[:from] && options[:from] =~ /-/
+          translations << options[:from].to_sym
+          define_method "#{options[:from]}=" do |val|
+            self[:"#{property_name}"] = val
+          end
+          options.delete(:from)
+          super(property_name, options)
+        else
+          super
+        end
+      end
+      
+      property :month
+      property :robbery
+      property :burglary
+      property :anti_social_behaviour, :from => "anti-social-behaviour"
+      property :other_crime, :from => "other-crime"
+      property :all_crime, :from => "all-crime"
+      property :vehicle_crime, :from => "vehicle-crime"
+      property :violent_crime, :from => "violent-crime"
+      property :session
+    
+    end
+  end
+end

data/lib/oldbill/v2/crimes/location.rb

@@ -0,0 +1,34 @@
+module OldBill
+  module V2
+    module Crimes
+      class Location < Hashie::Dash
+        
+      
+        property :name	#Name if available
+        property :longitude	#Location longitude
+        property :latitude	#Location latitude
+        property :street	#Location latitude
+        
+        # id  Unique identifier for the street
+        # name  Name of the location.
+        # This is only an approximation of where the crime happened
+        def street_parsed(value)
+          unless value.nil?
+            Hashie::Mash.new(value)
+          end
+        end
+        
+
+        def []=(property, value)
+          case property 
+            when "street"
+            super(property.to_s, street_parsed(value))
+          else
+            super
+          end
+        end
+      
+      end
+    end
+  end
+end

data/lib/oldbill/v2/crimes/street_level.rb

@@ -0,0 +1,32 @@
+module OldBill
+  module V2
+    module Crimes
+      class StreetLevel < Hashie::Dash
+        
+        property :category	#Category of the crime
+        property :id	#ID of the crime.
+        property :context	#Extra information about the crime (if applicable)
+        property :month	#Month of the crime
+        property :location	#Month of the crime
+        property :session	#Month of the crime
+      
+        def location_parsed(value)
+          unless value.nil?
+            Location.new(value)
+          end
+        end
+        
+        # == yak!!!!! refactor me please
+        def []=(property, value)
+          case property 
+            when "location"
+            super(property.to_s, location_parsed(value))
+          else
+            super
+          end
+        end
+                
+      end
+    end
+  end
+end

data/lib/oldbill/v2/force.rb

@@ -0,0 +1,37 @@
+module OldBill
+  module V2
+    class Force < Hashie::Dash
+              
+      property :id
+      property :name
+      property :description
+      property :url	#Force website URL
+      property :title
+      property :telephone	#Force telephone number
+      property :id #	Unique force identifier
+      property :session
+      property :engagement_methods
+      
+      
+      # url Method website URL
+      # description Method description
+      # title Method title
+      def engagement_methods_parsed(value)
+        unless value.nil?
+          value.map{|engagement_method| Hashie::Mash.new(engagement_method)}
+        end
+      end
+      
+      
+      def []=(property, value)
+        case property 
+          when "engagement_methods"
+          super(property.to_s, engagement_methods_parsed(value))
+        else
+          super
+        end
+      end
+            
+    end
+  end
+end

data/lib/oldbill/v2/neighbourhood.rb

@@ -0,0 +1,98 @@
+module OldBill
+  module V2
+    class Neighbourhood < Hashie::Dash
+    
+      property :id	 #Police force specific team identifier.
+      property :url_force	#URL for the neighbourhood on the Force's website
+      property :name #Name of the neighbourhood	
+      property :url	#URL
+      property :population	#Population of the neighbourhood
+      property :description	#Description
+      property :fully_loaded, :default => false
+      property :force
+      property :links
+      property :contact_details
+      property :centre
+      property :locations
+      property :session
+      
+      # url
+      # description
+      # title
+      def links_parsed(value)
+        unless value.nil?
+          value.map{|link| Hashie::Mash.new(link)}
+        end
+      end
+      
+      # email
+      # telephone
+      def contact_details_parsed(value)
+        unless value.nil?
+          Hashie::Mash.new(value)
+        end
+      end
+      
+      # @note This may not be exactly in the centre of the neighbourhood
+      # latitude
+      # longitude
+      def centre_parsed(value)
+        unless value.nil?
+          Hashie::Mash.new(value)
+        end
+      end
+      
+      def locations_parsed(value)
+        unless value.nil?
+          value.map{|location| OldBill::V2::Neighbourhoods::Location.new(location)}
+        end
+      end
+      
+      
+      # == yak!!!!! refactor me please
+      def []=(property, value)
+        case property 
+          when "locations"
+          super(property.to_s, locations_parsed(value))
+          when "centre"
+          super(property.to_s, centre_parsed(value))
+          when "contact_details"
+          super(property.to_s, contact_details_parsed(value))
+          when "links"
+          super(property.to_s, links_parsed(value))
+        else
+          super
+        end
+      end
+      
+      # @return [Array<OldBill::Crimes::StreetLevel>]
+      def street_level_crimes
+        fully_loaded!
+        @street_level_crimes ||= session.street_level_crimes(self.centre.latitude, self.centre.longitude)
+      end
+      
+      def crimes_by_month
+        @crimes_by_month ||= session.crimes_by_month(self.force, self.neighbourhood)
+      end
+      
+      def events
+        @events ||= session.events(force,id)
+      end
+      
+      def police_officers
+        @police_officers ||= session.police_officers(self.force, self.neighbourhood)
+      end
+      
+      def fully_loaded?
+        fully_loaded
+      end
+      
+      # if not fully_loaded update its attributes
+      def fully_loaded!
+        return if fully_loaded
+        self.send(:initialize, session.neighbourhood(force, id).to_hash) # hmm calling private method I am MAD
+      end
+          
+    end
+  end
+end

data/lib/oldbill/v2/neighbourhoods/event.rb

@@ -0,0 +1,43 @@
+module OldBill
+  module V2
+    module Neighbourhoods
+      class Event < Hashie::Dash
+              
+        property :description	#Description of the event
+        property :title	#Title of the event
+        property :address	#Address of the event
+        property :type	#Type of event
+        property :contact_details 
+        property :start_date
+        property :session
+        
+        # email
+        # telephone
+        def contact_details_parsed(value)
+          unless value.nil?
+            Hashie::Mash.new(value)
+          end
+        end
+        
+        def start_date_parsed(value)
+          unless value.nil?
+            Date.parse(value)
+          end
+        end
+        
+        # == yak!!!!! refactor me please
+        def []=(property, value)
+          case property 
+            when "contact_details"
+            super(property.to_s, contact_details_parsed(value))
+            when "start_date"
+            super(property.to_s, start_date_parsed(value))
+          else
+            super
+          end
+        end
+        
+      end
+    end
+  end
+end

data/lib/oldbill/v2/neighbourhoods/location.rb

@@ -0,0 +1,19 @@
+module OldBill
+  module V2
+    module Neighbourhoods
+      class Location < Hashie::Dash
+            
+        property :name	#Name if available
+        property :longitude	#Location longitude
+        property :latitude	#Location longitude
+        property :postcode	#Postcode
+        property :address	#Location address
+        property :telephone	#Location latitude
+        property :type	#Type of location, e.g. "station" (police station)
+        property :description	#Description
+        property :session
+      
+      end
+    end
+  end
+end