postcodeinfo-client-ruby

API Client wrapper for MoJ Postcode Info API

Installation

Assuming you use Bundler, add

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:

If you’re running your own server, see github.com/ministryofjustice/postcodeinfo#auth_tokens for instructions on how to set a token up.

Quick Start

In your code:

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.country
=> {
  gss_code: "E92000001"
  name: "England"
}

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:

# 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:

# 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:

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

Copyright © 2015 HM Government (Ministry of Justice Digital Services). See LICENSE.md for further details.