postcodes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4ca63fb1e521a07e8d555646be9f4133ff741fa8
+  data.tar.gz: 5883e86c9cce783fbc293d26dfcd7fcde377abb1
+SHA512:
+  metadata.gz: df0c13a6702cc09f0db334b01cd9368d6b04fabf3bec8b0b6f8071f94ccc672e702aed5803061e1b8c57713596cd81e6245c08c7c5e74fdb8e0f09c3ea6d2f37
+  data.tar.gz: 27a3591660a99b014685dc234bf4ab09469e23372ac1a9ced7641b5a36002dae88327e943c41000c45ed34837206278ccb5f9e7f5640350afb03cf17e0ce7cfc

data/Gemfile

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

data/README.md

@@ -0,0 +1,49 @@
+# Open Postcodes API Ruby Wrapper
+
+Retrieve a list of addresses for any postcode in the United Kingdom using the Open Postcodes API.
+
+## Getting Started
+
+__Installation__
+
+```bash
+gem install postcodes
+```
+
+__Get an API Key__
+
+Get a key at [Open Postcodes](https://openpostcodes.com), then try out our service with our testing postcodes e.g. 'XA1 0XX'
+
+__Implement it__
+
+You can complete a full address lookup with just a couple of lines of Ruby.
+
+```ruby
+require 'postcodes'
+
+Postcodes.api_key = "your_key_here"
+
+postcode = Postcodes::Postcode.lookup "XA1 0XX"
+
+#	postcode.addresses =>
+#
+# [
+#		{
+#			:postcode=>"XA1 0XX",
+# 		:post_town=>"LONDON",
+# 		:line_1=>"The Pavilion",
+# 		:line_2=>"Oaks Avenue",
+# 		:line_3=>""
+#		}, 
+#		... and so on
+```
+
+## Registering
+
+Open Postcodes provides street level address data for website, mobile and desktop applications at a competitive price.
+
+We charge _1p_ per public lookup; take a look at our [pricing](https://openpostcodes.com/pricing)
+
+## Documentation
+
+More in-depth documentation can be found [here](https://openpostcodes.com/documentation#examples-ruby)

data/lib/postcodes.rb

@@ -0,0 +1,94 @@
+require 'rest-client'
+require 'uri'
+require 'multi_json'
+require 'cgi'
+require 'postcodes/postcode'
+require 'postcodes/util'
+require 'postcodes/errors'
+
+module Postcodes
+	@base_url = 'https://api.openpostcodes.com'
+	@version = '1'
+
+	class << self
+		attr_accessor :api_key, :base_url, :version
+	end
+
+	def self.request(method, path, params = {})
+		unless @api_key
+			raise Postcodes::AuthenticationError.new('No API Key provided. ' +
+				'Set your API key using Postcodes.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
+
+		opc_code, opc_message = error[:code], error[:message]
+		
+		case opc_code
+		when 4010
+			raise AuthenticationError.new opc_message, http_code, http_body, opc_code
+		when 4011
+			raise RefererExcludedError.new opc_message, http_code, http_body, opc_code
+		when 4020
+			raise TokenExhaustedError.new opc_message, http_code, http_body, opc_code
+		when 4021
+			raise LimitReachedError.new opc_message, http_code, http_body, opc_code
+		when 4040
+			raise ResourceNotFoundError.new opc_message, http_code, http_body, opc_code
+		when 4220
+			raise InvalidInputError.new opc_message, http_code, http_body, opc_code
+		else
+			raise PostcodesError.new opc_message, http_code, http_body, opc_code
+		end
+	end
+
+	def self.handle_client_error(error)
+		raise PostcodesError.new("Unexpected error occurred: #{error.message})")
+	end
+
+	def self.general_error(response_code, response_body)
+		PostcodesError.new "Invalid response object", response_code, response_body
+	end
+
+end

data/lib/postcodes/errors.rb

@@ -0,0 +1,39 @@
+module Postcodes
+	class PostcodesError < 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."
+			opc_code = @response_code.nil ? "" : "(#{@response_code})"
+			"#{status} error. (#{opc_code}) #{message}"
+		end
+	end
+
+	class AuthenticationError < PostcodesError
+	end
+	
+	class RefererExcludedError < PostcodesError
+	end
+
+	class TokenExhaustedError < PostcodesError
+	end
+
+	class LimitReachedError < PostcodesError
+	end
+
+	class ResourceNotFoundError < PostcodesError
+	end
+
+	class InvalidInputError < PostcodesError
+	end
+end

data/lib/postcodes/postcode.rb

@@ -0,0 +1,35 @@
+module Postcodes
+	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 = Postcodes.request :get, "postcodes/#{postcode}"
+			rescue Postcodes::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/postcodes/util.rb

@@ -0,0 +1,29 @@
+module Postcodes
+	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

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: postcodes
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Open Postcodes
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.9
+description: Open Postcodes provides a postcode lookup API for UK addresses. More
+  information https://openpostcodes.com
+email:
+- support@openpostcodes.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- lib/postcodes.rb
+- lib/postcodes/errors.rb
+- lib/postcodes/postcode.rb
+- lib/postcodes/util.rb
+homepage: https://openpostcodes.com
+licenses:
+- Public Domain
+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.0.14
+signing_key: 
+specification_version: 4
+summary: A wrapper for the OpenPostcodes.com API
+test_files: []