uk_county_locator 0.1.0

data/lib/uk_county_locator/aliases/historic_county_aliases.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module UkCountyLocator
+  module Aliases
+    # rubocop:disable Metrics/ModuleLength
+    module HistoricCountyAliases
+      HISTORIC_COUNTY_ALIASES = {
+        'Aber' => 'Aberdeenshire',
+        'County of Aberdeen' => 'Aberdeenshire',
+        'Siorrachd Obar Dheathain' => 'Aberdeenshire',
+        'Obar Dheathain' => 'Aberdeenshire',
+        'Angl' => 'Anglesey',
+        'Ynys Mon' => 'Anglesey',
+        'Ynys Môn' => 'Anglesey',
+        'Sir Fôn' => 'Anglesey',
+        'Sir Môn' => 'Anglesey',
+        'Sir Fon' => 'Anglesey',
+        'Sir Mon' => 'Anglesey',
+        'Aonghas' => 'Angus',
+        'County Antrim' => 'Antrim',
+        'Co Antrim' => 'Antrim',
+        'Contae Aontroma' => 'Antrim',
+        'Aontroma' => 'Antrim',
+        'Coontie Antrìm' => 'Antrim',
+        'Argyll' => 'Argyllshire',
+        'Argyle' => 'Argyllshire',
+        'Earra-Ghàidheal' => 'Argyllshire',
+        'Earra-Ghaidheal' => 'Argyllshire',
+        'Co Armagh' => 'Armagh',
+        'County Armagh' => 'Armagh',
+        'Contae Ard Mhacha' => 'Armagh',
+        'Ard Mhacha' => 'Armagh',
+        'Coontie Airmagh' => 'Armagh',
+        'Airmagh' => 'Armagh',
+        'Coontie Armagh' => 'Armagh',
+        'Ayr' => 'Ayrshire',
+        'Siorrachd Inbhir Àir' => 'Ayrshire',
+        'Inbhir Àir' => 'Ayrshire',
+        'Inbhir Air' => 'Ayrshire',
+        'Banff' => 'Banffshire',
+        'Siorrachd Bhanbh' => 'Banffshire',
+        'Bhanbh' => 'Banffshire',
+        'Beds' => 'Bedfordshire',
+        'Berks' => 'Berkshire',
+        'Berwick' => 'Berwickshire',
+        'Bhearaig' => 'Berwickshire',
+        'Siorrachd Bhearaig' => 'Berwickshire',
+        'Breconshire' => 'Brecknockshire',
+        'Brecon' => 'Brecknockshire',
+        'Brecknockshire' => 'Brecknockshire',
+        'Brecknock' => 'Brecknockshire',
+        'Brycheiniog' => 'Brecknockshire',
+        'Sir Brycheiniog' => 'Brecknockshire',
+        'Brecks' => 'Brecknockshire',
+        'Bcshire' => 'Brecknockshire',
+        'Brecs' => 'Brecknockshire',
+        'Bucks' => 'Buckinghamshire',
+        'Bute' => 'Buteshire',
+        'Bhòid' => 'Buteshire',
+        'Bhoid' => 'Buteshire',
+        'Siorrachd Bhòid' => 'Buteshire',
+        'Siorrachd Bhoid' => 'Buteshire',
+        'County of Bute' => 'Buteshire',
+        'Caerns' => 'Caernarfonshire',
+        'Carnarvonshire' => 'Caernarfonshire',
+        'Carnarvon' => 'Caernarfonshire',
+        'Caernarvon' => 'Caernarfonshire',
+        'Gaernarfon' => 'Caernarfonshire',
+        'Sir Gaernarfon' => 'Caernarfonshire',
+        'Carn' => 'Caernarfonshire',
+        'Caith' => 'Caithness',
+        'Gallaibh' => 'Caithness',
+        'Cambs' => 'Cambridgeshire',
+        'Cards' => 'Cardiganshire',
+        'Cardigan' => 'Cardiganshire',
+        'Sir Aberteifi' => 'Cardiganshire',
+        'Aberteifi' => 'Cardiganshire',
+        'Sir Ceredigion' => 'Cardiganshire',
+        'Ceredigion' => 'Cardiganshire',
+        'Carms' => 'Carmarthenshire',
+        'Carmarthen' => 'Carmarthenshire',
+        'Sir Gaerfyrddin' => 'Carmarthenshire',
+        'Gaerfyrddin' => 'Carmarthenshire',
+        'Ches' => 'Cheshire',
+        'Clackm' => 'Clackmannanshire',
+        'Siorrachd Chlach Mhanann' => 'Clackmannanshire',
+        'Chlach Mhanann' => 'Clackmannanshire',
+        'Corn' => 'Cornwall',
+        'Cornw' => 'Cornwall',
+        'Cumb' => 'Cumberland',
+        'Denbigh' => 'Denbighshire',
+        'Denbs' => 'Denbighshire',
+        'Sir Ddinbych' => 'Denbighshire',
+        'Ddinbych' => 'Denbighshire',
+        'Derbs' => 'Derbyshire',
+        'Dev' => 'Devon',
+        'Dor' => 'Dorset',
+        'County Down' => 'Down',
+        'Co Down' => 'Down',
+        'Contae an Dúin' => 'Down',
+        'Contae an Duin' => 'Down',
+        'Dúin' => 'Down',
+        'Duin' => 'Down',
+        'Coontie Doon' => 'Down',
+        'Doon' => 'Down',
+        'Countie Doun' => 'Down',
+        'Doun' => 'Down',
+        'Dumfries' => 'Dumfriesshire',
+        'Siorrachd Dhùn Phris' => 'Dumfriesshire',
+        'Dhùn Phris' => 'Dumfriesshire',
+        'Dhun Phris' => 'Dumfriesshire',
+        'Dunbar' => 'Dunbartonshire',
+        'Siorrachd Dhùn Breatann' => 'Dunbartonshire',
+        'Siorrachd Dhun Breatann' => 'Dunbartonshire',
+        'Dhùn Breatann' => 'Dunbartonshire',
+        'Dhun Breatann' => 'Dunbartonshire',
+        'Durham' => 'County Durham',
+        'Co Durham' => 'County Durham',
+        'Co Dur' => 'County Durham',
+        'Dur' => 'County Durham',
+        'East Loth' => 'East Lothian',
+        'E Lothian' => 'East Lothian',
+        'E Loth' => 'East Lothian',
+        'Lodainn an Ear' => 'East Lothian',
+        'Fermanagh' => 'County Fermanagh',
+        'Co Fermanagh' => 'County Fermanagh',
+        'Contae Fhear Manach' => 'County Fermanagh',
+        'Fhear Manach' => 'County Fermanagh',
+        'Contae Fir Manach' => 'County Fermanagh',
+        'Fir Manach' => 'County Fermanagh',
+        'Coontie Fermanay' => 'County Fermanagh',
+        'Fermanay' => 'County Fermanagh',
+        'Fìobha' => 'Fife',
+        'Fiobha' => 'Fife',
+        'Flint' => 'Flintshire',
+        'Flints' => 'Flintshire',
+        'Sir y Fflint' => 'Flintshire',
+        'Fflint' => 'Flintshire',
+        'Glamorganshire' => 'Glamorgan',
+        'Glam' => 'Glamorgan',
+        'Sir Forgannwg' => 'Glamorgan',
+        'Forgannwg' => 'Glamorgan',
+        'Sir Morgannwg' => 'Glamorgan',
+        'Morgannwg' => 'Glamorgan',
+        'Glos' => 'Gloucestershire',
+        'Gloucs' => 'Gloucestershire',
+        'Hants' => 'Hampshire',
+        'Here' => 'Herefordshire',
+        'Heref' => 'Herefordshire',
+        'Herts' => 'Hertfordshire',
+        'Hunts' => 'Huntingdonshire',
+        'Inver' => 'Inverness-shire',
+        'Siorrachd Inbhir Nis' => 'Inverness-shire',
+        'Inbhir Nis' => 'Inverness-shire',
+        'Kincar' => 'Kincardineshire',
+        'The Mearns' => 'Kincardineshire',
+        "A' Mhaoirne" => 'Kincardineshire',
+        'Kinross' => 'Kinross-shire',
+        'Ceann Rois' => 'Kinross-shire',
+        'Kirkcud' => 'Kirkcudbrightshire',
+        'Cille Chuithbeirt' => 'Kirkcudbrightshire',
+        'Lanark' => 'Lanarkshire',
+        'Siorrachd Lannraig' => 'Lanarkshire',
+        'Lannraig' => 'Lanarkshire',
+        'Lancs' => 'Lancashire',
+        'Leics' => 'Leicestershire',
+        'Lincs' => 'Lincolnshire',
+        'Co Londonderry' => 'Londonderry',
+        'County Londonderry' => 'Londonderry',
+        'County Derry' => 'Londonderry',
+        'Derry' => 'Londonderry',
+        'Co Derry' => 'Londonderry',
+        'Contae Dhoire' => 'Londonderry',
+        'Dhoire' => 'Londonderry',
+        'Coontie Lunnonderrie' => 'Londonderry',
+        'Lunnonderrie' => 'Londonderry',
+        'Merion' => 'Merionethshire',
+        'Merioneth' => 'Merionethshire',
+        'Sir Feirionnydd' => 'Merionethshire',
+        'Feirionnydd' => 'Merionethshire',
+        'Sir Meirionydd' => 'Merionethshire',
+        'Meirionydd' => 'Merionethshire',
+        'Sir Meirion' => 'Merionethshire',
+        'Meirion' => 'Merionethshire',
+        'Mx' => 'Middlesex',
+        'Middx' => 'Middlesex',
+        'Mddx' => 'Middlesex',
+        "M'sex" => 'Middlesex',
+        'Midloth' => 'Midlothian',
+        'Meadhan Lodainn' => 'Midlothian',
+        'Mons' => 'Monmouthshire',
+        'Mon' => 'Monmouthshire',
+        'Monmouth' => 'Monmouthshire',
+        'Monshire' => 'Monmouthshire',
+        'Sir Fynwy' => 'Monmouthshire',
+        'Fynwy' => 'Monmouthshire',
+        'Sir Mynwy' => 'Monmouthshire',
+        'Mynwy' => 'Monmouthshire',
+        'Mont' => 'Montgomeryshire',
+        'Montg' => 'Montgomeryshire',
+        'Montgomery' => 'Montgomeryshire',
+        'Sir Drefaldwyn' => 'Montgomeryshire',
+        'Drefaldwyn' => 'Montgomeryshire',
+        'Sir Maldwyn' => 'Montgomeryshire',
+        'Maldwyn' => 'Montgomeryshire',
+        'Moray' => 'Morayshire',
+        'County of Moray' => 'Morayshire',
+        'Moireibh' => 'Morayshire',
+        'Nairn' => 'Nairnshire',
+        'County of Nairn' => 'Nairnshire',
+        'Siorrachd Inbhir Narann' => 'Nairnshire',
+        'Inbhir Narann' => 'Nairnshire',
+        'Norf' => 'Norfolk',
+        'Northants' => 'Northamptonshire',
+        'Northumb' => 'Northumberland',
+        'Northd' => 'Northumberland',
+        'Notts' => 'Nottinghamshire',
+        'Orkney Islands' => 'Orkney',
+        'Arcaibh' => 'Orkney',
+        'Oxon' => 'Oxfordshire',
+        'Peebles' => 'Peeblesshire',
+        'Siorrachd nam Pùballan' => 'Peeblesshire',
+        'Siorrachd nam Puballan' => 'Peeblesshire',
+        'nam Pùballan' => 'Peeblesshire',
+        'nam Puballan' => 'Peeblesshire',
+        'Pembs' => 'Pembrokeshire',
+        'Pem' => 'Pembrokeshire',
+        'Pemb' => 'Pembrokeshire',
+        'Pembroke' => 'Pembrokeshire',
+        'Sir Benfro' => 'Pembrokeshire',
+        'Benfro' => 'Pembrokeshire',
+        'Sir Penfro' => 'Pembrokeshire',
+        'Penfro' => 'Pembrokeshire',
+        'Perth' => 'Perthshire',
+        'Siorrachd Pheairt' => 'Perthshire',
+        'Pheairt' => 'Perthshire',
+        'Radnor' => 'Radnorshire',
+        'Rad' => 'Radnorshire',
+        'Rads' => 'Radnorshire',
+        'Sir Raesyfed' => 'Radnorshire',
+        'Raesyfed' => 'Radnorshire',
+        'Sir Maesyfed' => 'Radnorshire',
+        'Maesyfed' => 'Radnorshire',
+        'Renfrew' => 'Renfrewshire',
+        'Siorrachd Rinn Friù' => 'Renfrewshire',
+        'Siorrachd Rinn Friu' => 'Renfrewshire',
+        'Rinn Friù' => 'Renfrewshire',
+        'Rinn Friu' => 'Renfrewshire',
+        'Ross-shire and Cromartyshire' => 'Ross-shire & Cromartyshire',
+        'Ross' => 'Ross-shire & Cromartyshire',
+        'Crom' => 'Ross-shire & Cromartyshire',
+        'Ross and Crom' => 'Ross-shire & Cromartyshire',
+        'Ross & Crom' => 'Ross-shire & Cromartyshire',
+        'Ross-shire' => 'Ross-shire & Cromartyshire',
+        'Cromartyshire' => 'Ross-shire & Cromartyshire',
+        'Siorrachd Rois' => 'Ross-shire & Cromartyshire',
+        'Rois' => 'Ross-shire & Cromartyshire',
+        'Siorrachd Chromba' => 'Ross-shire & Cromartyshire',
+        'Chromba' => 'Ross-shire & Cromartyshire',
+        'Roxb' => 'Roxburghshire',
+        'Siorrachd Rosbroig' => 'Roxburghshire',
+        'Rosbroig' => 'Roxburghshire',
+        'Rutlandshire' => 'Rutland',
+        'Rut' => 'Rutland',
+        'Selk' => 'Selkirkshire',
+        'Siorrachd Shalcraig' => 'Selkirkshire',
+        'Shalcraig' => 'Selkirkshire',
+        'Shetland Islands' => 'Shetland',
+        'Zetland' => 'Shetland',
+        'Sealtainn' => 'Shetland',
+        'Shrops' => 'Shropshire',
+        'Salop' => 'Shropshire',
+        'Somersetshire' => 'Somerset',
+        'Som' => 'Somerset',
+        'Staffs' => 'Staffordshire',
+        'Staf' => 'Staffordshire',
+        'Stirl' => 'Stirlingshire',
+        'Siorrachd Sruighlea' => 'Stirlingshire',
+        'Sruighlea' => 'Stirlingshire',
+        'Suff' => 'Suffolk',
+        'Surr' => 'Surrey',
+        'Sy' => 'Surrey',
+        'Sx' => 'Sussex',
+        'Ssx' => 'Sussex',
+        'Suther' => 'Sutherland',
+        'Cataibh' => 'Sutherland',
+        'Co Tyrone' => 'County Tyrone',
+        'Tyrone' => 'County Tyrone',
+        'Tir Eoghain' => 'County Tyrone',
+        'Tír Eoghain' => 'County Tyrone',
+        'Contae Tír Eoghain' => 'County Tyrone',
+        'Contae Tir Eoghain' => 'County Tyrone',
+        'Coontie Owenslann' => 'County Tyrone',
+        'Owenslann' => 'County Tyrone',
+        'Warks' => 'Warwickshire',
+        'War' => 'Warwickshire',
+        'Warw' => 'Warwickshire',
+        'W Lothian' => 'West Lothian',
+        'West Loth' => 'West Lothian',
+        'W Loth' => 'West Lothian',
+        'Lodainn an Iar' => 'West Lothian',
+        'Westm' => 'Westmorland',
+        'Wigtown' => 'Wigtownshire',
+        'Siorrachd Bhaile na h-Ùige' => 'Wigtownshire',
+        'Siorrachd Bhaile na h-Uige' => 'Wigtownshire',
+        'Bhaile na h-Ùige' => 'Wigtownshire',
+        'Bhaile na h-Uige' => 'Wigtownshire',
+        'Wilts' => 'Wiltshire',
+        'Worcs' => 'Worcestershire',
+        'Worsts' => 'Worcestershire',
+        'Yorks' => 'Yorkshire'
+      }.freeze
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/uk_county_locator/argument_validator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module UkCountyLocator
+  # Class that encompasses all validations on user input
+  class ArgumentValidator
+    attr_reader :type, :lat, :lng, :county
+
+    VALID_COUNTY_TYPES = %i[current ceremonial historic].freeze
+
+    def initialize(request:, type:, lat: nil, lng: nil, county: nil)
+      @request = request
+      @type = verified_type(type)
+      @lat = parse_coordinate(lat, 'lat') if lat
+      @lng = parse_coordinate(lng, 'lat') if lat
+      @county = validated_county(county) if county
+    end
+
+    private
+
+    def verified_type(type)
+      type = type&.downcase&.to_sym
+      return type if valid_county_type?(type)
+
+      raise InvalidArgumentError, "Invalid input: type must be one of :current, :ceremonial, :historic.#{all_message}"\
+      ", got #{type}"
+    end
+
+    def valid_county_type?(type)
+      return true if type == :all && @request == :county
+
+      VALID_COUNTY_TYPES.include?(type)
+    end
+
+    def parse_coordinate(value, name)
+      if value.is_a?(String)
+        Float(value)
+      elsif value.is_a?(Numeric)
+        value.to_f
+      else
+        raise InvalidArgumentError, "Expected #{name} to be Numeric or a String, got #{value.class}"
+      end
+    rescue ArgumentError
+      raise InvalidArgumentError, "Invalid #{name} format: '#{value}'"
+    end
+
+    def validated_county(county)
+      return county if county.is_a?(String)
+
+      raise InvalidArgumentError, "Expected county to be a String, got #{county.class}"
+    end
+
+    def all_message
+      @request == :county ? ', or :all' : ''
+    end
+  end
+end

data/lib/uk_county_locator/locator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'polylines_service'
+require_relative 'polygons/ceremonial_county_polygons'
+require_relative 'polygons/historic_county_polygons'
+require_relative 'polygons/current_county_and_unitary_authority_polygons'
+
+module UkCountyLocator
+  # Locator is responsible for determining the county data (current, ceremonial, or historic)
+  # for a given latitude and longitude. It handles both general county data retrieval
+  # for all county types or specific retrieval based on a provided type. The class also
+  # integrates with the PolylinesService to check if the point lies within the defined county polygons.
+  class Locator
+    def initialize(lat, lng, type: :all)
+      @lat = lat
+      @lng = lng
+      @type = type
+    end
+
+    def county_data
+      return specific_county_type(@type) unless @type == :all
+
+      {
+        current_county_or_unitary_authority: find_county_within(current_county_and_unitary_authority_polygons),
+        ceremonial_county: find_county_within(ceremonial_county_polygons),
+        historic_county: find_county_within(historic_county_polygons)
+      }
+    end
+
+    private
+
+    def specific_county_type(county_type)
+      case county_type.downcase
+      when :current
+        find_county_within(current_county_and_unitary_authority_polygons)
+      when :ceremonial
+        find_county_within(ceremonial_county_polygons)
+      when :historic
+        find_county_within(historic_county_polygons)
+      end
+    end
+
+    def find_county_within(polygons)
+      polylines_service.point_inside_polygon?(polygons)
+    end
+
+    def polylines_service
+      @polylines_service ||= PolylinesService.new(lat: @lat, lng: @lng)
+    end
+
+    def current_county_and_unitary_authority_polygons
+      Polygons::CurrentCountyAndUnitaryAuthorityPolygons::CURRENT_COUNTY_AND_UNITARY_AUTHORITY_POLYGONS
+    end
+
+    def ceremonial_county_polygons
+      Polygons::CeremonialCountyPolygons::CEREMONIAL_COUNTY_POLYGONS
+    end
+
+    def historic_county_polygons
+      Polygons::HistoricCountyPolygons::HISTORIC_COUNTY_POLYGONS
+    end
+  end
+end

data/lib/uk_county_locator/polygon_fetcher.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative 'polygons/ceremonial_county_polygons'
+require_relative 'polygons/historic_county_polygons'
+require_relative 'polygons/current_county_and_unitary_authority_polygons'
+require_relative 'aliases/ceremonial_county_aliases'
+require_relative 'aliases/historic_county_aliases'
+require_relative 'aliases/current_county_and_unitary_authority_aliases'
+
+module UkCountyLocator
+  # The `UkCountyLocator::PolygonFetcher` retrieves geographic polygon data for UK counties.
+  # Supports `:current`, `:ceremonial`, and `:historic` county types.
+  # The class supports a large number of aliases for each county, stored in the aliases directory.
+  class PolygonFetcher
+    def initialize(type:)
+      @type = type
+      @counties = fetch_county_polygons.transform_keys(&:downcase)
+    end
+
+    def county_polygon(county)
+      county = county.downcase
+      return @counties[county] if @counties[county]
+      return @counties[county_by_alias(county)] if @counties[county_by_alias(county)]
+
+      nil
+    end
+
+    def county_list
+      fetch_county_polygons.keys.sort
+    end
+
+    private
+
+    def fetch_county_polygons
+      case @type
+      when :current
+        current_county_and_unitary_authority_polygons
+      when :ceremonial
+        ceremonial_county_polygons
+      when :historic
+        historic_county_polygons
+      end
+    end
+
+    def county_by_alias(county)
+      case @type
+      when :current
+        current_county_and_unitary_authority_aliases[county]&.downcase
+      when :ceremonial
+        ceremonial_county_aliases[county]&.downcase
+      when :historic
+        historic_county_aliases[county]&.downcase
+      end
+    end
+
+    def current_county_and_unitary_authority_polygons
+      Polygons::CurrentCountyAndUnitaryAuthorityPolygons::CURRENT_COUNTY_AND_UNITARY_AUTHORITY_POLYGONS
+    end
+
+    def ceremonial_county_polygons
+      Polygons::CeremonialCountyPolygons::CEREMONIAL_COUNTY_POLYGONS
+    end
+
+    def historic_county_polygons
+      Polygons::HistoricCountyPolygons::HISTORIC_COUNTY_POLYGONS
+    end
+
+    def current_county_and_unitary_authority_aliases
+      Aliases::CurrentCountyAndUnitaryAuthorityAliases::CURRENT_COUNTY_AND_UNITARY_AUTHORITY_ALIASES
+        .transform_keys(&:downcase)
+    end
+
+    def ceremonial_county_aliases
+      Aliases::CeremonialCountyAliases::CEREMONIAL_COUNTY_ALIASES.transform_keys(&:downcase)
+    end
+
+    def historic_county_aliases
+      Aliases::HistoricCountyAliases::HISTORIC_COUNTY_ALIASES.transform_keys(&:downcase)
+    end
+  end
+end