ideal_postcodes 0.1.1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c34b866375b1eb59033c3c9f4139ed49e1f91bd1
-  data.tar.gz: 48da9070ca6d8cb2af643879f1837d697c3a89af
+SHA256:
+  metadata.gz: 631e1f7827c1ebd216ac8da69d07f41e99dfcb542ea8db79160f81fb4e27e2f7
+  data.tar.gz: 528c592ee660794a49eaca814817181d7bb46dc67a848dd3015d9ed64023af3a
 SHA512:
-  metadata.gz: 11b659c4e56fb6188874468b2c2e8363eb7088ca13672540ced297f762f5a096f53f49f51d6b2144bc6af0a3006596e2be9e550291aff14ef15d28e6ea2e04ce
-  data.tar.gz: b64a4e49837cfad1410b382600f2af5eff9ee1fbea7a833689f1b34c021c10a75154f445e6363c0e6cc9f50ce79e2082af292f3c995b084b670301b9b12b3195
+  metadata.gz: f9f1c1c8405bad2e5f2593609a880f667f5b1b89643540e197aa79d348f1027abcfa7ca0de1c16d485861a6ab9d42471761068435b56be25584ed7cbcc269799
+  data.tar.gz: '078849bcd14507cab9dcc8263bcd823dd154d556da85065b8909b37ae5b504c51aa0d8a67b6413c487e82f5b37c4415abdab033ceb98465d450848f6a272ff8e'

data/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+on:
+  push:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: 
+          - '2.5'
+          - '2.6'
+          - '2.7'
+          - '3.0'
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+Any changes, including backwards incompatible changes will be listed here
+
+## 2.0.0 (11/10/2017)
+
+- Adds Ruby 2.4.0 support
+- Drops 1.9 support
+
+## 1.1.0 (22/6/2017)
+
+- Updated rest-client dependency
+
+## 1.0.0 
+- Major rewrite to make way for more resources
+- Breaking change applied to postcode lookup functionality
+- Implemented [addresses resource](https://ideal-postcodes.co.uk/documentation/addresses)
+- Implemented [keys resource](https://ideal-postcodes.co.uk/documentation/keys)
+- Implemented [postcodes resource](https://ideal-postcodes.co.uk/documentation/postcodes). Added location-based postcode searches
+- Swapped out test suite with rspec and vcr

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Ideal Postcodes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,57 +1,93 @@
-# Ideal-Postcodes.co.uk API Wrapper
+# Ideal Postcodes Ruby Library [![Build Status](https://travis-ci.org/ideal-postcodes/ideal-postcodes-ruby.png)](https://travis-ci.org/ideal-postcodes/ideal-postcodes-ruby)
 
-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.
+Ideal Postcodes is a simple JSON API to query UK postcodes and addresses. Find out more at [Ideal-Postcodes.co.uk](https://ideal-postcodes.co.uk/)
+
+Our API uses Royal Mail's Postcode Address File and is updated daily. Each method incurs a small charge (typically 2p) - free methods are labelled as such and are based on open data sources.
 
 ## Getting Started
 
-__Install it__
+**Install**
 
 ```bash
 gem install ideal_postcodes
 ```
 
-Alternatively for rails, include this in your gemfile and bundle install
+Alternatively, include this in your gemfile and bundle install
 
 ```ruby
 gem 'ideal_postcodes'
 ```
 
-__Get an API Key__
+**Create a Key**
 
-Get a key at [Ideal-Postcodes.co.uk](https://ideal-postcodes.co.uk). Try out the service with the test postcode 'ID1 1QD'
+Sign up at [Ideal-Postcodes.co.uk](https://ideal-postcodes.co.uk) and create a key.
 
-__Configuration__
+**Configure**
 
-In order to perform lookups, you'll need to configure the gem by passing in your api key by doing the following:
+Drop in your key when using the library.
 
 ```ruby
-require 'ideal_postcodes'
-
 IdealPostcodes.api_key = "your_key_goes_here"
 ```
 
-**For Rails**, the best way to do this is create a file in your initializers folder and drop in your key with this line of code:
+## Error Handling
+
+It's important that you lookout for common exceptions when interacting with the API. The most common exceptions can be caught as shown below.
 
 ```ruby
-IdealPostcodes.api_key = "<your key goes here>"
+begin
+  IdealPostcodes::Postcode.lookup "ID1 1QD"
+rescue IdealPostcodes::AuthenticationError => e
+	# Invalid API Key
+rescue IdealPostcodes::TokenExhaustedError => e
+	# Token has run out of lookups
+rescue IdealPostcodes::LimitReachedError => e
+	# One of your predefinied limits has been reached
+rescue IdealPostcodes::IdealPostcodesError => e
+	# API Error
+rescue => e
+	# An unexpected error
+end
+```
+
+Possible errors to look out for are listed in the [documentation](https://ideal-postcodes.co.uk/documentation/response-codes).
+
+## Methods
+
+The client provides a number of methods to allow you to get specific jobs done quickly and easily. These methods are listed below.
+
+
+
+
+## Get all addresses for a postcode [(docs)](https://ideal-postcodes.co.uk/documentation/postcodes#postcode)
+
+```
+IdealPostcodes::Postcode.lookup postcode
 ```
 
-__Usage__
+Returns an array of addresses representing all addresses at the specified postcode.
 
-Simply call #lookup class method on IdealPostcodes::Postcode. This will return a Postcode object containing the complete list of addresses if the postcode exists.
+**Arguments**
+
+- `postcode` (string). The postcode you want to lookup, case and space insensitive.
+
+**Returns**
+
+An array of hashes which represent each address at the postcode. Returns an empty array for an invalid postcode.
+
+**Example**
 
 ```ruby
-postcode = IdealPostcodes::Postcode.lookup "ID1 1QD"
+addresses = IdealPostcodes::Postcode.lookup "ID1 1QD"
 
-if postcode.empty? 
+if addresses.empty? 
 	puts "Your postcode doesn't have a match"
 else
-	postcode.addresses
+	puts addresses
 end
 
-# postcode.addresses =>
-#
-# [
+# addresses =>
+#[
 #  {
 #   :postcode => "ID1 1QD",
 #   :post_town => "LONDON",
@@ -61,44 +97,254 @@ end
 #   :organisation_name => "",
 #   :building_name => "Kingsley Hall",
 #   :udprn => 12345678
-#  }, ... and so on
+#   ... and so on
+```
+
+**Notes**
+
+**Data Source:** Royal Mail Postcode Address File. Ordnance Survey.
+
+Use the postcode "ID1 1QD" to test this method for free. The complete list of test postcodes is available in the [documentation](https://ideal-postcodes/documentation/postcodes).
+
+
+
+
+## Search for an address [(docs)](https://ideal-postcodes.co.uk/documentation/addresses#query)
+
+Perform a search for addresses which match your search term.
+
+```ruby
+IdealPostcodes::Address.search search_term, limit: 20, page: 0
 ```
 
-__Exceptions__
+**Arguments**
+
+- `search_term` (string). The address you wish to search for
+- `options` (hash, optional). Customise your search. 
+	- `limit` (number). The maximum number of returned results per page
+	-	`page` (number). Page of results to return (starts at page 0)
+
+**Returns**
 
-The wrapper will raise an exception for anything other than a 200 response or an empty 404 response (which means no addresses at postcode).
+Returns a search result object with the following attributes.
+
+- `addresses` (Array). An array of hashes which represent each address at the postcode. The array is ordered by how close the search term and address match.
+- `limit` (Number). The maximum number of returned results per page.
+- `page` (Number). The returned page of results.
+
+
+**Example**
 
 ```ruby
-begin
-  IdealPostcodes::Postcode.lookup "ID1 1QD"
-rescue IdealPostcodes::AuthenticationError => e
-	# Invalid API Key
-rescue IdealPostcodes::TokenExhaustedError => e
-	# Token has run out of lookups
-rescue IdealPostcodes::LimitReachedError => e
-	# One of your predefinied limits has been reached
-rescue IdealPostcodes::IdealPostcodesError => e
-	# API Error
-rescue => e
-	# An unexpected error
-end
+IdealPostcodes::Address.search "10 Downing Street London"
+
+r.limit # => 10
+r.page  # => 0
+r.addresses
+
+#[
+#  {
+#    :line_1=>"Prime Minister & First Lord Of The Treasury", 
+#    :line_2=>"10 Downing Street", 
+#    :line_3=>"", 
+#    :post_town=>"LONDON",  
+#    :postcode=>"SW1A 2AA", 
+#    :organisation_name=>"Prime Minister & First Lord Of The Treasury", 
+#    :premise=>"10", 
+#    :latitude=>51.5035398826274
+#    :longitude=>-0.127695242183412, 
+#    :thoroughfare=>"Downing Street", 
+#    :district=>"Westminster", 
+#    :ward=>"St James's", 
+#    :building_number=>"10", 
+#    :udprn=>23747771, 
+#	... and so on
 ```
 
-## Registering
+**Notes**
+
+Data source: Royal Mail Postcode Address File, Ordnance Survey.
+
+Use the address "ID1 1QD" to test integration for free. The complete list of test methods is available in the [documentation](https://ideal-postcodes/documentation/addresses).
 
-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)
+## Get nearby postcode for a given geolocation [(docs)](https://ideal-postcodes.co.uk/documentation/postcodes#lonlat)
+
+Retrieve the nearest postcodes for a given geolocation. Free to use.
+
+```ruby
+IdealPostcodes::Postcode.find_by_location longitude: lon, latitude: lat
+```
+
+**Arguments**
+
+- `location` (Hash)
+	- `longitude` (number, required)
+	- `latitude` (number, required)
+	- `limit` (number, optional) Maximum number of results to return 
+	- `radius` (number, optional) search radius (in metres)
+
+**Returns**
+
+An array of hashes which represent the nearest postcodes to the specified location. Ordered by distance from location.
+
+**Example**
+
+```ruby
+postcodes = IdealPostcodes::Postcode.find_by_location longitude: 0.629834, latitude: 51.79232
+
+# postcodes =>
+#[
+#  {
+#    :postcode=>"CM8 1EF", 
+#    :northings=>213679, 
+#    :eastings=>581461, 
+#    :longitude=>0.629834723775309, 
+#    :latitude=>51.7923246977375, 
+#    :distance=>0.52506633}, 
+#  {
+#    :postcode=>"CM8 1EU", 
+#    :northings=>213650, 
+#    :eastings=>581507, 
+#    :longitude=>0.630485817275861, 
+#    :latitude=>51.7920493205979, 
+#    :distance=>54.12525282
+#  },
+```
+
+**Notes**
+
+Data source: Ordnance Survey. Free to use.
+
+
+
+## Retrieve an address using UDPRN [(docs)](https://ideal-postcodes.co.uk/documentation/addresses#address)
+
+Retrieve the specific address for a specific UDPRN.
+
+```ruby
+IdealPostcodes::Address.lookup udprn
+```
+
+**Arguments**
+
+- `udprn` (string | number). A number which uniquely identifies the address.
+
+**Returns**
+
+Returns a hash representing the matching address. Returns `nil` if no matching address is found.
+
+**Example**
+
+```ruby
+IdealPostcodes::Address.lookup 23747771
+
+#{
+#  :line_1=>"Prime Minister & First Lord Of The Treasury", 
+#  :line_2=>"10 Downing Street", 
+#  :line_3=>"", 
+#  :post_town=>"LONDON",  
+#  :postcode=>"SW1A 2AA", 
+#  :organisation_name=>"Prime Minister & First Lord Of The Treasury", 
+#  :premise=>"10", 
+#  :latitude=>51.5035398826274
+#  :longitude=>-0.127695242183412, 
+#  :thoroughfare=>"Downing Street", 
+#  :district=>"Westminster", 
+#  :ward=>"St James's", 
+#  :building_number=>"10", 
+#  :udprn=>23747771, 
+#  ... and so on
+```
+
+**Notes**
+
+Data source: Royal Mail Postcode Address File, Ordnance Survey.
+
+Use the address `0` to test integration for free. The complete list of test methods is available in the [documentation](https://ideal-postcodes/documentation/addresses).
+
+## Utility Methods
+
+Listed below are free utility methods, e.g. finding the status of your key.
+
+### Find out if your key is in a usable state [(docs)](https://ideal-postcodes.co.uk/documentation/keys#key)
+
+Find out if your key is in a usable state. E.g. it has a positive balance, it is currently under your defined usage limits, etc.
+
+```
+IdealPostcodes.key_available
+```
+
+**Arguments**
+
+None.
+
+**Returns**
+
+- availability (Boolean). Returns true if key can be used. False if something is preventing the key from making lookups e.g. insufficient balance, reached limits, etc.
+
+**Example**
+
+```ruby
+IdealPostcodes.key_available # => true, you're clear to make lookups
+```
+
+### Retrieve private key information [(docs)](https://ideal-postcodes.co.uk/documentation/keys#details)
+
+This method reveals private information about your key such as the lookup balance, whitelisted URLs, etc. Note: a secret key is required to invoke this method.
+
+```
+IdealPostcodes.key_details
+```
+
+**Arguments**
+
+None.
+
+**Returns**
+
+Returns a hash containing pertinent private information about your key.
+
+**Example**
+
+```ruby
+IdealPostcodes.key_details
+
+# {
+# 	:lookups_remaining=>9678, 
+# 	:daily_limit=>{
+# 		:limit=>100, 
+# 		:consumed=>1
+# 	}, 
+# 	:individual_limit=>{
+# 		:limit=>15
+# 	}, 
+# 	:allowed_urls=>["foo.com"], 
+# 	:notifications=>{
+# 		:emails=>["bar@baz.com"], 
+# 	:enabled=>true}, 
+# 	:automated_topups=>{
+# 		:enabled=>true
+# 	}
+# }
+```
+
+If you intend to use this method, you must pass your secret key (which can be found on your [account page](https://ideal-postcodes.co.uk/account)) along with your API key when instantiating the client. E.g.
+
+```ruby
+IdealPostcodes.apply_secret "your secret key"
+```
+
+Do not share your secret key and avoid commiting this key to your codebase.
 
 ## Testing
 
 ```
-bundle exec rake test
+bundle exec rake
 ```
 
 ## License
-MIT
+
+MIT

data/Rakefile

@@ -1,8 +1,15 @@
-require 'rake'
-require 'rake/testtask'
+begin
+  require 'rspec/core/rake_task'
 
-Rake::TestTask.new do |t|
-	t.libs << "test"
-  t.test_files = FileList['test/test*.rb']
-  t.verbose = true
+  RSpec::Core::RakeTask.new(:spec) do |t|
+  	t.rspec_opts = "--format documentation"
+  end
+
+  task :default => :spec
+rescue LoadError
+  # no rspec available
+end
+
+task :eject_tapes do
+	`rm spec/vcr_cassettes/*.yml`
 end

data/ideal-postcodes-ruby.gemspec

@@ -6,20 +6,20 @@ 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.description = 'Ideal Postcodes is a simple postcode lookup API for UK addresses. See https://ideal-postcodes.co.uk'
+  s.authors = ['Ideal Postcodes']
+  s.email = ['support@ideal-postcodes.co.uk']
+  s.homepage = 'https://ideal-postcodes.co.uk/'
+  s.licenses = ['MIT']
 
-  s.add_dependency('rest-client', '~> 1.6')
-  s.add_dependency('multi_json', '~> 1.7.9')
+  s.add_dependency('rest-client', '>= 1.8', '< 3.0')
 
-  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.add_development_dependency 'rake', '~> 10.1'
+  s.add_development_dependency 'vcr', '~> 2.9'
+  s.add_development_dependency 'rspec', '~> 3.1'
+  s.add_development_dependency 'webmock', '~> 2.3.1'
 
   s.files = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- test/*`.split("\n")
+  s.test_files    = `git ls-files -- spec/*`.split("\n")
   s.require_paths = ['lib']
 end

data/lib/ideal_postcodes.rb

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

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/errors.rb

@@ -1,33 +1,38 @@
 module IdealPostcodes
-	class IdealPostcodesError < StandardError
-		attr_reader :message
-		attr_reader :http_code
-		attr_reader :http_body
-		attr_reader :response_code
+  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 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
+    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 AuthenticationError < IdealPostcodesError
+  end
 
-	class TokenExhaustedError < IdealPostcodesError
-	end
+  class TokenExhaustedError < IdealPostcodesError
+  end
 
-	class LimitReachedError < IdealPostcodesError
-	end
+  class LimitReachedError < IdealPostcodesError
+  end
 
-	class ResourceNotFoundError < IdealPostcodesError
-	end
-end
+  class ResourceNotFoundError < IdealPostcodesError
+  end
+end

data/lib/idealpostcodes/key.rb

@@ -0,0 +1,14 @@
+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