ideal_postcodes 0.1.1 → 2.0.1

data/lib/idealpostcodes/postcode.rb

@@ -1,35 +1,23 @@
 module IdealPostcodes
-	class Postcode
+  module Postcode
+    def self.lookup(postcode)
+      begin
+        response = IdealPostcodes.request :get, "postcodes/#{postcode}"
+        addresses = response[:result]
+      rescue IdealPostcodes::ResourceNotFoundError => e
+        raise e unless e.response_code == 4040
 
-		attr_reader :postcode_data, :postcode, :addresses
+        addresses = []
+      end
+      addresses
+    end
 
-		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
+    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
+  end
+end

data/lib/idealpostcodes/util.rb

@@ -1,29 +1,42 @@
+require 'uri'
+
 module IdealPostcodes
-	class Util
+  DEFAULT_PARSER = URI::Parser.new
 
-		def self.merge_params(hash)
-			result = []
-			hash.each do |key, value|
-				result << "#{CGI.escape(key.to_s)}=#{CGI.escape(value)}"
-			end
-			result.join("&")
-		end
+  class Util
+    def self.escape(str)
+      IdealPostcodes::DEFAULT_PARSER.escape(str)
+    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
+    def self.merge_params(hash)
+      result = []
+      hash.each do |key, value|
+        result << "#{escape(key.to_s)}=#{escape(value.to_s)}"
+      end
+      result.join('&')
+    end
 
-	end
-end
+    def self.keys_to_sym(object)
+      case object
+      when Hash
+        temp = {}
+        object.each do |key, value|
+          key =
+            (
+              begin
+                key.to_sym
+              rescue StandardError
+                key
+              end
+            ) || 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

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

data/lib/idealpostcodes.rb

@@ -1,91 +1,124 @@
-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
-	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)
+  @base_url = 'https://api.ideal-postcodes.co.uk'
+  @version = '1'
+
+  class << self
+    attr_accessor :api_key, :base_url, :version, :secret
+  end
+
+  def self.request(method, path, params = {})
+    unless @api_key
+      raise IdealPostcodes::AuthenticationError, '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 => e
+      if rcode = e.http_code && rbody = e.http_body
+        handle_error(rcode, rbody)
+      else
+        handle_client_error(e)
+      end
+    rescue RestClient::Exception, Errno::ECONNREFUSED => e
+      handle_client_error(e)
+    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
+    if @secret.nil?
+      raise IdealPostcodes::AuthenticationError, 'No Secret Key provided. ' +
+                                                 'Set your secret key with IdealPostcodes.apply_secret #your_key'
     end
-	end
+    response = Key.lookup_details @api_key, @secret
+  end
+
+  def self.resource_url(path = '')
+    IdealPostcodes::Util.escape "#{@base_url}/v#{@version}/#{path}"
+  end
 
-	def self.handle_error(http_code, http_body)
+  def self.generate_request(options)
+    RestClient::Request.execute(options)
+  end
+
+  def self.parse(response)
+    Util.keys_to_sym JSON.parse(response)
+  rescue JSON::ParserError => e
+    raise handle_client_error(e)
+  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
+    ideal_code = error[:code]
+    ideal_message = 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, "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/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,77 @@
+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,89 @@
+# Enable VCR
+require 'vcr'
+require 'webmock'
+
+WebMock.enable!
+
+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]) { example.run }
+  end
+end
+
+def contains_attributes(attribute_list, target)
+  result = true
+  attribute_list.each { |attribute| result = false if target[attribute].nil? }
+  result
+end
+
+def postcode_location_elements
+  %i[postcode longitude latitude northings eastings]
+end
+
+def is_postcode_location(postcode)
+  contains_attributes postcode_location_elements, postcode
+end
+
+def address_elements
+  %i[
+    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
+  %i[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