Ideal-Postcodes.co.uk API Wrapper

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.

Getting Started

Install it

gem install ideal_postcodes

Alternatively for rails, include this in your gemfile and bundle install

gem 'ideal_postcodes'

Get an API Key

Get a key at Ideal-Postcodes.co.uk. Try out the service with the test postcode 'ID1 1QD'

Configuration

In order to perform lookups, you'll need to configure the gem by passing in your api key by doing the following:

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:

IdealPostcodes.api_key = "<your key goes here>"

Usage

Simply call #lookup class method on IdealPostcodes::Postcode. This will return a Postcode object containing the complete list of addresses if the postcode exists.

postcode = IdealPostcodes::Postcode.lookup "ID1 1QD"

if postcode.empty? 
    puts "Your postcode doesn't have a match"
else
    postcode.addresses
end

# postcode.addresses =>
#
# [
#  {
#   :postcode => "ID1 1QD",
#   :post_town => "LONDON",
#   :line_1 => "Kingsley Hall",
#   :line_2 => "Powis Road",
#   :line_3 => "",
#   :organisation_name => "",
#   :building_name => "Kingsley Hall",
#   :udprn => 12345678
#  }, ... and so on

Exceptions

The wrapper will raise an exception for anything other than a 200 response or an empty 404 response (which means no addresses at postcode).

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

Registering

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 lookup.

Documentation

More documentation can be found here

Testing

bundle exec rake test

License

MIT