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.