geocodable

Geocodable

Geocodable is a UK geocoding Ruby gem powered by Geocodable.io.

Using open data released by Royal Mail, Ordnance Survey and the Office for National Statistics, Geocodable can geocode UK mainland postcodes, streets and place names.

Installation

Add this line to your application's Gemfile:

gem 'geocodable'

And then execute:

$ bundle

Or install it yourself as:

$ gem install geocodable

Usage

You'll need an API key to get started and one can be registered for free at https://account.geocodable.io/signup.

Once you've registered an API key, the geocode method can be used to query the API:

require 'geocodable'

Geocodable.api_key = 'YOUR-API-KEY'
Geocodable.geocode('London, UK')

The results will be returned in a Ruby hash:

{
  found: 1,
  results: [
    {
      location: { 
        latitude: 51.517124, 
        longitude: -0.106196 
      },
      address_components: [
        { type: "city",         name: "London" }, 
        { type: "country",      name: "United Kingdom" }, 
        { type: "country_code", name: "UK" }
      ]
    }
  ]
}

Exceptions

Geocodable will raise an exception if the response from the server is anything other that a successful HTTP 2XX response.

begin
  Geocodable.geocode('London, UK')
rescue Geocodable::InvalidRequestError => e
  # Probably missing the query parameter
rescue Geocodable::AuthenticationError => e
  # Missing or invalid API key
rescue Geocodable::AccessDisabledError => e
  # You've disabled requests for this API key in your account
rescue Geocodable::OverRequestLimitError => e
  # You've reached the daily free request limit
rescue Geocodable::APIError => e
  # There was an internal server error or invalid response from the 
  # Geocodable.io servers
rescue => e
  # An unexpected error possibly related to Geocodable
end

## Requirements

• Ruby 1.9.3 and above. (May work on lower 1.9 versions)
• Gems: faraday, excon, json

Development

RSpec tests can be run with: bundle exec rspec spec

Contributing

1. Fork it ( https://github.com/geocodable/geocodable-ruby/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request