postcodeinfo-client-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ca6ca25946353c44ba94a7512c8077202c414b62
+  data.tar.gz: c15c8b55cf06276466ab4445573efa8ff540074d
+SHA512:
+  metadata.gz: 38057890127e5a2202d7643d036a9f32f89e17751f9b58fb6405069af37545b06f2f8ce96169dafd33bc73b4ad81af7117e6c6b281d1b324d2fbb766eeb96e0f
+  data.tar.gz: 6bbb6256d82091e3c5e377785f73c67280ee70b6fd4fa59bb1c3582e73845eef337412859ddf923a216efdadcb41a9d6be5147f43d2835e73e664ce34b03724e

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/.ruby-gemset

@@ -0,0 +1,2 @@
+postcodeinfo-client-ruby
+

data/.ruby-version

@@ -0,0 +1 @@
+2.1.5

data/.simplecov

@@ -0,0 +1,6 @@
+SimpleCov.start do
+  # any custom configs like groups and filters can be here at a central place
+  add_filter '/test/'
+  add_filter '/spec/'
+  add_filter '/.rvm/'
+end

data/Gemfile

@@ -0,0 +1,18 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+gem 'json'
+gem 'rest-client'
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "byebug"
+  gem "rspec", ">= 3.2.0"
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "~> 1.0"
+  gem "jeweler", "~> 2.0.1"
+  gem "simplecov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,97 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.3.8)
+    builder (3.2.2)
+    byebug (5.0.0)
+      columnize (= 0.9.0)
+    columnize (0.9.0)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    domain_name (0.5.24)
+      unf (>= 0.0.5, < 1.0.0)
+    faraday (0.9.1)
+      multipart-post (>= 1.2, < 3)
+    git (1.2.9.1)
+    github_api (0.12.3)
+      addressable (~> 2.3)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.3)
+      multi_json (>= 1.7.5, < 2.0)
+      nokogiri (~> 1.6.3)
+      oauth2
+    hashie (3.4.1)
+    highline (1.7.2)
+    http-cookie (1.0.2)
+      domain_name (~> 0.5)
+    jeweler (2.0.1)
+      builder
+      bundler (>= 1.0)
+      git (>= 1.2.5)
+      github_api
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      rake
+      rdoc
+    json (1.8.2)
+    jwt (1.5.0)
+    mime-types (2.5)
+    mini_portile (0.6.2)
+    multi_json (1.11.0)
+    multi_xml (0.5.5)
+    multipart-post (2.0.0)
+    netrc (0.10.3)
+    nokogiri (1.6.6.2)
+      mini_portile (~> 0.6.0)
+    oauth2 (1.0.0)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 1.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (~> 1.2)
+    rack (1.6.1)
+    rake (10.4.2)
+    rdoc (3.12.2)
+      json (~> 1.4)
+    rest-client (1.8.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 3.0)
+      netrc (~> 0.7)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.3)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.2)
+    simplecov (0.10.0)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    thread_safe (0.3.5)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0)
+  byebug
+  jeweler (~> 2.0.1)
+  json
+  rdoc (~> 3.12)
+  rest-client
+  rspec (>= 3.2.0)
+  simplecov

data/LICENSE.MD

@@ -0,0 +1,19 @@
+Copyright (C) 2015 HM Government (Ministry of Justice Digital Services)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,150 @@
+# postcodeinfo-client-ruby
+
+API Client wrapper for https://github.com/ministryofjustice/postcodeinfo
+
+# Installation
+
+Assuming you use Bundler, add 
+```ruby
+gem 'postcodeinfo-client-ruby'
+```
+to your Gemfile, and ```bundle install```
+
+# Usage
+
+## Authentication
+
+You will need an _authentication token_ ('auth token'). If you're using MoJ DS's Postcode Info server, 
+you can get one by emailing platforms@digital.justice.gov.uk with a brief summary of:
+
+* who you are
+* what project you're going to be using it on
+* roughly how many lookups you expect to do per day
+
+If you're running your own server, see https://github.com/ministryofjustice/postcodeinfo#auth_tokens for instructions on how to set a token up.
+
+## Quick Start
+
+In your code:
+
+```ruby
+require 'postcodeinfo-client-ruby'
+
+# create a client
+client = PostcodeInfo::Client.new(auth_token: "(your auth token here, without parentheses)")
+
+# lookup a postcode
+postcode = client.lookup_postcode('SN15NB')
+
+# postcode details
+postcode.valid?
+=> true
+
+postcode.latitude
+=> 51.55669583757671
+
+postcode.longitude
+=> -1.788422750342563
+
+postcode.local_authority
+=> {
+  gss_code: "E09000003"
+  name: "Barnet"
+}
+
+postcode.addresses
+=> 
+[{"uprn"=>"100121127903",
+  "organisation_name"=>"",
+  "department_name"=>"",
+  "po_box_number"=>"",
+  "building_name"=>"",
+  "sub_building_name"=>"",
+  "building_number"=>45,
+  "thoroughfare_name"=>"DEACON STREET",
+  "dependent_thoroughfare_name"=>"",
+  "dependent_locality"=>"",
+  "double_dependent_locality"=>"",
+  "post_town"=>"SWINDON",
+  "postcode"=>"SN1 5NB",
+  "postcode_type"=>"S",
+  "formatted_address"=>"45 Deacon Street\nSwindon\nSN1 5NB",
+  "point"=>
+   {"type"=>"Point", "coordinates"=>[-1.788451994079729, 51.55661047202816]}},
+ {"uprn"=>"100121127907",
+  "organisation_name"=>"",
+  "department_name"=>"",
+  "po_box_number"=>"",
+  "building_name"=>"48B",
+  "sub_building_name"=>"",
+  "building_number"=>nil,
+  "thoroughfare_name"=>"DEACON STREET",
+  "dependent_thoroughfare_name"=>"",
+  "dependent_locality"=>"",
+  "double_dependent_locality"=>"",
+  "post_town"=>"SWINDON",
+  "postcode"=>"SN1 5NB",
+  "postcode_type"=>"S",
+  "formatted_address"=>"48B Deacon Street\nSwindon\nSN1 5NB",
+  "point"=>
+   {"type"=>"Point", "coordinates"=>[-1.788393506605397, 51.55678120312527]}}]
+```
+
+## Configuration
+
+Apart from the auth_token, there is only one other parameter that the API client needs - api_url.
+
+### Explicit api_url
+
+You can set the api_url explicitly by passing it to the client constructor, like this:
+```ruby
+# create a client
+client = PostcodeInfo::Client.new(api_url: 'https://some.dom.ain/', auth_token: "(your auth token here, without parentheses)")
+```
+or by setting it on an existing client, like this:
+```ruby
+# create a client
+client = PostcodeInfo::Client.new(auth_token: "(your auth token here, without parentheses)")
+# then set the api_url separately:
+client.api_url = 'https://some.dom.ain/'
+```
+
+### Implicit api_url
+
+If you don't pass an api_url to the constructor, it will attempt to infer one from the environment. The client
+has a built-in mapping of environment names to URLs:
+```ruby
+PostcodeInfo::Client.api_urls
+=> {
+  development: 'http://localhost:8000/',
+  test: 'http://localhost:8000/',
+  staging: 'https://postcodeinfo.dsd.io/',
+  production: 'https://postcodeinfo.service.gov.uk/'
+}
+```
+
+It will use the following rules to infer the URL:
+
+1. If you pass an :env to the constructor (e.g. `client = PostcodeInfo::Client.new(env: 'staging', auth_token:'...')`, it will use that as a reference into the api_urls mapping
+2. If you don't pass an :env, but ENV['RAILS_ENV'] is set, it will use that value (so if you're using this gem in a Rails app, it should 'just work')
+3. If neither of the above produce a known environment name, it will default to development
+
+## Support
+
+This code is provided as-is, with no incident response or support levels. Please log all questions, issues, and feature requests in the Github issue tracker for this repo, and we'll take a look as soon as we can. If you're reporting a bug, then it really helps if you can provide the smallest possible bit of code that reproduces the issue. A failing rspec example is even better!
+
+## Contributing to postcodeinfo-client-ruby
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (C) 2015 HM Government (Ministry of Justice Digital Services). See LICENSE.md for
+further details.
+

data/Rakefile

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
+  gem.name = "postcodeinfo-client-ruby"
+  gem.homepage = "https://github.com/ministryofjustice/postcodeinfo-client-ruby"
+  gem.license = "Open Government License"
+  gem.summary = %Q{Client for postcodeinfo API (https://://github.com/ministryofjustice/postcodeinfo)}
+  gem.description = %Q{Provides a convenient interface for looking up postcodes in an instance of the MoJ postcodeinfo API (https://://github.com/ministryofjustice/postcodeinfo).
+    Lets you check if a postcode is valid, and ookup:
+    * all addresses with that postcode
+    * the latitude/longitude of its centre point
+    * the name & GSS code of the local authority under which it resides.}
+  gem.email = "alistair.davidson@digital.justice.gov.uk"
+  gem.authors = ["Al Davidson"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+desc "Code coverage detail"
+task :simplecov do
+  ENV['COVERAGE'] = "true"
+  Rake::Task['spec'].execute
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "postcodeinfo-client-ruby #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/postcodeinfo-client-ruby.rb

@@ -0,0 +1,3 @@
+require 'postcodeinfo/client'
+require 'postcodeinfo/postcode'
+require 'postcodeinfo/exceptions'

data/lib/postcodeinfo/client.rb

@@ -0,0 +1,129 @@
+require 'json'
+require 'rest-client'
+require 'postcodeinfo/exceptions'
+
+require 'byebug'
+
+
+module PostcodeInfo
+  class Client
+
+    attr_accessor :auth_token, :api_uri
+
+    # params:
+    #   auth_token: 'your auth token' (optional)
+    #   api_url:    'url of a postcodeinfo server' (optional)
+    #               If this is not supplied, it will be inferred from the params below
+    #               If no value can be inferred, it will default to http://localhost:8000/
+    #   env:        (development|test|staging|production) (optional - default is development)
+    #               If provided, the API url will be looked up in .api_urls by
+    #               this value.
+    #               If not provided, it will look for a RAILS_ENV environment variable
+    #               and use that.
+    #               If it still can't work out the environment, it will default to development
+    def initialize(opts={})
+      @auth_token = opts[:auth_token]
+      @api_uri = URI.parse(infer_api_url(opts))
+    end
+
+    def api_url
+      @api_uri.to_s
+    end
+
+    def api_url=(url)
+      @api_uri = URI.parse(url)
+    end
+
+    def lookup_postcode(postcode)
+      begin
+        pc = Postcode.new(postcode, self)
+        pc.lookup_info!
+        pc.lookup_addresses!
+        pc
+      rescue RestClient::ResourceNotFound => e
+        raise PostcodeInfo::UnrecognisedPostcode.new(e, nil)
+      end
+    end
+
+    def valid?(postcode)
+      begin
+        response = make_request('/postcodes/' + postcode)
+        case response.code
+          when 200 then true
+          when /^5[0-9]{2}/ then nil
+          when 404 then false
+        end
+
+      rescue RestClient::ResourceNotFound => e
+        false
+      end
+    end
+
+    def addresses(postcode)
+      response = make_request('/addresses/?postcode=' + postcode)
+      handle_response(response)
+    end
+
+    def info(postcode)
+      response = make_request('/postcodes/' + postcode)
+      handle_response(response)
+    end
+
+    def make_request(endpoint)
+      headers = {
+        'Authorization' => 'Token ' + @auth_token
+      }
+      begin
+        response = RestClient::Request.execute( method: :get, 
+            url: URI.join(@api_uri, endpoint).to_s, 
+            headers: headers, 
+            timeout: 5 
+          )
+
+      rescue Exception => ex
+        raise wrapped_exception(ex, response)
+      end
+    end
+
+    protected
+
+      def wrapped_exception(exception, response)
+        case exception
+        when RestClient::Unauthorized
+          PostcodeInfo::InvalidAuthToken.new(exception, response)
+        when RestClient::InternalServerError
+          PostcodeInfo::ServerError.new(exception, response)
+        when SocketError
+          PostcodeInfo::ServiceUnavailable.new(exception, response)
+        else
+          exception
+        end
+      end
+
+      def handle_response(response)
+        JSON.parse(response.body, symbolize_names: true)
+      end
+
+      def infer_api_url(opts={})
+        opts[:api_url] ||
+          from_env( effective_env(opts) )
+      end
+
+      def effective_env(opts)
+        opts[:env] || ENV['RAILS_ENV'] || :development
+      end
+
+      def from_env(env)
+        self.class.api_urls[env.to_sym] || self.class.api_urls[:development]
+      end
+
+      def self.api_urls
+        {
+          development: 'http://localhost:8000/',
+          test: 'http://localhost:8000/',
+          staging: 'https://postcodeinfo.dsd.io/',
+          production: 'https://postcodeinfo.service.gov.uk/'
+        }
+      end
+  end
+end