Provides a convenient interface for looking up postcodes in an instance of the MoJ postcodeinfo API ( Lets you check if a postcode is valid, and lookup: * 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 install postcodeinfo-client-ruby -v 0.2.1



API Client wrapper for MoJ Postcode Info API which contains public sector information licensed under the Open Government License v2.0

Code Climate Test Coverage


Assuming you use Bundler, add

gem 'postcodeinfo-client-ruby'

to your Gemfile, and bundle install



You will need an authentication token ('auth token'). If you're using MoJ DS's Postcode Info server, you can get one by emailing 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 for instructions on how to set a token up.

Quick Start

In your code:

require 'postcodeinfo-client-ruby'

# Create a client
client = "(Your auth token here, without parentheses)")

# lookup a postcode
postcode = client.lookup_postcode('SN15NB')

# postcode details
=> true

=> 51.55669583757671

=> -1.788422750342563

=> {
  gss_code: "E09000003"
  name: "Barnet"
=> {
  gss_code: "E92000001"
  name: "England"

  "thoroughfare_name"=>"DEACON STREET",
  "postcode"=>"SN1 5NB",
  "formatted_address"=>"45 Deacon Street\nSwindon\nSN1 5NB",
   {"type"=>"Point", "coordinates"=>[-1.788451994079729, 51.55661047202816]}},
  "thoroughfare_name"=>"DEACON STREET",
  "postcode"=>"SN1 5NB",
  "formatted_address"=>"48B Deacon Street\nSwindon\nSN1 5NB",
   {"type"=>"Point", "coordinates"=>[-1.788393506605397, 51.55678120312527]}}]


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 = '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 = "(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:

=> {
  development: 'http://localhost:8000/',
  test: 'http://localhost:8000/',
  staging: '',
  production: ''

It will use the following rules to infer the URL:

  1. If you pass an :env to the constructor (e.g. client = '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['POSTCODEINFO_API_TOKEN'] 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


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 (C) 2015 HM Government (Ministry of Justice Digital Services). See for further details.