postcodeinfo-client-ruby
API Client wrapper for MoJ Postcode Info API which contains public sector information licensed under the Open Government License v2.0
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:
- 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:
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-staging.dsd.io/',
production: 'https://postcodeinfo.service.justice.gov.uk/'
}
It will use the following rules to infer the URL:
- 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 - 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')
- 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.