uk-gov-mirror / defra.os-places-address-lookup

A REST based wrapper around the OS Places API used to support address lookup

OS Places address lookup

We do not recommend using this project. Contact Alan Cruikshanks for details and alternatives.

A REST based wrapper built using Dropwizard around the OS Places API. Created for the Waste Carriers Registration service, it has since been superseded by other projects.

Not all features of the API are exposed with this service. It was built to support address lookup using a postcode for another service, and to provide the latitude and longitude for a given address.

For further details about the OS Places API check out their user guide.

Prerequisites

• Java Open JDK 8
• Key and URL for OS Places service

Installation

Clone the repo

git clone https://github.com/DEFRA/os-places-address-lookup && cd os-places-address-lookup

Configuration

The file configuration.yml represents a template configuration. If you are happy to use the defaults the only value you'll need to replace is WCRS_OSPLACES_KEY.

Build

The project uses Maven as its build tool, and Maven Wrapper to handle getting a version of Maven on your machine to download the project.

So to build the project call

./mvnw -B -Dmaven.test.skip=true -T 1C clean package

N.B. If maven was installed all on the machine you would swap ./mvnw with mvn.

Run tests

Currently the unit tests included in the project rely on an actual connection to OS Places as it has not been mocked. Because of this it can cause issues during a typical Maven build as by default it will attempt to run any unit tests it finds.

Also the unit tests cannot read from the configuration.yml as the app would when started, so you must set some environment variables before attempting to run the tests

• WCRS_OSPLACES_KEY
• WCRS_OSPLACES_URL

Hence the command to build above includes the option to skip tests. Instead we advise those working on the project should manually run the tests as and when required using

./mvnw test

Start the service

Once built execute the jar file, providing 'server' and the name of the configuration file as arguments.

java -jar target/os-places-address-lookup.jar server configuration.yml

Once the application server is started you should be able to access the service in your browser. Confirm this by going to http://localhost:8006 and the operational menu will be visible.

Using the service

The following provides examples of how to use the service.

1. Get a list of all addresses for a given postcode

$ curl -GET localhost:8005/addresses?postcode=BS15AH

2. Get the detailed address info for an address given by its unique identifier (moniker or UPRN)

$ curl -GET localhost:8005/addresses/340116

Contributing to this project

If you have an idea you'd like to contribute please log an issue. Else if you would like to contribute but are stuck for ideas check out the issue log.

All contributions should be submitted via a pull request.

License

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the license

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.