defra_ruby_address 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f47c9a7a1e39ae9d9b7062dc77fe063bf443cbe0
-  data.tar.gz: 37cf2259b5bb278a180f89fcb413636b50b4011c
+SHA256:
+  metadata.gz: a5d4b459711e84d2d0caac1f48600cb928c1cede9b4ca85e5d23e53b12f4a881
+  data.tar.gz: 0c6b7e465734d6f4cc4cbea1df20b40a2d93d9e0d38035dc7d2d8ffbe639855e
 SHA512:
-  metadata.gz: 10198b655e7d18bb9dc59d90bbe9ac1909d0a528bfc9df7a26be3dad6e5438881d501202962d1d102d4298ef9980dfe5b182772fe4bb934b74cd4e1f57cb27dc
-  data.tar.gz: b1221cbdd838ba2ee750778987ff652f16b72dc33a20cd5fcef9ae8eaf9ad0248e277af12f3bf61ed63dc5ec01b5b765e5604125f725faf689dad43c677c8ea4
+  metadata.gz: c80f7606cbfffc7dc4f03c06b106c2df3d23ad5c4fd93e29849c3ff035e6b5d53836b8bad16816f40164674de1d9437b07792d13410d99b8df4775cb72c10c2c
+  data.tar.gz: 7dc7df096183d0422971325ba71e4f5607b9e279833f10d8bd86249ef808af6c758be28a610e16bfb6f2604489992fbfa3eba0c089543fabbe2d6bec9197029b

data/README.md

@@ -1,9 +1,9 @@
 # Defra Ruby Address
 
-[![Build Status](https://travis-ci.com/DEFRA/defra-ruby-address.svg?branch=master)](https://travis-ci.com/DEFRA/defra-ruby-address)
-[![Maintainability](https://api.codeclimate.com/v1/badges/1a0b68efe00098e0734f/maintainability)](https://codeclimate.com/github/DEFRA/defra-ruby-address/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/1a0b68efe00098e0734f/test_coverage)](https://codeclimate.com/github/DEFRA/defra-ruby-address/test_coverage)
-[![security](https://hakiri.io/github/DEFRA/defra-ruby-address/master.svg)](https://hakiri.io/github/DEFRA/defra-ruby-address/master)
+![Build Status](https://github.com/DEFRA/defra-ruby-address/workflows/CI/badge.svg?branch=main)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=DEFRA_defra-ruby-address&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=DEFRA_defra-ruby-address)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=DEFRA_defra-ruby-address&metric=coverage)](https://sonarcloud.io/dashboard?id=DEFRA_defra-ruby-address)
+[![security](https://hakiri.io/github/DEFRA/defra-ruby-address/main.svg)](https://hakiri.io/github/DEFRA/defra-ruby-address/main)
 [![Gem Version](https://badge.fury.io/rb/defra_ruby_address.svg)](https://badge.fury.io/rb/defra_ruby_address)
 [![Licence](https://img.shields.io/badge/Licence-OGLv3-blue.svg)](http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3)
 
@@ -47,14 +47,23 @@ DefraRuby::Address.configure do |config|
 end
 ```
 
+To use the OS API service, you need to configure your API key from the [OS Data Hub](https://osdatahub.os.uk/). The host defaults to `https://api.os.uk/search/places/v1`:
+
+```ruby
+DefraRuby::Address.configure do |config|
+  config.key = ENV["OS_API_KEY"]
+end
+```
+
 ## Usage
 
-The gem interfaces with 2 address lookups
+The gem interfaces with 3 address lookups
 
 - [OS Places Address Lookup](https://github.com/DEFRA/os-places-address-lookup)
 - [EA Address Facade](https://github.com/DEFRA/ea-address-facade) (repo is private)
+- [OS API](https://docs.os.uk/os-apis/accessing-os-apis/os-places-api) (Ordnance Survey Places API)
 
-The **EA Address Facade** has 2 versions, so the gem provides 3 separate services a host app can use.
+The **EA Address Facade** has 2 versions, and combined with the other lookups, the gem provides 4 separate services a host app can use.
 
 ### Response object
 
@@ -210,6 +219,73 @@ The expected format of each result is
 }
 ```
 
+### OS API Address Lookup v1
+
+This service calls the [Ordnance Survey Places API](https://docs.os.uk/os-apis/accessing-os-apis/os-places-api) directly, without going through an intermediary service. It returns results mapped to the same format as the EA Address Facade v1.1, making it a drop-in replacement.
+
+> **Note:** The OS API is subject to a 600 transactions-per-minute throttle. Applications using this service should implement their own caching and/or rate limiting to stay within this limit.
+
+```ruby
+response = DefraRuby::Address::OsApiAddressLookupV1Service.run("BS1 5AH")
+
+puts response.results.first["uprn"] # 340116
+```
+
+The expected format of each result matches the EA Address Facade v1.1 format:
+
+```ruby
+{
+  "uprn"=>340116,
+  "address"=>"ENVIRONMENT AGENCY, HORIZON HOUSE, DEANERY ROAD, BRISTOL, BS1 5AH",
+  "organisation"=>"ENVIRONMENT AGENCY",
+  "premises"=>"HORIZON HOUSE",
+  "street_address"=>"DEANERY ROAD",
+  "locality"=>nil,
+  "city"=>"BRISTOL",
+  "postcode"=>"BS1 5AH",
+  "country"=>"United Kingdom",
+  "x"=>358205.03,
+  "y"=>172708.07,
+  "coordinate_system"=>nil,
+  "blpu_state_date"=>"12/10/2009",
+  "blpu_state_code"=>"2",
+  "postal_address_code"=>"D",
+  "logical_status_code"=>"1",
+  "source_data_type"=>"dpa",
+  "blpu_state_code_description"=>"In use",
+  "classification_code"=>"CO01",
+  "classification_code_description"=>"Office / Work Studio",
+  "lpi_logical_status_code"=>nil,
+  "lpi_logical_status_code_description"=>nil,
+  "match"=>1.0,
+  "match_description"=>"EXACT",
+  "topography_layer_toid"=>"osgb1000002529079737",
+  "parent_uprn"=>nil,
+  "last_update_date"=>"10/02/2016",
+  "status"=>"APPROVED",
+  "entry_date"=>"12/10/2009",
+  "postal_address_code_description"=>"A record which is linked to PAF",
+  "usrn"=>nil,
+  "language"=>"EN"
+}
+```
+
+### Coordinate conversion
+
+The gem also provides a pair of services for converting British National Grid easting and northing coordinates (OSGB36) to WGS84 latitude and longitude, and back again, for example to support geospatial queries.
+
+The conversion is pure Ruby, using the 7-parameter Helmert transformation and Transverse Mercator formulae from the OS guide [A guide to coordinate systems in Great Britain](https://www.ordnancesurvey.co.uk/documents/resources/guide-coordinate-systems-great-britain.pdf), and is accurate to around 5 metres.
+
+Unlike the address lookup services these do not call an external API, and they return a plain hash rather than a `Response` object. String arguments are coerced to floats.
+
+```ruby
+DefraRuby::Address::EastingNorthingToLatLonService.run(358_130, 172_688)
+# => { latitude: 51.45161..., longitude: -2.60394... }
+
+DefraRuby::Address::LatLonToEastingNorthingService.run(51.451616, -2.603943)
+# => { easting: 358129.8..., northing: 172687.8... }
+```
+
 ## Contributing to this project
 
 If you have an idea you'd like to contribute please log an issue.

data/Rakefile

@@ -11,7 +11,6 @@ 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"
 
@@ -26,8 +25,9 @@ begin
   require "github_changelog_generator/task"
 
   GitHubChangelogGenerator::RakeTask.new :changelog do |config|
+    config.user = "defra"
+    config.project = "defra-ruby-address"
   end
 rescue LoadError
   # no changelog available
 end
-# rubocop:enable Lint/HandleExceptions

data/bin/console

@@ -6,9 +6,5 @@ require "defra_ruby/address"
 # 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__)
+require "pry"
+Pry.start

data/lib/defra_ruby/address/helmert_transformation.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Address
+    # Shifts latitude/longitude between the OSGB36 and WGS84 datums using the
+    # 7-parameter Helmert transformation from the OS guide "A guide to
+    # coordinate systems in Great Britain". Accurate to around 5 metres.
+    #
+    # The OSGB36 to WGS84 direction is ported from the breasal gem
+    # (https://github.com/theodi/breasal, MIT licence, copyright 2013
+    # pezholio), corrected to the published OS guide parameters. The reverse
+    # direction just negates them.
+    class HelmertTransformation
+      AIRY_1830 = { a: 6_377_563.396, b: 6_356_256.909 }.freeze
+      WGS84 = { a: 6_378_137.0, b: 6_356_752.3141 }.freeze
+
+      ARC_SECOND_IN_RADIANS = Math::PI / 648_000
+
+      # Translations (tx, ty, tz) in metres, scale change (s) in parts per
+      # unit and rotations (rx, ry, rz) in radians, for the OSGB36 to WGS84
+      # direction; negated they transform in the opposite direction.
+      PARAMETERS = {
+        tx: 446.448,
+        ty: -125.157,
+        tz: 542.060,
+        s: -0.0000204894,
+        rx: 0.1502 * ARC_SECOND_IN_RADIANS,
+        ry: 0.2470 * ARC_SECOND_IN_RADIANS,
+        rz: 0.8421 * ARC_SECOND_IN_RADIANS
+      }.freeze
+
+      def self.osgb36_to_wgs84(latitude, longitude)
+        new(AIRY_1830, WGS84, 1).transform(latitude, longitude)
+      end
+
+      def self.wgs84_to_osgb36(latitude, longitude)
+        new(WGS84, AIRY_1830, -1).transform(latitude, longitude)
+      end
+
+      def initialize(source_ellipsoid, target_ellipsoid, direction)
+        @source_ellipsoid = source_ellipsoid
+        @target_ellipsoid = target_ellipsoid
+        @direction = direction
+      end
+
+      def transform(latitude, longitude)
+        to_geodetic(apply_helmert(to_cartesian(latitude, longitude)))
+      end
+
+      private
+
+      attr_reader :source_ellipsoid, :target_ellipsoid, :direction
+
+      def to_cartesian(latitude, longitude)
+        e_squared = eccentricity_squared(source_ellipsoid)
+        phi = latitude * Math::PI / 180
+        lambda = longitude * Math::PI / 180
+        nu = source_ellipsoid[:a] / Math.sqrt(1.0 - (e_squared * (Math.sin(phi)**2)))
+
+        [nu * Math.cos(phi) * Math.cos(lambda),
+         nu * Math.cos(phi) * Math.sin(lambda),
+         (1.0 - e_squared) * nu * Math.sin(phi)]
+      end
+
+      def apply_helmert(cartesian)
+        x, y, z = cartesian
+        scale = 1.0 + parameter(:s)
+        rx = parameter(:rx)
+        ry = parameter(:ry)
+        rz = parameter(:rz)
+
+        [parameter(:tx) + (scale * x) - (rz * y) + (ry * z),
+         parameter(:ty) + (rz * x) + (scale * y) - (rx * z),
+         parameter(:tz) - (ry * x) + (rx * y) + (scale * z)]
+      end
+
+      def to_geodetic(cartesian)
+        x, y, z = cartesian
+        e_squared = eccentricity_squared(target_ellipsoid)
+        p = Math.hypot(x, y)
+        phi = Math.atan(z / (p * (1.0 - e_squared)))
+
+        10.times do
+          nu = target_ellipsoid[:a] / Math.sqrt(1.0 - (e_squared * (Math.sin(phi)**2)))
+          phi = Math.atan((z + (e_squared * nu * Math.sin(phi))) / p)
+        end
+
+        [phi * 180 / Math::PI, Math.atan2(y, x) * 180 / Math::PI]
+      end
+
+      def parameter(key)
+        direction * PARAMETERS[key]
+      end
+
+      def eccentricity_squared(ellipsoid)
+        a = ellipsoid[:a]
+        b = ellipsoid[:b]
+        ((a * a) - (b * b)) / (a * a)
+      end
+    end
+  end
+end

data/lib/defra_ruby/address/response.rb

@@ -3,8 +3,7 @@
 module DefraRuby
   module Address
     class Response
-      attr_reader :error
-      attr_reader :results
+      attr_reader :error, :results
 
       def initialize(response_exe)
         @success = true

data/lib/defra_ruby/address/services/base_service.rb

@@ -6,8 +6,8 @@ require "rest-client"
 module DefraRuby
   module Address
     class BaseService
-      def self.run(attrs = nil)
-        new.run(attrs)
+      def self.run(*)
+        new.run(*)
       end
     end
   end

data/lib/defra_ruby/address/services/easting_northing_to_lat_lon_service.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Address
+    # Converts a British National Grid easting and northing to a WGS84
+    # latitude and longitude. Accurate to around 5 metres.
+    class EastingNorthingToLatLonService < BaseService
+      def run(easting, northing)
+        osgb36_latitude, osgb36_longitude = TransverseMercatorProjection.easting_northing_to_lat_lon(
+          Float(easting), Float(northing)
+        )
+        latitude, longitude = HelmertTransformation.osgb36_to_wgs84(osgb36_latitude, osgb36_longitude)
+
+        { latitude: latitude, longitude: longitude }
+      end
+    end
+  end
+end

data/lib/defra_ruby/address/services/lat_lon_to_easting_northing_service.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Address
+    # Converts a WGS84 latitude and longitude to a British National Grid
+    # easting and northing. Accurate to around 5 metres.
+    class LatLonToEastingNorthingService < BaseService
+      def run(latitude, longitude)
+        osgb36_latitude, osgb36_longitude = HelmertTransformation.wgs84_to_osgb36(
+          Float(latitude), Float(longitude)
+        )
+        easting, northing = TransverseMercatorProjection.lat_lon_to_easting_northing(
+          osgb36_latitude, osgb36_longitude
+        )
+
+        { easting: easting, northing: northing }
+      end
+    end
+  end
+end

data/lib/defra_ruby/address/services/os_api_address_lookup_v1_service.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Address
+    class OsApiAddressLookupV1Service < BaseService
+
+      # Mapping from OS API DPA field names to EaAddressFacade field names
+      # rubocop:disable Layout/HashAlignment
+      FIELD_MAPPING = {
+        "UPRN"                           => "uprn",
+        "ADDRESS"                        => "address",
+        "ORGANISATION_NAME"              => "organisation",
+        "BUILDING_NAME"                  => "premises",
+        "THOROUGHFARE_NAME"              => "street_address",
+        "DEPENDENT_LOCALITY"             => "locality",
+        "POST_TOWN"                      => "city",
+        "POSTCODE"                       => "postcode",
+        "X_COORDINATE"                   => "x",
+        "Y_COORDINATE"                   => "y",
+        "BLPU_STATE_DATE"                => "blpu_state_date",
+        "BLPU_STATE_CODE"                => "blpu_state_code",
+        "POSTAL_ADDRESS_CODE"            => "postal_address_code",
+        "LOGICAL_STATUS_CODE"            => "logical_status_code",
+        "BLPU_STATE_CODE_DESCRIPTION"    => "blpu_state_code_description",
+        "CLASSIFICATION_CODE"            => "classification_code",
+        "CLASSIFICATION_CODE_DESCRIPTION" => "classification_code_description",
+        "MATCH"                          => "match",
+        "MATCH_DESCRIPTION"              => "match_description",
+        "TOPOGRAPHY_LAYER_TOID"          => "topography_layer_toid",
+        "PARENT_UPRN"                    => "parent_uprn",
+        "LAST_UPDATE_DATE"               => "last_update_date",
+        "STATUS"                         => "status",
+        "ENTRY_DATE"                     => "entry_date",
+        "POSTAL_ADDRESS_CODE_DESCRIPTION" => "postal_address_code_description",
+        "USRN"                           => "usrn",
+        "LANGUAGE"                       => "language"
+      }.freeze
+      # rubocop:enable Layout/HashAlignment
+
+      DEFAULT_HOST = "https://api.os.uk/search/places/v1"
+
+      def run(postcode)
+        @postcode = postcode
+        Response.new(response_exe)
+      end
+
+      private
+
+      attr_reader :postcode
+
+      def url
+        host = DefraRuby::Address.configuration.host || DEFAULT_HOST
+
+        File.join(
+          host,
+          "postcode?postcode=#{postcode}&key=#{DefraRuby::Address.configuration.key}"
+        )
+      end
+
+      def response_exe
+        lambda do
+          response = RestClient::Request.execute(
+            method: :get,
+            url: url,
+            timeout: DefraRuby::Address.configuration.timeout
+          )
+          parsed = JSON.parse(response)
+          results = parsed["results"] || []
+
+          raise DefraRuby::Address::NoMatchError if results.empty?
+
+          results.map { |r| map_dpa_to_result(r["DPA"]) }
+        end
+      end
+
+      def map_dpa_to_result(dpa)
+        result = map_fields(dpa)
+        result["uprn"] = result["uprn"]&.to_i
+        result.merge(hardcoded_fields)
+      end
+
+      def map_fields(dpa)
+        FIELD_MAPPING.each_with_object({}) do |(os_key, facade_key), hash|
+          hash[facade_key] = dpa[os_key]
+        end
+      end
+
+      def hardcoded_fields
+        {
+          "country" => "United Kingdom",
+          "coordinate_system" => nil,
+          "source_data_type" => "dpa",
+          "lpi_logical_status_code" => nil,
+          "lpi_logical_status_code_description" => nil
+        }
+      end
+
+    end
+  end
+end

data/lib/defra_ruby/address/services/os_places_address_lookup_service.rb

@@ -3,6 +3,7 @@
 module DefraRuby
   module Address
     class OsPlacesAddressLookupService < BaseService
+      OS_PLACES_ADDRESS_LOOKUP_NO_MATCH_ERROR_MSG = "Parameters are not valid"
 
       def run(postcode)
         @postcode = postcode
@@ -11,8 +12,6 @@ module DefraRuby
 
       private
 
-      OS_PLACES_ADDRESS_LOOKUP_NO_MATCH_ERROR_MSG = "Parameters are not valid"
-
       attr_reader :postcode
 
       def url
@@ -24,16 +23,16 @@ module DefraRuby
 
       def response_exe
         lambda do
-          begin
-            response = RestClient::Request.execute(
-              method: :get,
-              url: url,
-              timeout: DefraRuby::Address.configuration.timeout
-            )
-            JSON.parse(response)
-          rescue RestClient::BadRequest => e
-            raise process_error(e)
-          end
+
+          response = RestClient::Request.execute(
+            method: :get,
+            url: url,
+            timeout: DefraRuby::Address.configuration.timeout
+          )
+          JSON.parse(response)
+        rescue RestClient::BadRequest => e
+          raise process_error(e)
+
         end
       end
 
@@ -43,8 +42,6 @@ module DefraRuby
         end
       rescue StandardError
         error
-      ensure
-        error
       end
     end
   end

data/lib/defra_ruby/address/transverse_mercator_projection.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Address
+    # Converts between British National Grid easting/northing and OSGB36
+    # latitude/longitude, a Transverse Mercator projection on the Airy 1830
+    # ellipsoid. Variable names follow the terms in the OS guide "A guide to
+    # coordinate systems in Great Britain".
+    #
+    # The easting/northing to lat/lon direction is ported from the breasal
+    # gem (https://github.com/theodi/breasal, MIT licence, copyright 2013
+    # pezholio). Breasal has no reverse conversion, so that direction comes
+    # straight from the OS guide's forward projection formulae.
+    class TransverseMercatorProjection
+      A = HelmertTransformation::AIRY_1830[:a]
+      B = HelmertTransformation::AIRY_1830[:b]
+      E_SQUARED = ((A * A) - (B * B)) / (A * A)
+      N = (A - B) / (A + B)
+
+      F0 = 0.9996012717
+      PHI0 = 49.0 * Math::PI / 180
+      LAMBDA0 = -2.0 * Math::PI / 180
+      E0 = 400_000.0
+      N0 = -100_000.0
+
+      def self.easting_northing_to_lat_lon(easting, northing)
+        new.easting_northing_to_lat_lon(easting, northing)
+      end
+
+      def self.lat_lon_to_easting_northing(latitude, longitude)
+        new.lat_lon_to_easting_northing(latitude, longitude)
+      end
+
+      def easting_northing_to_lat_lon(easting, northing)
+        phi_prime = converged_phi_prime(northing)
+        delta_e = easting - E0
+
+        [latitude_from(phi_prime, delta_e) * 180 / Math::PI,
+         longitude_from(phi_prime, delta_e) * 180 / Math::PI]
+      end
+
+      def lat_lon_to_easting_northing(latitude, longitude)
+        phi = latitude * Math::PI / 180
+        delta_lambda = (longitude * Math::PI / 180) - LAMBDA0
+
+        [easting_from(phi, delta_lambda), northing_from(phi, delta_lambda)]
+      end
+
+      private
+
+      # Converges within a few iterations for any real coordinates; the cap
+      # guards against non-finite input looping forever
+      def converged_phi_prime(northing)
+        phi_prime = ((northing - N0) / (A * F0)) + PHI0
+
+        100.times do
+          delta = northing - N0 - meridional_arc(phi_prime)
+          break if delta < 0.001
+
+          phi_prime += delta / (A * F0)
+        end
+
+        phi_prime
+      end
+
+      # The methods below are a straight port of the OS guide formulae; the
+      # ABC metric counts every arithmetic operator, so is disabled for them.
+      # rubocop:disable Metrics/AbcSize
+
+      # M in the OS guide
+      def meridional_arc(phi)
+        delta_phi = phi - PHI0
+        sum_phi = phi + PHI0
+
+        B * F0 * (((1 + N + ((5.0 / 4) * (N**2)) + ((5.0 / 4) * (N**3))) * delta_phi) -
+          (((3 * N) + (3 * (N**2)) + ((21.0 / 8) * (N**3))) * Math.sin(delta_phi) * Math.cos(sum_phi)) +
+          ((((15.0 / 8) * (N**2)) + ((15.0 / 8) * (N**3))) * Math.sin(2 * delta_phi) * Math.cos(2 * sum_phi)) -
+          (((35.0 / 24) * (N**3)) * Math.sin(3 * delta_phi) * Math.cos(3 * sum_phi)))
+      end
+
+      # Terms VII, VIII and IX in the OS guide
+      def latitude_from(phi_prime, delta_e)
+        tan = Math.tan(phi_prime)
+        tan2 = tan**2
+        nu = nu(phi_prime)
+        rho = rho(phi_prime)
+        eta_squared = (nu / rho) - 1.0
+
+        vii = tan / (2 * rho * nu)
+        viii = (tan / (24 * rho * (nu**3))) * (5 + (3 * tan2) + eta_squared - (9 * tan2 * eta_squared))
+        ix = (tan / (720 * rho * (nu**5))) * (61 + (90 * tan2) + (45 * (tan2**2)))
+
+        phi_prime - (vii * (delta_e**2)) + (viii * (delta_e**4)) - (ix * (delta_e**6))
+      end
+
+      # Terms X, XI, XII and XIIA in the OS guide
+      def longitude_from(phi_prime, delta_e)
+        sec = 1.0 / Math.cos(phi_prime)
+        tan2 = Math.tan(phi_prime)**2
+        nu = nu(phi_prime)
+
+        x = sec / nu
+        xi = (sec / (6 * (nu**3))) * ((nu / rho(phi_prime)) + (2 * tan2))
+        xii = (sec / (120 * (nu**5))) * (5 + (28 * tan2) + (24 * (tan2**2)))
+        xiia = (sec / (5040 * (nu**7))) * (61 + (662 * tan2) + (1320 * (tan2**2)) + (720 * (tan2**3)))
+
+        LAMBDA0 + (x * delta_e) - (xi * (delta_e**3)) + (xii * (delta_e**5)) - (xiia * (delta_e**7))
+      end
+
+      # Terms IV, V and VI in the OS guide
+      def easting_from(phi, delta_lambda)
+        nu = nu(phi)
+        rho = rho(phi)
+        eta_squared = (nu / rho) - 1.0
+        cos_phi = Math.cos(phi)
+        tan2 = Math.tan(phi)**2
+
+        iv = nu * cos_phi
+        v = (nu / 6) * (cos_phi**3) * ((nu / rho) - tan2)
+        vi = (nu / 120) * (cos_phi**5) * (5 - (18 * tan2) + (tan2**2) + (14 * eta_squared) - (58 * tan2 * eta_squared))
+
+        E0 + (iv * delta_lambda) + (v * (delta_lambda**3)) + (vi * (delta_lambda**5))
+      end
+
+      # Terms I, II, III and IIIA in the OS guide
+      def northing_from(phi, delta_lambda)
+        nu = nu(phi)
+        eta_squared = (nu / rho(phi)) - 1.0
+        sin_phi = Math.sin(phi)
+        cos_phi = Math.cos(phi)
+        tan2 = Math.tan(phi)**2
+
+        i = meridional_arc(phi) + N0
+        ii = (nu / 2) * sin_phi * cos_phi
+        iii = (nu / 24) * sin_phi * (cos_phi**3) * (5 - tan2 + (9 * eta_squared))
+        iiia = (nu / 720) * sin_phi * (cos_phi**5) * (61 - (58 * tan2) + (tan2**2))
+
+        i + (ii * (delta_lambda**2)) + (iii * (delta_lambda**4)) + (iiia * (delta_lambda**6))
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def nu(phi)
+        A * F0 * ((1.0 - (E_SQUARED * (Math.sin(phi)**2)))**-0.5)
+      end
+
+      def rho(phi)
+        A * F0 * (1.0 - E_SQUARED) * ((1.0 - (E_SQUARED * (Math.sin(phi)**2)))**-1.5)
+      end
+    end
+  end
+end

data/lib/defra_ruby/address/version.rb

@@ -2,6 +2,6 @@
 
 module DefraRuby
   module Address
-    VERSION = "0.1.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/defra_ruby/address.rb

@@ -2,12 +2,17 @@
 
 require_relative "address/configuration"
 require_relative "address/ea_address_facade_request"
+require_relative "address/helmert_transformation"
 require_relative "address/no_match_error"
 require_relative "address/response"
+require_relative "address/transverse_mercator_projection"
 
 require_relative "address/services/base_service"
 require_relative "address/services/ea_address_facade_v1_1_service"
 require_relative "address/services/ea_address_facade_v1_service"
+require_relative "address/services/easting_northing_to_lat_lon_service"
+require_relative "address/services/lat_lon_to_easting_northing_service"
+require_relative "address/services/os_api_address_lookup_v1_service"
 require_relative "address/services/os_places_address_lookup_service"
 
 module DefraRuby