ideal_postcodes 0.1.1 → 1.0.0

data/lib/idealpostcodes.rb

@@ -1,18 +1,24 @@
-require 'rest-client'
-require 'uri'
-require 'multi_json'
 require 'cgi'
+require 'uri'
+require 'json'
+require 'rest-client'
 require 'idealpostcodes/version'
-require 'idealpostcodes/postcode'
+
+# Require utility libraries
 require 'idealpostcodes/util'
 require 'idealpostcodes/errors'
 
+# Require Resources
+require 'idealpostcodes/key'
+require 'idealpostcodes/address'
+require 'idealpostcodes/postcode'
+
 module IdealPostcodes
 	@base_url = 'https://api.ideal-postcodes.co.uk'
 	@version = '1'
 
 	class << self
-		attr_accessor :api_key, :base_url, :version
+		attr_accessor :api_key, :base_url, :version, :secret
 	end
 
 	def self.request(method, path, params = {})
@@ -38,11 +44,26 @@ module IdealPostcodes
 				handle_client_error(error)
 			end
 		rescue RestClient::Exception, Errno::ECONNREFUSED => error
-			handle_client_error(e)
+			handle_client_error(error)
 		end
 		parse response.body
 	end
 
+	def self.apply_secret(secret)
+		@secret = secret
+	end
+
+	def self.key_available
+		response = Key.lookup @api_key
+		response[:available]
+	end
+
+	def self.key_details
+		raise IdealPostcodes::AuthenticationError.new('No Secret Key provided. ' +
+				'Set your secret key with IdealPostcodes.apply_secret #your_key') if @secret.nil?
+		response = Key.lookup_details @api_key, @secret
+	end
+
 	private
 
 	def self.resource_url(path='')
@@ -55,8 +76,8 @@ module IdealPostcodes
 
 	def self.parse(response)
 		begin
-      Util.keys_to_sym MultiJson.load(response)
-    rescue MultiJson::DecodeError => e
+      Util.keys_to_sym JSON.parse(response)
+    rescue JSON::ParserError => e
       raise handle_client_error(e)
     end
 	end
@@ -85,7 +106,7 @@ module IdealPostcodes
 	end
 
 	def self.general_error(response_code, response_body)
-		IdealPostcodesError.new "Invalid response object", response_code, response_body
+		IdealPostcodesError.new 'Invalid response object', response_code, response_body
 	end
 
 end

data/lib/idealpostcodes/address.rb

@@ -0,0 +1,31 @@
+module IdealPostcodes
+	module Address
+		class SearchResult
+			attr_reader :page, :limit, :addresses
+			def initialize response
+				@page = response[:result][:page]
+				@limit = response[:result][:limit]
+				@addresses = response[:result][:hits]
+			end
+		end
+
+		def self.lookup udprn
+			begin
+				response = IdealPostcodes.request :get, "addresses/#{udprn}"
+				address = response[:result]
+			rescue IdealPostcodes::IdealPostcodesError => error
+				raise error unless error.response_code == 4044
+				address = nil
+			end
+			address
+		end
+
+		def self.search search_term, options = {}
+			query = { query: search_term }
+			query[:limit] = options[:limit] unless options[:limit].nil?
+			query[:page] = options[:page] unless options[:page].nil?
+			response = IdealPostcodes.request :get, "addresses", query
+			SearchResult.new response
+		end
+	end
+end

data/lib/idealpostcodes/key.rb

@@ -0,0 +1,13 @@
+module IdealPostcodes
+	module Key
+		def self.lookup api_key
+			response = IdealPostcodes.request :get, "keys/#{api_key}"
+			response[:result]
+		end
+
+		def self.lookup_details api_key, secret
+			response = IdealPostcodes.request :get, "keys/#{api_key}", { user_token: secret }
+			response[:result]
+		end
+	end
+end

data/lib/idealpostcodes/postcode.rb

@@ -1,35 +1,22 @@
 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)
+	module Postcode
+		def self.lookup postcode
 			begin
 				response = IdealPostcodes.request :get, "postcodes/#{postcode}"
+				addresses = response[:result]
 			rescue IdealPostcodes::ResourceNotFoundError => error
 				raise error unless error.response_code == 4040
-				response = nil
+				addresses = []
 			end
-			new postcode, response
+			addresses
 		end
 
-		def empty?
-			@raw.nil?
+		def self.find_by_location geolocation
+			query = {lonlat: "#{geolocation[:longitude]},#{geolocation[:latitude]}"}
+			query[:limit] = geolocation[:limit] unless geolocation[:limit].nil?
+			query[:radius] = geolocation[:radius] unless geolocation[:radius].nil?
+			response = IdealPostcodes.request :get, 'postcodes', query
+			response[:result]
 		end
-
-		def addresses
-			@addresses
-		end
-
-		def to_s
-			addresses.to_s
-		end
-
 	end
 end

data/lib/idealpostcodes/util.rb

@@ -4,9 +4,9 @@ module IdealPostcodes
 		def self.merge_params(hash)
 			result = []
 			hash.each do |key, value|
-				result << "#{CGI.escape(key.to_s)}=#{CGI.escape(value)}"
+				result << "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
 			end
-			result.join("&")
+			result.join('&')
 		end
 
 		def self.keys_to_sym(object)

data/lib/idealpostcodes/version.rb

@@ -1,3 +1,3 @@
 module IdealPostcodes
-	VERSION = '0.1.1'
+	VERSION = '1.0.0'
 end

data/spec/addresses_spec.rb

@@ -0,0 +1,68 @@
+require 'spec_helper'
+
+describe IdealPostcodes::Address do
+	describe '.lookup' do
+		it 'returns an address for a valid UDPRN' do
+			address = IdealPostcodes::Address.lookup 0
+			expect(is_address(address)).to eq(true)
+		end
+		it 'returns nil for an invalid UDPRN' do
+			address = IdealPostcodes::Address.lookup -1
+			expect(address).to be_nil
+		end
+		it 'raises an exception if invalid key' do
+			IdealPostcodes.api_key = 'foo'
+			expect {
+				IdealPostcodes::Address.lookup 0
+			}.to raise_error(IdealPostcodes::AuthenticationError)
+		end
+		it 'raises an exception if no lookups remaining' do
+			expect {
+				IdealPostcodes::Address.lookup -2
+			}.to raise_error(IdealPostcodes::TokenExhaustedError)
+		end
+		it 'raises an exception if limit breached' do
+			expect {
+				IdealPostcodes::Address.lookup -3
+			}.to raise_error(IdealPostcodes::LimitReachedError)
+		end
+	end	
+
+	describe '.search' do
+		it 'returns results in a SearchResult object' do
+			results = IdealPostcodes::Address.search "ID1 1QD"
+			expect(results).to be_a(IdealPostcodes::Address::SearchResult)
+			expect(results.addresses.length).to be > 0
+			results.addresses.each do |address|
+				expect(is_address(address)).to eq(true)
+			end
+		end
+		it 'is sensitive to limit' do
+			limit = 1
+			results = IdealPostcodes::Address.search "High Street", limit: limit
+			expect(results.addresses.length).to equal(limit)
+			expect(results.limit).to equal(limit)
+		end
+		it 'is sensitive to page' do
+			page = 1
+			results = IdealPostcodes::Address.search "High Street", page: page
+			expect(results.page).to equal(page)
+		end
+		it 'raises an exception if invalid key' do
+			IdealPostcodes.api_key = 'foo'
+			expect {
+				results = IdealPostcodes::Address.search "ID1 1QD"
+			}.to raise_error(IdealPostcodes::AuthenticationError)
+		end
+		it 'raises an exception if no lookups remaining' do
+			expect {
+				results = IdealPostcodes::Address.search "ID1 CLIP"
+			}.to raise_error(IdealPostcodes::TokenExhaustedError)
+		end
+		it 'raises an exception if limit breached' do
+			expect {
+				results = IdealPostcodes::Address.search "ID1 CHOP"
+			}.to raise_error(IdealPostcodes::LimitReachedError)
+		end
+	end
+end

data/spec/idealpostcodes_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe IdealPostcodes do
+	describe '#request' do
+		it 'generates a HTTP request' do
+			response = IdealPostcodes.request :get, 'postcodes/ID1 1QD'
+			expect(response[:code]).to eq(2000)
+		end
+		it 'raises an error if no key is provided' do
+			IdealPostcodes.api_key = nil
+			expect do
+				response = IdealPostcodes.request :get, 'postcodes/ID1 1QD'
+			end.to raise_error(IdealPostcodes::AuthenticationError)
+		end
+		it 'raises authentication error if invalid key is provided' do
+			IdealPostcodes.api_key = 'foo'
+			expect do
+				response = IdealPostcodes.request :get, 'postcodes/ID1 1QD'
+			end.to raise_error(IdealPostcodes::AuthenticationError)
+		end
+		it 'raises token exhausted error if key balance is depleted' do
+			expect do
+				response = IdealPostcodes.request :get, 'postcodes/ID1 CLIP'
+			end.to raise_error(IdealPostcodes::TokenExhaustedError)
+		end
+		it 'raises limit reached error if a limit has been breached' do
+			expect do
+				response = IdealPostcodes.request :get, 'postcodes/ID1 CHOP'
+			end.to raise_error(IdealPostcodes::LimitReachedError)
+		end
+	end
+
+	describe '.key_available' do
+		it 'returns true if key is available' do
+			IdealPostcodes.api_key = "iddqd"
+			expect(IdealPostcodes.key_available).to equal(true)
+		end
+		it 'returns false if key is unavailable' do
+			IdealPostcodes.api_key = "idkfa"
+			expect(IdealPostcodes.key_available).to equal(false)
+		end
+	end
+
+	describe '.key_details' do
+		it 'raises an exception if no secret is provided' do
+			expect {
+				IdealPostcodes.key_details
+			}.to raise_error(IdealPostcodes::AuthenticationError)
+		end
+		it 'returns key information' do
+			IdealPostcodes.apply_secret(secret_key)
+			response = IdealPostcodes.key_details
+			expect(is_key(response)).to eq(true)
+		end
+	end
+end

data/spec/keys_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+describe IdealPostcodes::Key do
+	describe '.lookup' do
+		it 'returns the availability status of a key (true key)' do
+			result = IdealPostcodes::Key.lookup "iddqd"
+			expect(result[:available]).to eq(true)
+		end
+		it 'returns the availability status of a key (false key)' do
+			result = IdealPostcodes::Key.lookup "idkfa"
+			expect(result[:available]).to eq(false)
+		end
+	end	
+
+	describe '.lookup_details' do
+		it 'returns key details' do
+			result = IdealPostcodes::Key.lookup_details "gandhi", secret_key
+			expect(result[:lookups_remaining]).to_not be_nil
+			expect(result[:daily_limit]).to_not be_nil
+			expect(result[:individual_limit]).to_not be_nil
+			expect(result[:allowed_urls]).to_not be_nil
+			expect(result[:notifications]).to_not be_nil
+		end
+	end
+end

data/spec/postcodes_spec.rb

@@ -0,0 +1,66 @@
+require 'spec_helper'
+
+describe IdealPostcodes::Postcode do
+	describe '.lookup' do
+		it 'returns a list of addresses for a postcode' do
+			addresses = IdealPostcodes::Postcode.lookup 'ID1 1QD'
+			expect(addresses.length).to be > 0
+			addresses.each do |address|
+				expect(is_address(address)).to eq(true)
+				expect(address[:postcode]).to eq('ID1 1QD')
+			end
+		end
+		it 'returns an empty array if postcode does not exist' do
+			addresses = IdealPostcodes::Postcode.lookup 'ID1 KFA'
+			expect(addresses.length).to eq(0)
+		end
+		it 'raises an exception if key has run out of balance' do
+			expect {
+				IdealPostcodes::Postcode.lookup 'ID1 CLIP'
+			}.to raise_error(IdealPostcodes::TokenExhaustedError)
+		end
+		it 'raises an exception if limit has been reached' do
+			expect {
+				IdealPostcodes::Postcode.lookup 'ID1 CHOP'
+			}.to raise_error(IdealPostcodes::LimitReachedError)
+		end
+		it 'raises an exception if invalid key' do
+			IdealPostcodes.api_key = 'foo'
+			expect {
+				IdealPostcodes::Postcode.lookup 'ID1 1QD'
+			}.to raise_error(IdealPostcodes::AuthenticationError)
+		end
+	end
+	describe '.find_by_location' do
+		it 'returns an array of postcodes and locations' do
+			lon = 0.6298
+			lat = 51.7923
+			postcodes = IdealPostcodes::Postcode.find_by_location longitude: lon, latitude: lat
+			expect(postcodes.length).to be > 0
+			postcodes.each do |postcode|
+				expect(is_postcode_location(postcode)).to eq(true)
+			end
+		end
+		it 'returns an empty array if no results are found' do
+			lon = 0
+			lat = 0
+			postcodes = IdealPostcodes::Postcode.find_by_location longitude: lon, latitude: lat
+			expect(postcodes).to be_a(Array)
+			expect(postcodes.length).to eq(0)
+		end
+		it 'is sensitive to limit parameter' do
+			lon = 0.6298
+			lat = 51.7923
+			limit = 1
+			postcodes = IdealPostcodes::Postcode.find_by_location longitude: lon, latitude: lat, limit: limit
+			expect(postcodes.length).to eq(limit)
+		end
+		it 'is sensitive to radius parament' do
+			lon = 0.6298
+			lat = 51.7923
+			small_radius = IdealPostcodes::Postcode.find_by_location longitude: lon, latitude: lat, radius: 10
+			large_radius = IdealPostcodes::Postcode.find_by_location longitude: lon, latitude: lat, radius: 100
+			expect(large_radius.length > small_radius.length).to eq(true)
+		end
+	end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,65 @@
+# Enable VCR
+require 'vcr'
+
+VCR.configure do |c|
+	c.cassette_library_dir = 'spec/vcr_cassettes'
+	c.hook_into :webmock
+end
+
+# Configure Ideal Postcodes lib
+require 'ideal_postcodes'
+
+RSpec.configure do |c|
+	c.before(:each) do
+    IdealPostcodes.base_url = 'https://localhost:1337'
+		IdealPostcodes.api_key = "gandhi"
+		IdealPostcodes.apply_secret nil
+  end
+
+	c.around(:each) do |example|
+		VCR.use_cassette(example.metadata[:full_description]) do
+			example.run
+		end
+	end
+end
+
+def contains_attributes attribute_list, target
+	result = true
+	attribute_list.each do |attribute|
+		result = false if target[attribute].nil?
+	end
+	result
+end
+
+def postcode_location_elements
+	[:postcode, :longitude, :latitude, :northings, :eastings]
+end
+
+def is_postcode_location(postcode)
+	contains_attributes postcode_location_elements, postcode
+end
+
+def address_elements
+	[:postcode, :postcode_inward, :postcode_outward, :post_town, :dependant_locality, 
+		:double_dependant_locality, :thoroughfare, :dependant_thoroughfare, 
+		:building_number, :building_name, :sub_building_name, :po_box, :department_name, 
+		:organisation_name, :udprn, :postcode_type, :su_organisation_indicator, 
+		:delivery_point_suffix, :line_1, :line_2, :line_3, :premise, :county, 
+		:district, :ward, :longitude, :latitude, :eastings, :northings]
+end
+
+def is_address(address)
+	contains_attributes address_elements, address
+end
+
+def key_elements
+	[:lookups_remaining, :daily_limit, :individual_limit, :allowed_urls, :notifications]
+end
+
+def is_key(key)
+	contains_attributes key_elements, key
+end
+
+def secret_key
+	"uk_hxp6ouk0rmyXoobVJnehrsQcdvTfb"
+end