Ruby

Ideal Postcodes maintains a library to perform postcode and address queries using Ruby. This guide demonstrates how to use the Ruby gem

Getting Started

Install

gem install ideal_postcodes

Alternatively, include this in your gemfile and bundle install

gem 'ideal_postcodes'

Configure

Drop in your key when using the library.

IdealPostcodes.api_key = "your_key_goes_here"

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.

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.

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)

IdealPostcodes::Postcode.lookup postcode

Returns an array of addresses representing all addresses at the specified postcode.

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

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

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

# 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

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.

Search for an address (docs)

IdealPostcodes::Address.search search_term

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

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
```

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.

Source

Listed above are only a few of the core methods to perform useful tasks on our API.

For more methods, you can refer to the README or the source on the Github repository.

Documentation