ideal_postcodes 0.1.0

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/README.md

@@ -0,0 +1,49 @@
+# Ideal-Postcodes.co.uk API Wrapper
+
+Get a full list of addresses for any given UK postcode using the Ideal-Postcodes.co.uk API. We use the most accurate addressing database in the UK, Royal Mail's Postcode Address File.
+
+## Getting Started
+
+__Install it__
+
+```bash
+gem install ideal_postcodes
+```
+
+__Get an API Key__
+
+Get a key [Ideal-Postcodes.co.uk](https://ideal-postcodes.co.uk). Try out the service with the test postcode 'ID1 1QD'
+
+__Use it__
+
+Do address lookups with a few lines of Ruby
+
+```ruby
+require 'ideal_postcodes'
+
+IdealPostcodes.api_key = "your_key_goes_here"
+
+postcode = IdealPostcodes::Postcode.lookup "ID1 1QD"
+
+#	postcode.addresses =>
+#
+# [
+#		{
+#			:postcode=>"ID1 1QD",
+# 		:post_town=>"LONDON",
+# 		:line_1=>"Kingsley Hall",
+# 		:line_2=>"Powis Road",
+# 		:line_3=>""
+#		}, 
+#		... and so on
+```
+
+## Registering
+
+PAF is licensed from the Royal Mail and is, unfortunately, not free to use. Ideal Postcodes aims to be simple to use and fairly priced to use for web and mobile developers.
+
+We charge _2p_ per [external](https://ideal-postcodes.co.uk/termsandconditions#external) lookup.
+
+## Documentation
+
+More documentation can be found [here](https://ideal-postcodes.co.uk/documentation/ruby-wrapper)

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+	t.libs << "test"
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end

data/ideal-postcodes-ruby.gemspec

@@ -0,0 +1,25 @@
+$:.unshift(File.join(File.dirname(__FILE__), 'lib'))
+
+require 'idealpostcodes/version'
+
+spec = Gem::Specification.new do |s|
+  s.name = 'ideal_postcodes'
+  s.version = IdealPostcodes::VERSION
+  s.summary = 'Wrapper for the Ideal-Postcodes.co.uk API'
+  s.description = 'Ideal Postcodes is a simple postcode lookup API for UK addresses.  See https://ideal-postcodes.co.uk'
+  s.authors = ['Chris Blanchard']
+  s.email = ['cablanchard@gmail.com']
+  s.homepage = 'https://ideal-postcodes.co.uk/documentation'
+
+  s.add_dependency('rest-client', '~> 1.6')
+  s.add_dependency('multi_json', '~> 1.7.9')
+
+  s.add_development_dependency('mocha', '~> 0.14.0')
+  s.add_development_dependency('test-unit')
+  s.add_development_dependency('shoulda', '~> 3.5.0')
+  s.add_development_dependency('rake')
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- test/*`.split("\n")
+  s.require_paths = ['lib']
+end

data/lib/ideal_postcodes.rb

@@ -0,0 +1,2 @@
+# Allows to reference by ideal_postcodes
+require 'idealpostcodes'

data/lib/idealpostcodes.rb

@@ -0,0 +1,91 @@
+require 'rest-client'
+require 'uri'
+require 'multi_json'
+require 'cgi'
+require 'idealpostcodes/version'
+require 'idealpostcodes/postcode'
+require 'idealpostcodes/util'
+require 'idealpostcodes/errors'
+
+module IdealPostcodes
+	@base_url = 'https://api.ideal-postcodes.co.uk'
+	@version = '1'
+
+	class << self
+		attr_accessor :api_key, :base_url, :version
+	end
+
+	def self.request(method, path, params = {})
+		unless @api_key
+			raise IdealPostcodes::AuthenticationError.new('No API Key provided. ' +
+				'Set your key with IdealPostcodes.api_key = #your_key')
+		end
+
+		url = URI.parse(resource_url(path))
+		params.merge! api_key: @api_key
+		url.query = Util.merge_params(params)
+		request_options = {
+			method: method.downcase.to_sym,
+			url: url.to_s
+		}
+
+		begin
+			response = generate_request(request_options)
+		rescue RestClient::ExceptionWithResponse => error
+			if rcode = error.http_code && rbody = error.http_body
+				handle_error(rcode, rbody)
+			else
+				handle_client_error(error)
+			end
+		rescue RestClient::Exception, Errno::ECONNREFUSED => error
+			handle_client_error(e)
+		end
+		parse response.body
+	end
+
+	private
+
+	def self.resource_url(path='')
+		URI.escape "#{@base_url}/v#{@version}/#{path}"
+	end
+
+	def self.generate_request(options)
+		RestClient::Request.execute(options)
+	end
+
+	def self.parse(response)
+		begin
+      Util.keys_to_sym MultiJson.load(response)
+    rescue MultiJson::DecodeError => e
+      raise handle_client_error(e)
+    end
+	end
+
+	def self.handle_error(http_code, http_body)
+    error = parse http_body
+
+		ideal_code, ideal_message = error[:code], error[:message]
+		
+		case ideal_code
+		when 4010
+			raise AuthenticationError.new ideal_message, http_code, http_body, ideal_code
+		when 4020
+			raise TokenExhaustedError.new ideal_message, http_code, http_body, ideal_code
+		when 4021
+			raise LimitReachedError.new ideal_message, http_code, http_body, ideal_code
+		when 4040
+			raise ResourceNotFoundError.new ideal_message, http_code, http_body, ideal_code
+		else
+			raise IdealPostcodesError.new ideal_message, http_code, http_body, ideal_code
+		end
+	end
+
+	def self.handle_client_error(error)
+		raise IdealPostcodesError.new("An unexpected error occured: #{error.message})")
+	end
+
+	def self.general_error(response_code, response_body)
+		IdealPostcodesError.new "Invalid response object", response_code, response_body
+	end
+
+end

data/lib/idealpostcodes/errors.rb

@@ -0,0 +1,33 @@
+module IdealPostcodes
+	class IdealPostcodesError < StandardError
+		attr_reader :message
+		attr_reader :http_code
+		attr_reader :http_body
+		attr_reader :response_code
+
+		def initialize(message = nil, http_code = nil, http_body = nil, response_code = nil)
+			@message = message
+			@http_code = http_code
+			@http_body = http_body
+			@response_code = response_code
+		end
+
+		def to_s
+			status = @http_code.nil? ? "" : "#{@http_code} error."
+			ideal_code = @response_code.nil ? "" : "(#{@response_code})"
+			"#{status} error. (#{ideal_code}) #{message}"
+		end
+	end
+
+	class AuthenticationError< IdealPostcodesError
+	end
+
+	class TokenExhaustedError < IdealPostcodesError
+	end
+
+	class LimitReachedError < IdealPostcodesError
+	end
+
+	class ResourceNotFoundError < IdealPostcodesError
+	end
+end

data/lib/idealpostcodes/postcode.rb

@@ -0,0 +1,35 @@
+module IdealPostcodes
+	class Postcode
+
+		attr_reader :postcode_data, :postcode, :addresses
+
+		def initialize(postcode = nil, postcode_data = nil)
+			@raw = postcode_data
+			@addresses = (postcode_data.nil? || postcode_data[:result].nil?) ? [] : postcode_data[:result]
+			@postcode = postcode
+		end
+
+		def self.lookup(postcode)
+			begin
+				response = IdealPostcodes.request :get, "postcodes/#{postcode}"
+			rescue IdealPostcodes::ResourceNotFoundError => error
+				raise error unless error.response_code == 4040
+				response = nil
+			end
+			new postcode, response
+		end
+
+		def empty?
+			@raw.nil?
+		end
+
+		def addresses
+			@addresses
+		end
+
+		def to_s
+			addresses.to_s
+		end
+
+	end
+end

data/lib/idealpostcodes/util.rb

@@ -0,0 +1,29 @@
+module IdealPostcodes
+	class Util
+
+		def self.merge_params(hash)
+			result = []
+			hash.each do |key, value|
+				result << "#{CGI.escape(key.to_s)}=#{CGI.escape(value)}"
+			end
+			result.join("&")
+		end
+
+		def self.keys_to_sym(object)
+			case object
+			when Hash
+				temp = {}
+				object.each do |key, value|
+					key = (key.to_sym rescue key) || key
+          temp[key] = keys_to_sym(value)
+				end
+				temp
+			when Array
+				object.map { |elem| keys_to_sym(elem) }
+			else
+				object
+			end
+		end
+
+	end
+end

data/lib/idealpostcodes/version.rb

@@ -0,0 +1,3 @@
+module IdealPostcodes
+	VERSION = '0.1.0'
+end

data/test/test_helper.rb

@@ -0,0 +1,77 @@
+require 'test/unit'
+require 'mocha/setup'
+require 'ideal_postcodes'
+require 'shoulda'
+
+module IdealPostcodes
+
+	attr_accessor :mock
+
+	def self.mock=(mock)
+		@mock = mock
+	end
+
+	def self.generate_request(options)
+		method = options[:method]
+		url = options[:url]
+		@mock.execute method, url
+	end
+
+end
+
+def test_response(body, status=200)
+	body = MultiJson.dump(body)
+	m = mock
+	m.instance_variable_set('@instance_vals', {code: status, body: body})
+	def m.body; @instance_vals[:body]; end
+	def m.code; @instance_vals[:code]; end
+	m
+end
+
+def test_postcode
+	"ID11QD"
+end
+
+def valid_postcode(params={})
+	{
+		result: [
+			{
+				postcode: "ID1 1QD",
+				post_town: "LONDON",
+				line_1: "Kingsley Hall",
+				line_2: "Powis Road",
+				line_3: ""
+			}
+		],
+		message: "Success",
+		code: 2000 
+	}
+end
+
+def invalid_postcode
+	{
+		message: "Postcode not found",
+		code: 4040
+	}
+end
+
+def invalid_token
+	{
+		message: "Invalid key",
+		code: 4010 
+	}
+end
+
+def limit_reached
+	{
+		code: 4021,
+		message: "Lookup Limit Reached"
+	}
+end
+
+def token_exhausted
+	{
+		code: 4020,
+		message: "Token exhausted"
+	}
+end

data/test/test_ideal_postcodes.rb

@@ -0,0 +1,78 @@
+require File.expand_path('../test_helper', __FILE__)
+
+class TestIdealPostcodes < Test::Unit::TestCase
+	include Mocha
+
+	context "API" do
+
+		setup do
+			@mock = mock
+			IdealPostcodes.mock = @mock
+		end
+
+		teardown do
+			IdealPostcodes.mock = nil
+		end
+
+		should "raise an exception if no API key set" do
+			IdealPostcodes.api_key = nil
+			assert_raises IdealPostcodes::AuthenticationError do
+				postcode = IdealPostcodes::Postcode.lookup(test_postcode)
+			end
+		end
+
+		should "raise an exception if authentication failed" do
+			IdealPostcodes.api_key = "BOGUS"
+			response = test_response invalid_token
+			assert_raises IdealPostcodes::AuthenticationError do
+				@mock.expects(:execute).raises(RestClient::ExceptionWithResponse.new(response, 401))
+				IdealPostcodes::Postcode.lookup(test_postcode)
+			end
+		end
+
+		context "Valid API key" do
+
+			setup do
+				IdealPostcodes.api_key = "correctkey"
+			end
+
+			teardown do
+				IdealPostcodes.api_key = nil
+			end
+
+			should "raise an exception if tokens exhausted" do
+				response = test_response token_exhausted
+				assert_raises IdealPostcodes::TokenExhaustedError do
+					@mock.expects(:execute).raises(RestClient::ExceptionWithResponse.new(response, 402))
+					IdealPostcodes::Postcode.lookup(test_postcode)
+				end
+			end
+
+			should "raise an exception if limit has been breached" do
+				response = test_response limit_reached
+				assert_raises IdealPostcodes::LimitReachedError do
+					@mock.expects(:execute).raises(RestClient::ExceptionWithResponse.new(response, 402))
+					IdealPostcodes::Postcode.lookup(test_postcode)
+				end
+			end
+
+			should "return postcode object with addresses for valid postcode" do
+				response = test_response valid_postcode
+				@mock.expects(:execute).returns(response)
+				postcode = IdealPostcodes::Postcode.lookup(test_postcode)
+				assert_equal postcode.empty?, false
+				assert_equal postcode.addresses, valid_postcode[:result]
+			end
+
+			should "return postcode object with empty array for non-existent postcode" do
+				response = test_response invalid_postcode
+				@mock.expects(:execute).raises(RestClient::ExceptionWithResponse.new(response, 404))
+				postcode = IdealPostcodes::Postcode.lookup(test_postcode)
+				assert_equal postcode.empty?, true
+			end
+
+		end
+
+	end
+
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: ideal_postcodes
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Chris Blanchard
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.9
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.5.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ideal Postcodes is a simple postcode lookup API for UK addresses.  See
+  https://ideal-postcodes.co.uk
+email:
+- cablanchard@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- Rakefile
+- ideal-postcodes-ruby.gemspec
+- lib/ideal_postcodes.rb
+- lib/idealpostcodes.rb
+- lib/idealpostcodes/errors.rb
+- lib/idealpostcodes/postcode.rb
+- lib/idealpostcodes/util.rb
+- lib/idealpostcodes/version.rb
+- test/test_helper.rb
+- test/test_ideal_postcodes.rb
+homepage: https://ideal-postcodes.co.uk/documentation
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Wrapper for the Ideal-Postcodes.co.uk API
+test_files:
+- test/test_helper.rb
+- test/test_ideal_postcodes.rb