ideal_postcodes 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c34b866375b1eb59033c3c9f4139ed49e1f91bd1
-  data.tar.gz: 48da9070ca6d8cb2af643879f1837d697c3a89af
+  metadata.gz: be3239f59167b00d3b406e3c6a45365dc7e646b4
+  data.tar.gz: 285c68271eb9fb98011e575d1bc8446c3b892e40
 SHA512:
-  metadata.gz: 11b659c4e56fb6188874468b2c2e8363eb7088ca13672540ced297f762f5a096f53f49f51d6b2144bc6af0a3006596e2be9e550291aff14ef15d28e6ea2e04ce
-  data.tar.gz: b64a4e49837cfad1410b382600f2af5eff9ee1fbea7a833689f1b34c021c10a75154f445e6363c0e6cc9f50ce79e2082af292f3c995b084b670301b9b12b3195
+  metadata.gz: bd635f4ad102fc61785c3d8d7637f2d7c5f11bd348e2ad9a14ad2f8d3222e4bd44914e6b784512ff819f8c97ec8e87df6151f7c0ba63d6c1d5bceeb6fdf71ab7
+  data.tar.gz: b596444fc91dea8b680a9681950f0c2a7f0ca712f0a879290b37c4f3a8ae2c1d7c86e2a883dcc9bd120f5cb2ecf561b8f8c721cd3ccc640984be274a0e3bd32c

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.1.1
+  - 2.0.0
+  - 1.9.3
+  - jruby-19mode

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/documentatpion/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,261 @@ end
 #   :organisation_name => "",
 #   :building_name => "Kingsley Hall",
 #   :udprn => 12345678
-#  }, ... and so on
+#   ... and so on
 ```
 
-__Exceptions__
+**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).
+
+
 
-The wrapper will raise an exception for anything other than a 200 response or an empty 404 response (which means no addresses at postcode).
+
+## Search for an address [(docs)](https://ideal-postcodes.co.uk/documentation/addresses#query)
+
+Perform a search for addresses which match your search term.
+
+**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**
+
+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.
 
-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.
+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).
+
+
+
+
+## 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
+```
 
-We charge _2p_ per [external](https://ideal-postcodes.co.uk/termsandconditions#external) lookup.
+**Arguments**
 
-## Documentation
+- `location` (Hash)
+	- `longitude` (number, required)
+	- `latitude` (number, required)
+	- `limit` (number, optional) Maximum number of results to return 
+	- `radius` (number, optional) search radius (in metres)
 
-More documentation can be found [here](https://ideal-postcodes.co.uk/documentation/ruby-wrapper)
+**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
+```
+
+### Find out 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.
+
+
+## Changelog
+
+*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
 
 ## Testing
 
 ```
-bundle exec rake test
+bundle exec rake
 ```
 
 ## License
+
 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,19 @@ 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.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.add_development_dependency 'rake', '~> 10.1.0'
+  s.add_development_dependency 'vcr', '~> 2.9.3'
+  s.add_development_dependency 'rspec', '~> 3.1.0'
+  s.add_development_dependency 'webmock', '~> 1.20.4'
 
   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