defra_ruby_area 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b4136c639188f345ff7f134ae43493de19768027
+  data.tar.gz: 60e70fab3d624fc8078fa4229d46f4ef5afc03f9
+SHA512:
+  metadata.gz: a36b69f5153fcdfc5fff4dc701b126fc137b3459876846e92a9a13232d882edd0f871ee7cf9d7490acaa6211d53bde8ea53b58295dcfe4b5a76bb0de80d4a5bf
+  data.tar.gz: d65828c98e10527719438daf61ed84dc6cd346aacf80ae5f36f16f271271f3b5eeea04186da7d8f5f2cf5d7255b354600291d796bcdb0c7a8122bcbcf6e7fde5

data/LICENSE

@@ -0,0 +1,8 @@
+The Open Government Licence (OGL) Version 3
+
+Copyright (c) 2019 Environment Agency
+
+This source code is licensed under the Open Government Licence v3.0. To view this
+licence, visit www.nationalarchives.gov.uk/doc/open-government-licence/version/3
+or write to the Information Policy Team, The National Archives, Kew, Richmond,
+Surrey, TW9 4DU.

data/README.md

@@ -0,0 +1,150 @@
+# Defra Ruby Area
+
+[![Build Status](https://travis-ci.com/DEFRA/defra-ruby-area.svg?branch=master)](https://travis-ci.com/DEFRA/defra-ruby-area)
+[![Maintainability](https://api.codeclimate.com/v1/badges/7aeffed0588d86a5e553/maintainability)](https://codeclimate.com/github/DEFRA/defra-ruby-area/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/7aeffed0588d86a5e553/test_coverage)](https://codeclimate.com/github/DEFRA/defra-ruby-area/test_coverage)
+[![security](https://hakiri.io/github/DEFRA/defra-ruby-area/master.svg)](https://hakiri.io/github/DEFRA/defra-ruby-area/master)
+[![Licence](https://img.shields.io/badge/Licence-OGLv3-blue.svg)](http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3)
+
+This ruby gem provides a means of looking up an Environment Agency Administrative boundary from a GIS Web Feature Service (WFS). Provided with a valid [easting and northing](https://en.wikipedia.org/wiki/Easting_and_northing) it will query the WFS and return the long name for the area if a match is found.
+
+## Installation
+
+Add this line to your application's Gemfile
+
+```ruby
+gem "defra_ruby_area"
+```
+
+And then update your dependencies by calling
+
+```bash
+bundle install
+```
+
+## Usage
+
+The gem interfaces with two WFS's that provide administrative boundaries; [Environment Agency and Natural England Public Face Areas](https://environment.data.gov.uk/dataset/91d0fb43-209c-477f-91e3-74e756296268) and [Water Management Areas](https://environment.data.gov.uk/dataset/7942e4cf-d465-11e4-ac00-f0def148f590).
+
+### Response object
+
+Each WFS is called through a service that responds with a `DefraRuby::Area::Response` object. It has the following attributes
+
+```ruby
+response.successful?
+response.area
+response.error
+```
+
+If the call is successful (the query did not error and a match was found) then
+
+- `successful?()` will be `true`
+- `area` will contain the long name of the matching administrative boundary
+- `error` will be `nil`
+
+If the call is unsuccessful (the query errored or no match was found) then
+
+- `successful?()` will be `false`
+- `area` will be `nil`
+- `error` will contain the error
+
+If its a runtime error, or an error when calling the WFS `error` will contain whatever error was raised.
+
+If its because no match was found `error` will contain an instance of `DefraRuby::Area::NoMatchError`.
+
+### Environment Agency and Natural England Public Face Areas
+
+This WFS contains public facing administrative boundaries set at 1:10,000 scale. To use it make the following call
+
+```ruby
+easting = 408_602.61
+northing = 257_535.31
+response = DefraRuby::Area::PublicFaceAreaService.run(easting, northing)
+
+puts response.area if response.successful? # West Midlands
+```
+
+### Water Management Areas
+
+This WFS contains public facing water management administrative boundaries set at 1:10,000 scale. To use it make the following call
+
+```ruby
+easting = 408_602.61
+northing = 257_535.31
+response = DefraRuby::Area::WaterManagementAreaService.run(easting, northing)
+
+puts response.area if response.successful? # Staffordshire Warwickshire and West Midlands
+```
+
+## Web Feature Services
+
+A [Web Feature Service (WFS)](https://en.m.wikipedia.org/wiki/Web_Feature_Service) is simply a web service that implements the Open Geospatial Consortium Web Feature Service (WFS) Interface Standard.
+
+Calls are made using url query params. For example behind the scenes `DefraRuby::Area::PublicFaceAreaService` is hitting the following URL
+
+`https://environment.data.gov.uk/spatialdata/administrative-boundaries-environment-agency-and-natural-england-public-face-areas/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=GetFeature&typeNames=ms:Administrative_Boundaries_Environment_Agency_and_Natural_England_Public_Face_Areas&propertyName=long_name&SRSName=EPSG:27700&Filter=(<Filter><Intersects><PropertyName>SHAPE</PropertyName><gml:Point><gml:coordinates>408602.61,257535.31</gml:coordinates></gml:Point></Intersects></Filter>)`
+
+As you can see it uses XML within query, and will return the result in XML.
+
+```xml
+<?xml version="1.0" encoding="utf-8" ?>
+<wfs:FeatureCollection xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:wfs="http://www.opengis.net/wfs" xmlns:gml="http://www.opengis.net/gml" xmlns:ms="https://environment.data.gov.uk/spatialdata/administrative-boundaries-environment-agency-and-natural-england-public-face-areas/wfs" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/wfs http://schemas.opengis.net/wfs/1.0.0/WFS-basic.xsd http://www.opengis.net/gml http://schemas.opengis.net/gml/2.1.2/feature.xsd https://environment.data.gov.uk/spatialdata/administrative-boundaries-environment-agency-and-natural-england-public-face-areas/wfs https://environment.data.gov.uk/spatialdata/administrative-boundaries-environment-agency-and-natural-england-public-face-areas/wfs?service=wfs%26version=1.0.0%26request=DescribeFeatureType">
+<gml:boundedBy>
+  <gml:Box srsName="EPSG:27700">
+    <gml:coordinates>0,0,0,0</gml:coordinates>
+  </gml:Box>
+</gml:boundedBy>
+  <gml:featureMember>
+    <ms:Administrative_Boundaries_Environment_Agency_and_Natural_England_Public_Face_Areas fid="Administrative_Boundaries_Environment_Agency_and_Natural_England_Public_Face_Areas.23">
+      <ms:OBJECTID>23</ms:OBJECTID>
+      <ms:long_name>West Midlands</ms:long_name>
+      <ms:st_area_shape_>14543741870.84492</ms:st_area_shape_>
+      <ms:st_perimeter_shape_>1043376.795941756</ms:st_perimeter_shape_>
+    </ms:Administrative_Boundaries_Environment_Agency_and_Natural_England_Public_Face_Areas>
+  </gml:featureMember>
+</wfs:FeatureCollection>
+```
+
+### Further reading
+
+Checkout these additional resources we have found helpful in understanding how WFS's work.
+
+- [Communicating with a WFS service in a web browser](https://enterprise.arcgis.com/en/server/latest/publish-services/windows/communicating-with-a-wfs-service-in-a-web-browser.htm)
+- [Introduction to Web Feature Service](https://geoserver.geo-solutions.it/edu/en/vector_data/wfsintro.html)
+- [WFS reference](https://docs.geoserver.org/latest/en/user/services/wfs/reference.html)
+
+### Argh!
+
+We don't know if its just a characteristic of WFS's, GIS, or just the EA implementations but things often break in this world.
+
+A WFS will often go down, sometimes for maintenance (_hopefully_ on a weekend 😀) sometimes just for 'reasons'.
+
+Also though this gem is new, we have worked with these services before and this is approximately the 5th time the format of the query has changed in the space of a 3 years.
+
+For example the period of December 2018 to June 2019 both services were completely down whilst we waited for fixes to be implemented, then confirmation of what query would actually work!
+
+You may also find any page we have linked to in this README will no longer respond. Again they often seem to move or be taken down.
+
+So expect stuff to break, and be prepared to use some detective work to either get it going again, for find where its moved to 😉.
+
+## Contributing to this project
+
+If you have an idea you'd like to contribute please log an issue.
+
+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.

data/Rakefile

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+Bundler::GemHelper.install_tasks
+
+# This is wrapped to prevent an error when rake is called in environments where
+# rspec may not be available, e.g. production. As such we don't need to handle
+# the error.
+# rubocop:disable Lint/HandleExceptions
+begin
+  require "rspec/core/rake_task"
+
+  RSpec::Core::RakeTask.new(:spec)
+
+  task default: :spec
+rescue LoadError
+  # no rspec available
+end
+
+begin
+  require "github_changelog_generator/task"
+
+  GitHubChangelogGenerator::RakeTask.new :changelog do |config|
+  end
+rescue LoadError
+  # no changelog available
+end
+# rubocop:enable Lint/HandleExceptions

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "defra/ruby/area"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/defra_ruby.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "defra_ruby/area"
+
+module DefraRuby
+  # The Defra Ruby packages namespace
+end

data/lib/defra_ruby/area.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "area/no_match_error"
+require_relative "area/response"
+
+require_relative "area/services/base_area_service"
+require_relative "area/services/public_face_area_service"
+require_relative "area/services/water_management_area_service"
+
+module DefraRuby
+  module Area
+  end
+end

data/lib/defra_ruby/area/no_match_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Area
+    class NoMatchError < StandardError
+      def initialize
+        super("No match found")
+      end
+    end
+  end
+end

data/lib/defra_ruby/area/response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Area
+    class Response
+      attr_reader :error
+      attr_reader :area
+
+      def initialize(response_exe)
+        @success = true
+        @area = nil
+        @error = nil
+
+        capture_response(response_exe)
+      end
+
+      def successful?
+        success
+      end
+
+      private
+
+      attr_reader :success
+
+      def capture_response(response_exe)
+        @area = response_exe.call[:area]
+      rescue StandardError => e
+        @error = e
+        @success = false
+      end
+    end
+  end
+end

data/lib/defra_ruby/area/services/base_area_service.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "rest-client"
+
+module DefraRuby
+  module Area
+    class BaseAreaService
+
+      def self.run(easting, northing)
+        new(easting, northing).run
+      end
+
+      def initialize(easting, northing)
+        @easting = easting
+        @northing = northing
+      end
+
+      def run
+        Response.new(response_exe)
+      end
+
+      private
+
+      attr_reader :easting, :northing
+
+      def response_exe
+        lambda do
+          begin
+            response = RestClient::Request.execute(method: :get, url: url)
+            area = parse_xml(response)
+            raise NoMatchError if area.nil? || area == ""
+          rescue StandardError => e
+            raise e
+          end
+          { area: area }
+        end
+      end
+
+      def parse_xml(response)
+        xml = Nokogiri::XML(response)
+        xml.xpath(response_xml_path).text
+      end
+
+      def url
+        implemented_in_subclass
+      end
+
+      def response_xml_path
+        implemented_in_subclass
+      end
+
+      def implemented_in_subclass
+        raise NotImplementedError, "This #{self.class} cannot respond to:"
+      end
+    end
+  end
+end

data/lib/defra_ruby/area/services/public_face_area_service.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "rest-client"
+
+module DefraRuby
+  module Area
+    class PublicFaceAreaService < BaseAreaService
+
+      private
+
+      def response_xml_path
+        type_name = "Administrative_Boundaries_Environment_Agency_and_Natural_England_Public_Face_Areas"
+        "//wfs:FeatureCollection/gml:featureMember/ms:#{type_name}/ms:long_name"
+      end
+
+      def url
+        # rubocop:disable Metrics/LineLength
+        "https://environment.data.gov.uk/spatialdata/administrative-boundaries-environment-agency-and-natural-england-public-face-areas/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=GetFeature&typeNames=ms:Administrative_Boundaries_Environment_Agency_and_Natural_England_Public_Face_Areas&propertyName=long_name&SRSName=EPSG:27700&Filter=(<Filter><Intersects><PropertyName>SHAPE</PropertyName><gml:Point><gml:coordinates>#{easting},#{northing}</gml:coordinates></gml:Point></Intersects></Filter>)"
+        # rubocop:enable Metrics/LineLength
+      end
+
+    end
+  end
+end

data/lib/defra_ruby/area/services/water_management_area_service.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "rest-client"
+
+module DefraRuby
+  module Area
+    class WaterManagementAreaService < BaseAreaService
+
+      private
+
+      def response_xml_path
+        type_name = "Administrative_Boundaries_Water_Management_Areas"
+        "//wfs:FeatureCollection/gml:featureMember/ms:#{type_name}/ms:long_name"
+      end
+
+      def url
+        # rubocop:disable Metrics/LineLength
+        "https://environment.data.gov.uk/spatialdata/administrative-boundaries-water-management-areas/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=GetFeature&typeNames=ms:Administrative_Boundaries_Water_Management_Areas&propertyName=long_name&SRSName=EPSG:27700&Filter=(<Filter><Intersects><PropertyName>SHAPE</PropertyName><gml:Point><gml:coordinates>#{easting},#{northing}</gml:coordinates></gml:Point></Intersects></Filter>)"
+        # rubocop:enable Metrics/LineLength
+      end
+
+    end
+  end
+end

data/lib/defra_ruby/area/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Area
+    VERSION = "0.1.0"
+  end
+end

data/spec/cassettes/public_face_area_invalid_blank.yml

@@ -0,0 +1,157 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://environment.data.gov.uk/spatialdata/administrative-boundaries-environment-agency-and-natural-england-public-face-areas/wfs?Filter=(%3CFilter%3E%3CIntersects%3E%3CPropertyName%3ESHAPE%3C/PropertyName%3E%3Cgml:Point%3E%3Cgml:coordinates%3E,%3C/gml:coordinates%3E%3C/gml:Point%3E%3C/Intersects%3E%3C/Filter%3E)&REQUEST=GetFeature&SERVICE=WFS&SRSName=EPSG:27700&VERSION=2.0.0&propertyName=long_name,short_name&typeNames=ms:Administrative_Boundaries_Environment_Agency_and_Natural_England_Public_Face_Areas
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Accept:
+      - "*/*"
+      Accept-Encoding:
+      - gzip, deflate
+      User-Agent:
+      - rest-client/2.0.2 (darwin18.5.0 x86_64) ruby/2.4.2p198
+      Host:
+      - environment.data.gov.uk
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Server:
+      - nginx
+      Date:
+      - Tue, 09 Jul 2019 15:45:40 GMT
+      Content-Type:
+      - application/xml
+      Content-Length:
+      - '635'
+      Connection:
+      - keep-alive
+      Cache-Control:
+      - private
+      X-Aspnet-Version:
+      - 4.0.30319
+      X-Powered-By:
+      - ASP.NET
+    body:
+      encoding: UTF-8
+      string: |
+        <?xml version="1.0" encoding="utf-8" ?>
+        <ExceptionReport
+         version="2.0.0" xmlns="http://www.opengis.net/ows/1.1"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://www.opengis.net/ows/1.1 http://schemas.opengis.net/ows/1.1.0/owsAll.xsd"
+        >
+          <Exception exceptionCode="InvalidParameterValue" locator="Unknown">
+            <ExceptionText><![CDATA[The geometry was not recognized.]]></ExceptionText>
+          </Exception>
+          <Exception exceptionCode="OperationProcessingFailed" locator="Unknown">
+            <ExceptionText><![CDATA[Operator 'Intersects' can't parse geometry.]]></ExceptionText>
+          </Exception>
+        </ExceptionReport>
+    http_version: 
+  recorded_at: Tue, 09 Jul 2019 15:45:40 GMT
+- request:
+    method: get
+    uri: https://environment.data.gov.uk/spatialdata/administrative-boundaries-environment-agency-and-natural-england-public-face-areas/wfs?Filter=(%3CFilter%3E%3CIntersects%3E%3CPropertyName%3ESHAPE%3C/PropertyName%3E%3Cgml:Point%3E%3Cgml:coordinates%3E,%3C/gml:coordinates%3E%3C/gml:Point%3E%3C/Intersects%3E%3C/Filter%3E)&REQUEST=GetFeature&SERVICE=WFS&SRSName=EPSG:27700&VERSION=2.0.0&propertyName=long_name&typeNames=ms:Administrative_Boundaries_Environment_Agency_and_Natural_England_Public_Face_Areas
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Accept:
+      - "*/*"
+      Accept-Encoding:
+      - gzip, deflate
+      User-Agent:
+      - rest-client/2.0.2 (darwin18.5.0 x86_64) ruby/2.4.2p198
+      Host:
+      - environment.data.gov.uk
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Server:
+      - nginx
+      Date:
+      - Thu, 01 Aug 2019 10:07:13 GMT
+      Content-Type:
+      - application/xml
+      Content-Length:
+      - '635'
+      Connection:
+      - keep-alive
+      Cache-Control:
+      - private
+      X-Aspnet-Version:
+      - 4.0.30319
+      X-Powered-By:
+      - ASP.NET
+    body:
+      encoding: UTF-8
+      string: |
+        <?xml version="1.0" encoding="utf-8" ?>
+        <ExceptionReport
+         version="2.0.0" xmlns="http://www.opengis.net/ows/1.1"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://www.opengis.net/ows/1.1 http://schemas.opengis.net/ows/1.1.0/owsAll.xsd"
+        >
+          <Exception exceptionCode="InvalidParameterValue" locator="Unknown">
+            <ExceptionText><![CDATA[The geometry was not recognized.]]></ExceptionText>
+          </Exception>
+          <Exception exceptionCode="OperationProcessingFailed" locator="Unknown">
+            <ExceptionText><![CDATA[Operator 'Intersects' can't parse geometry.]]></ExceptionText>
+          </Exception>
+        </ExceptionReport>
+    http_version: 
+  recorded_at: Thu, 01 Aug 2019 10:07:13 GMT
+- request:
+    method: get
+    uri: https://environment.data.gov.uk/spatialdata/administrative-boundaries-environment-agency-and-natural-england-public-face-areas/wfs?Filter=(%3CFilter%3E%3CIntersects%3E%3CPropertyName%3ESHAPE%3C/PropertyName%3E%3Cgml:Point%3E%3Cgml:coordinates%3E,%3C/gml:coordinates%3E%3C/gml:Point%3E%3C/Intersects%3E%3C/Filter%3E)&REQUEST=GetFeature&SERVICE=WFS&SRSName=EPSG:27700&VERSION=1.0.0&propertyName=long_name&typeNames=ms:Administrative_Boundaries_Environment_Agency_and_Natural_England_Public_Face_Areas
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Accept:
+      - "*/*"
+      Accept-Encoding:
+      - gzip, deflate
+      User-Agent:
+      - rest-client/2.0.2 (darwin18.5.0 x86_64) ruby/2.4.2p198
+      Host:
+      - environment.data.gov.uk
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Server:
+      - nginx
+      Date:
+      - Sat, 03 Aug 2019 10:48:37 GMT
+      Content-Type:
+      - application/xml
+      Content-Length:
+      - '349'
+      Connection:
+      - keep-alive
+      Cache-Control:
+      - private
+      X-Aspnet-Version:
+      - 4.0.30319
+      X-Powered-By:
+      - ASP.NET
+    body:
+      encoding: UTF-8
+      string: |
+        <?xml version="1.0" encoding="utf-8" ?>
+        <ogc:ServiceExceptionReport xmlns:ogc="http://www.opengis.net/ogc" version="1.2.0">
+          <ogc:ServiceException><![CDATA[The geometry was not recognized.]]></ogc:ServiceException>
+          <ogc:ServiceException><![CDATA[Operator 'Intersects' can't parse geometry.]]></ogc:ServiceException>
+        </ogc:ServiceExceptionReport>
+    http_version: 
+  recorded_at: Sat, 03 Aug 2019 10:48:37 GMT
+recorded_with: VCR 4.0.0