geocodable 0.0.1

data/lib/geocodable.rb

@@ -0,0 +1,21 @@
+require 'json'
+require 'excon'
+require 'faraday'
+
+require 'geocodable/version'
+require 'geocodable/geocodable_error'
+require 'geocodable/json_parser'
+require 'geocodable/request'
+
+module Geocodable
+  @api_base = 'https://api.geocodable.io/'
+  @ssl_verify_certs = true
+
+  class << self
+    attr_accessor :api_key, :api_base, :ssl_verify_certs
+
+    def geocode(query)
+      Request.get('/v1/geocode.json', { query: query })
+    end
+  end
+end

data/lib/geocodable/geocodable_error.rb

@@ -0,0 +1,24 @@
+module Geocodable
+  class GeocodableError < StandardError
+    attr_reader :message
+    attr_reader :http_status
+    attr_reader :http_body
+
+    def initialize(message=nil, http_status=nil, http_body=nil)
+      @message = message
+      @http_status = http_status
+      @http_body = http_body
+    end
+
+    def to_s
+      str = @http_status.nil? ? '' : "HTTP Status #{@http_status} "
+      "#{str}#{@message}"
+    end
+  end
+
+  class InvalidRequestError < GeocodableError; end
+  class AuthenticationError < GeocodableError; end
+  class AccessDisabledError < GeocodableError; end
+  class OverRequestLimitError < GeocodableError; end
+  class APIError < GeocodableError; end
+end

data/lib/geocodable/json_parser.rb

@@ -0,0 +1,20 @@
+module Geocodable
+  class Request
+    class JSONParser < Faraday::Response::Middleware
+      def on_complete(env)
+        begin
+          env.body = JSON.parse(env.body, symbolize_names: true) if is_json?(env)
+        rescue JSON::ParserError
+          raise APIError.new(
+            "Invalid response object from API: #{env.body}", env.status, env.body)
+        end
+      end
+
+      private
+
+      def is_json?(env)
+        env[:response_headers]['Content-Type'].match 'application/json'
+      end
+    end
+  end
+end

data/lib/geocodable/request.rb

@@ -0,0 +1,55 @@
+module Geocodable
+  class Request
+    @ssl_bundle_path = File.dirname(__FILE__) + '/../certs/ca-certificates.crt'
+
+    class << self
+      def get(url, params={})
+        response = conn.get url, params, headers
+        handle_api_error(response) unless response.success?
+        response.body
+      end
+
+      def headers
+        hash = { user_agent: "geocodable-ruby/#{Geocodable::VERSION}" }
+        hash[:authorization] = "Bearer #{api_key}" unless api_key.nil?
+        hash
+      end
+
+      def conn
+        Faraday::Response.register_middleware json_parser: JSONParser
+        conn = Faraday.new(Geocodable.api_base, ssl: ssl) do |faraday|
+          faraday.adapter :excon
+          faraday.response :json_parser
+        end
+      end
+
+      def ssl
+        { verify: Geocodable.ssl_verify_certs, ca_file: @ssl_bundle_path }
+      end
+
+      def api_key
+        Geocodable.api_key
+      end
+
+      def handle_api_error(response)
+        code, body = response.status, response.body
+        begin
+          error = body[:errors] || body[:error]
+          error = error.first if error.kind_of? Array
+        rescue
+          raise APIError.new(
+            "Invalid response object from API: #{body.inspect}", code, body)
+        end
+
+        case code
+        when 400, 404 then raise InvalidRequestError.new(error, code, body)
+        when 401      then raise AuthenticationError.new(error, code, body)
+        when 403      then raise AccessDisabledError.new(error, code, body)
+        when 429      then raise OverRequestLimitError.new(error, code, body)
+        else
+          raise APIError.new(error, code, body)
+        end
+      end
+    end
+  end
+end

data/lib/geocodable/version.rb

@@ -0,0 +1,3 @@
+module Geocodable
+  VERSION = "0.0.1"
+end

data/spec/geocode_spec.rb

@@ -0,0 +1,104 @@
+require 'spec_helper'
+
+describe Geocodable do
+  describe '#api_key=' do
+    it 'sets the API key' do
+      Geocodable.api_key = 'abc123'
+      expect(Geocodable.api_key).to eq('abc123')
+    end
+  end
+
+  describe '#geocode' do
+    before { Geocodable.api_key = 'abc' }
+
+    it 'returns results' do
+      stub_api_request(body: '{"found": 1}')
+      resp = Geocodable.geocode('London')
+      expect(resp[:found]).to eq(1)
+    end
+
+    it 'raises InvalidRequestError with missing query param' do
+      stub_api_request(params: { query: '' },
+                       status: 400, 
+                       body: '{"errors": ["Query parameter missing"]}')
+      expect { 
+        Geocodable.geocode('')
+      }.to raise_error(Geocodable::InvalidRequestError) { |e|
+        expect(e.message).to eq('Query parameter missing')
+        expect(e.http_status).to eq(400)
+        expect(e.http_body).to eq(errors: ['Query parameter missing'])
+      }
+    end
+
+    it 'raises AuthenticationError with invalid API key' do
+      stub_api_request(headers: {},
+                       status: 401, 
+                       body: '{"errors": ["Unauthorized API key"]}')
+      Geocodable.api_key = nil
+      expect { 
+        Geocodable.geocode('London')
+      }.to raise_error(Geocodable::AuthenticationError) { |e|
+        expect(e.message).to eq('Unauthorized API key')
+        expect(e.http_status).to eq(401)
+        expect(e.http_body).to eq(errors: ['Unauthorized API key'])
+      }
+    end
+
+    it 'raises AccessDisabledError when api_key disabled' do
+      stub_api_request(status: 403, 
+                       body: '{"errors": ["API key disabled by owner"]}')
+      expect { 
+        Geocodable.geocode('London')
+      }.to raise_error(Geocodable::AccessDisabledError) { |e|
+        expect(e.message).to eq('API key disabled by owner')
+        expect(e.http_status).to eq(403)
+        expect(e.http_body).to eq(errors: ['API key disabled by owner'])
+      }
+    end
+
+    it 'raises OverRequestLimitError when api_key disabled' do
+      stub_api_request(status: 429, body: '{"errors": ["Over request limit"]}')
+      expect { 
+        Geocodable.geocode('London')
+      }.to raise_error(Geocodable::OverRequestLimitError) { |e|
+        expect(e.message).to eq('Over request limit')
+        expect(e.http_status).to eq(429)
+        expect(e.http_body).to eq(errors: ['Over request limit'])
+      }
+    end
+
+    it 'raises APIError when 500 server error' do
+      stub_api_request(status: 500, 
+                       body: '{"status":"500", "error":"Internal server error"}')
+      expect { 
+        Geocodable.geocode('London')
+      }.to raise_error(Geocodable::APIError) { |e|
+        expect(e.message).to eq('Internal server error')
+        expect(e.http_status).to eq(500)
+        expect(e.http_body).to eq(error: 'Internal server error', status: '500')
+      }
+    end
+  end
+end
+
+
+def stub_api_request(args)
+  args = { 
+    headers: { authorization: 'Bearer abc' }, 
+    params: { query: 'London' }, 
+    status: 200, 
+    body: ''
+  }.update(args)
+  query = URI.encode_www_form(args[:params])
+  args[:headers].update(
+    'Host' => 'api.geocodable.io:443', 
+    'User-Agent' => "geocodable-ruby/#{Geocodable::VERSION}"
+  )
+  stub_request(:get, "https://api.geocodable.io/v1/geocode.json?#{query}").
+    with(headers: args[:headers]).
+    to_return(
+      body: args[:body], 
+      status: args[:status], 
+      headers: { 'Content-Type' => 'application/json' }
+    )
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'geocodable'
+require 'webmock/rspec'
+
+RSpec.configure do |config|
+  config.color_enabled = true
+  config.formatter = :documentation
+end

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: geocodable
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Sam Levy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: excon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.32.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.32.1
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.1
+description: Geocodable is a UK geocoding service using Open Data
+email:
+- sam@geocodable.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- geocodable.gemspec
+- lib/certs/ca-certificates.crt
+- lib/geocodable.rb
+- lib/geocodable/geocodable_error.rb
+- lib/geocodable/json_parser.rb
+- lib/geocodable/request.rb
+- lib/geocodable/version.rb
+- spec/geocode_spec.rb
+- spec/spec_helper.rb
+homepage: http://geocodable.io/docs
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: UK geocoding API wrapper for Geocodable
+test_files:
+- spec/geocode_spec.rb
+- spec/spec_helper.rb