/postcode_lookup

Lookups postcodes to check if they are whitelisted

Primary LanguageRuby

PostCode Lookup

PostCode lookup is a simple web application to work out if a given postcode is whitelisted given a list of LSOA (Lower Super Output Area - UK postal service area) areas and an additional postcode specific whitelist particular service area.

It is a single page app with a form where the input is a UK postcode. Submitting the form gives a response as to whether the postcode is whitelisted or not.

Whitelisting rules

The system uses the Postcodes.io REST API as a data source. The service area is described by the following rules:

  1. Postcodes are grouped into larger blocks called LSOAs. This is returned from the API when we query a postcode. By default we whitelist any postcode in an LSOA starting "Southwark" or "Lambeth". Example postcodes for these LSOAs are SE1 7QD and SE1 7QA respectively. This is the "LSOA whitelist".
  2. Some postcodes are unknown by the API or may be served despite being outside of the whitelisted LSOAs. We whitelist these anyway, even though the API does not recognise them. SH24 1AA and SH24 1AB are both examples of unknown postcodes that we serve. This is the "Postcode whitelist".
  3. Any postcode not in the LSOA whitelist or the Postcode whitelist is not servable.

Requirements

The code is written and tested against:

Installation

  1. Clone the repository
$ git clone https://github.co/tansaku/postcode_lookup
  1. Move into directory and install dependencies
$ cd postcode_lookup
$ bundle
  1. Start the server
$ bundle exec rails server
  1. View the site:

http://localhost:3000

If you want to set up whitelisted boroughs and postcodes, you can do so as follows:

$ bundle exec ./bin/rails console

> Borough.create!(name: "Southwark")
> Borough.create!(name: "Lambeth")
> Postcode.create!(name: "SH24 1AA")
> Postcode.create!(name: "SH24 1AB")

include an animated gif of the system in operation?

  • System dependencies

Postcodes API provided by https://postcodes.io and ruby gem https://github.com/jamesruston/postcodes_io. See Gemfile for other dependencies

  • Configuration

none at present

  • Database creation?

  • Database initialization?

  • Run the test suite (and linting via rubocop) by the following command

$ bundle exec ./bin/rails default

which should produce output like the following:

Running RuboCop...
Inspecting 17 files
.................

17 files inspected, no offenses detected
/Users/tansaku/.rvm/rubies/ruby-2.6.5/bin/ruby -I/Users/tansaku/.rvm/gems/ruby-2.6.5/gems/rspec-core-3.9.1/lib:/Users/tansaku/.rvm/gems/ruby-2.6.5/gems/rspec-support-3.9.2/lib /Users/tansaku/.rvm/gems/ruby-2.6.5/gems/rspec-core-3.9.1/exe/rspec --pattern spec/\*\*\{,/\*/\*\*\}/\*_spec.rb

lookup postcode
  check a non whitelisted postcode
  check a Southwark postcode is whitelisted
  check a Lambeth postcode is whitelisted
  check an unknown postcode is whitelisted
  check an API unknown postcode is whitelisted when specified
  check an API unknown postcode is not whitelisted
  handle error from WhitelistChecker

WhitelistChecker
  Lambeth postcode
    is whitelisted
  Southwark postcode
    is whitelisted
  specifically whitelisted API unknown postcode
    is whitelisted, e.g. 'SH24 1AA'
    is whitelisted, e.g. 'SH24 1AB'
  Harrow postcode
    is not whitelisted
  API unknown postcodes that are not on the whitelist
    is not whitelisted
  Errors
    lsoa is empty string
      postcode is not whitelisted

Finished in 4.98 seconds (files took 7.6 seconds to load)
14 examples, 0 failures


COVERAGE: 100.00% -- 77/77 lines in 19 files
  • Deployment instructions

To deploy to heroku web hosting (assuming heroku CLI is installed), ensure you are in the project directory and run the following commands:

$ heroku create postcode-checker
$ git push heroku master
$ heroku run rails db:migrate

and potentially

$ heroku addons:create heroku-postgresql:hobby-dev

Finally, you can set up whitelisted boroughs and postcodes on heroku like so:

$ heroku run rails console

> Borough.create!(name: "Southwark")
> Borough.create!(name: "Lambeth")
> Postcode.create!(name: "SH24 1AA")
> Postcode.create!(name: "SH24 1AB")

The app can then be accessed on heroku, e.g.

https://postcode-checker.herokuapp.com/

TODO

  • extract the actual whitelists
    • stick them in the database
    • show the whitelists on the main page
  • error cases
    • maybe show note about server is down if postcodes server is down
  • checking input format
  • refactoring?
  • test coverage
  • stubbing test calls to postcodes.io?
    • unit tests
      • mockwreck issue? don't stub what you don't own?
    • acceptance tests
  • deploy to heroku
  • Should the form use an ajax request?