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

Argument	Type	Description
postcode	string	The postcode you want to lookup; case and space insensitive

Response

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

Argument	Type	Description
search_term	string	The address you wish to search for
options	hash	Customise search
options.limit	number	Maximum number of returned results per page
options.page	number	Page of results to return (starts at page 0)

Response

Returns a search result object with the following attributes.

Attribute	Type	Description
addresses	hash[]	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	Maximum number of returned results per page
page	number	Page of returned 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.