has_geo_lookup 0.1.0

data/lib/has_geo_lookup/models/geoboundary.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+# Administrative boundary geometries from GeoBoundaries.org
+#
+# This model stores precise administrative boundary polygons from GeoBoundaries.org,
+# providing accurate geometric shapes for countries, states, counties, and municipalities
+# worldwide. Each boundary includes PostGIS geometry data for spatial queries and
+# containment testing.
+#
+# GeoBoundaries provides multiple administrative levels:
+# - ADM0: Country boundaries
+# - ADM1: State/province boundaries (e.g., California, Ontario)
+# - ADM2: County/district boundaries (e.g., Los Angeles County)
+# - ADM3: Municipality boundaries (e.g., city limits)
+# - ADM4: Neighborhood/ward boundaries
+#
+# The boundary geometries are stored using PostGIS and can be used for precise
+# point-in-polygon queries to determine administrative containment.
+#
+# @attr [String] name Official boundary name
+# @attr [String] level Administrative level (ADM0, ADM1, ADM2, ADM3, ADM4)
+# @attr [String] shape_iso ISO3 country code for this boundary
+# @attr [String] shape_group Grouping identifier for related boundaries
+# @attr [RGeo::Geos::CAPIGeometryMethods] boundary PostGIS geometry (polygon/multipolygon)
+#
+# @example Find boundaries containing a point
+#   Geoboundary.where("ST_Contains(boundary, ST_GeomFromText('POINT(-74.0060 40.7128)', 4326))")
+#
+# @example Find state-level boundaries for the US
+#   Geoboundary.where(level: "ADM1").where("shape_iso LIKE '%USA%'")
+#
+# @see https://www.geoboundaries.org GeoBoundaries.org data source
+class Geoboundary < ActiveRecord::Base
+  # Associations
+  has_and_belongs_to_many :metros
+
+  # Validations
+  validates :name, presence: true
+  validates :level, presence: true, inclusion: { in: %w[ADM0 ADM1 ADM2 ADM3 ADM4] }
+  validates :boundary, presence: true
+
+  # Scopes for different administrative levels
+  scope :countries, -> { where(level: "ADM0") }
+  scope :states_provinces, -> { where(level: "ADM1") }
+  scope :counties_districts, -> { where(level: "ADM2") }
+  scope :municipalities, -> { where(level: "ADM3") }
+  scope :neighborhoods, -> { where(level: "ADM4") }
+
+  scope :by_country, ->(country_code) {
+    iso3 = country_code_to_iso3(country_code)
+    where("shape_iso LIKE ? OR shape_group LIKE ?", "%#{iso3}%", "%#{iso3}%") if iso3
+  }
+
+  scope :containing_point, ->(latitude, longitude) {
+    where("ST_Contains(boundary, ST_GeomFromText(?, 4326))", "POINT(#{longitude} #{latitude})")
+  }
+
+  # Check if this boundary contains the given coordinates
+  #
+  # Uses PostGIS ST_Contains function to perform precise geometric containment
+  # testing against the boundary polygon.
+  #
+  # @param latitude [Float] Latitude in decimal degrees
+  # @param longitude [Float] Longitude in decimal degrees
+  # @return [Boolean] true if the point is within this boundary
+  #
+  # @example
+  #   boundary.contains_point?(40.7128, -74.0060)
+  #   # => true (if NYC coordinates are within this boundary)
+  def contains_point?(latitude, longitude)
+    return false unless latitude && longitude && boundary
+    
+    point_wkt = "POINT(#{longitude} #{latitude})"
+    
+    self.class.connection.select_value(
+      "SELECT ST_Contains(ST_GeomFromText(?), ST_GeomFromText(?, 4326)) AS contains",
+      boundary.to_s, point_wkt
+    ) == 1
+  rescue => e
+    Rails.logger.warn "Error checking point containment: #{e.message}"
+    false
+  end
+
+  # Calculate the area of this boundary in square kilometers
+  #
+  # Uses PostGIS ST_Area function with spheroid calculations for accurate
+  # area computation on the Earth's surface.
+  #
+  # @return [Float] Area in square kilometers
+  #
+  # @example
+  #   boundary.area_km2
+  #   # => 10991.5 (area in square kilometers)
+  def area_km2
+    return nil unless boundary
+    
+    area_m2 = self.class.connection.select_value(
+      "SELECT ST_Area(ST_Transform(ST_GeomFromText(?), 3857))", 
+      boundary.to_s
+    )
+    
+    area_m2 ? (area_m2 / 1_000_000).round(2) : nil
+  rescue => e
+    Rails.logger.warn "Error calculating boundary area: #{e.message}"
+    nil
+  end
+
+  # Get the centroid (center point) of this boundary
+  #
+  # Uses PostGIS ST_Centroid function to find the geometric center
+  # of the boundary polygon.
+  #
+  # @return [Array<Float>, nil] [latitude, longitude] of centroid, or nil if error
+  #
+  # @example
+  #   boundary.centroid
+  #   # => [40.7589, -73.9851] (lat, lng of boundary center)
+  def centroid
+    return nil unless boundary
+    
+    result = self.class.connection.select_one(
+      "SELECT ST_Y(ST_Centroid(ST_GeomFromText(?))) AS lat, ST_X(ST_Centroid(ST_GeomFromText(?))) AS lng",
+      boundary.to_s, boundary.to_s
+    )
+    
+    result ? [result['lat'].to_f, result['lng'].to_f] : nil
+  rescue => e
+    Rails.logger.warn "Error calculating boundary centroid: #{e.message}"
+    nil
+  end
+
+  # Returns a human-readable description of this boundary
+  #
+  # Includes the boundary name, administrative level, and country context
+  # for clear identification.
+  #
+  # @return [String] Formatted description
+  #
+  # @example
+  #   boundary.display_name
+  #   # => "Los Angeles County (ADM2 - County/District, USA)"
+  def display_name
+    level_description = case level
+    when "ADM0" then "Country"
+    when "ADM1" then "State/Province"
+    when "ADM2" then "County/District"
+    when "ADM3" then "Municipality"
+    when "ADM4" then "Neighborhood/Ward"
+    else level
+    end
+    
+    country_info = extract_country_from_shape_iso
+    country_suffix = country_info ? ", #{country_info}" : ""
+    
+    "#{name} (#{level} - #{level_description}#{country_suffix})"
+  end
+
+  # Check if this is a country-level boundary
+  # @return [Boolean] true if level is "ADM0"
+  def country?
+    level == "ADM0"
+  end
+
+  # Check if this is a state/province-level boundary
+  # @return [Boolean] true if level is "ADM1"
+  def state_province?
+    level == "ADM1"
+  end
+
+  # Check if this is a county/district-level boundary
+  # @return [Boolean] true if level is "ADM2"
+  def county_district?
+    level == "ADM2"
+  end
+
+  # Check if this is a municipality-level boundary
+  # @return [Boolean] true if level is "ADM3"
+  def municipality?
+    level == "ADM3"
+  end
+
+  # Check if this is a neighborhood-level boundary
+  # @return [Boolean] true if level is "ADM4"
+  def neighborhood?
+    level == "ADM4"
+  end
+
+  private
+
+  # Convert 2-letter country code to 3-letter ISO3 code
+  def self.country_code_to_iso3(country_code)
+    return nil unless country_code&.length == 2
+    
+    begin
+      country = Iso3166.for_code(country_code.upcase)
+      country&.code3
+    rescue
+      nil
+    end
+  end
+
+  # Extract country information from shape_iso field
+  def extract_country_from_shape_iso
+    return nil unless shape_iso.present?
+    
+    # shape_iso often contains patterns like "USA-ADM1" or similar
+    # Extract the country code portion
+    country_match = shape_iso.match(/([A-Z]{3})/)
+    return nil unless country_match
+    
+    iso3_code = country_match[1]
+    
+    begin
+      country = Iso3166.for_alpha3(iso3_code)
+      country&.name
+    rescue
+      iso3_code
+    end
+  end
+end

data/lib/has_geo_lookup/models/geoname.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# Geoname model for geographic place names from Geonames.org
+#
+# This model represents geographic features from the Geonames.org dataset, which provides
+# comprehensive information about populated places, administrative divisions, and geographic
+# features worldwide. Each record includes coordinates, names, administrative codes, and
+# feature classifications.
+#
+# The Geonames dataset is organized using feature classes and codes that categorize
+# different types of geographic entities (populated places, administrative areas,
+# hydrographic features, etc.).
+#
+# @example Find populated places in the US
+#   Geoname.where(country_code: "US", feature_class: "P")
+#
+# @example Find administrative divisions
+#   Geoname.where(feature_class: "A", feature_code: "ADM2")
+#
+# @see https://www.geonames.org/ Official Geonames website
+# @see FeatureCode For feature classification definitions
+class Geoname < ActiveRecord::Base
+  include HasGeoLookup
+
+  # Associations
+  has_and_belongs_to_many :metros
+
+  # Validations
+  validates :name, presence: true
+  validates :latitude, :longitude, presence: true, numericality: true
+  validates :feature_class, presence: true, length: { is: 1 }
+  validates :feature_code, presence: true, length: { maximum: 10 }
+  validates :country_code, length: { is: 2 }, allow_blank: true
+  validates :population, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+  validates :elevation, numericality: true, allow_nil: true
+
+  # Scopes for common queries
+  scope :populated_places, -> { where(feature_class: "P") }
+  scope :administrative, -> { where(feature_class: "A") }
+  scope :hydrographic, -> { where(feature_class: "H") }
+  scope :terrain, -> { where(feature_class: "T") }
+  scope :roads_railways, -> { where(feature_class: "R") }
+  scope :spots_buildings, -> { where(feature_class: "S") }
+  scope :undersea, -> { where(feature_class: "U") }
+  scope :vegetation, -> { where(feature_class: "V") }
+
+  scope :by_country, ->(country_code) { where(country_code: country_code.upcase) }
+  scope :with_population, -> { where.not(population: [nil, 0]) }
+  scope :major_places, -> { with_population.where("population > ?", 100000) }
+
+  # Geographic bounds scopes
+  scope :within_bounds, ->(north, south, east, west) {
+    where(latitude: south..north, longitude: west..east)
+  }
+
+  scope :near_coordinates, ->(lat, lng, radius_deg = 1.0) {
+    where(
+      latitude: (lat - radius_deg)..(lat + radius_deg),
+      longitude: (lng - radius_deg)..(lng + radius_deg)
+    )
+  }
+
+  # Calculate distance to coordinates using Haversine formula
+  #
+  # This method calculates the great-circle distance between this geoname's coordinates
+  # and the provided coordinates using the Haversine formula. Useful for finding nearby
+  # places or sorting by distance.
+  #
+  # @param target_lat [Float] Target latitude in degrees
+  # @param target_lng [Float] Target longitude in degrees
+  # @return [Float] Distance in kilometers
+  #
+  # @example
+  #   geoname.distance_to(40.7128, -74.0060)
+  #   # => 245.67 (distance in kilometers)
+  def distance_to(target_lat, target_lng)
+    return nil unless latitude && longitude && target_lat && target_lng
+
+    # Haversine formula
+    radius_km = 6371.0
+    lat1_rad = latitude * Math::PI / 180
+    lat2_rad = target_lat * Math::PI / 180
+    delta_lat_rad = (target_lat - latitude) * Math::PI / 180
+    delta_lng_rad = (target_lng - longitude) * Math::PI / 180
+
+    a = Math.sin(delta_lat_rad / 2) * Math.sin(delta_lat_rad / 2) +
+        Math.cos(lat1_rad) * Math.cos(lat2_rad) *
+        Math.sin(delta_lng_rad / 2) * Math.sin(delta_lng_rad / 2)
+    
+    c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+    radius_km * c
+  end
+
+  # Returns a human-readable description of this place
+  #
+  # Combines the name with administrative context and country information to provide
+  # a comprehensive description suitable for display or logging.
+  #
+  # @return [String] Formatted description
+  #
+  # @example
+  #   geoname.display_name
+  #   # => "New York, New York, US (PPL - populated place)"
+  def display_name
+    parts = [name]
+    parts << admin1_name if admin1_name.present?
+    parts << admin2_name if admin2_name.present? && admin2_name != admin1_name
+    parts << country_code if country_code.present?
+    
+    description = parts.join(", ")
+    
+    if feature_code.present?
+      description += " (#{feature_code})"
+    end
+    
+    description
+  end
+
+  # Check if this is a populated place
+  # @return [Boolean] true if feature_class is "P"
+  def populated_place?
+    feature_class == "P"
+  end
+
+  # Check if this is an administrative division
+  # @return [Boolean] true if feature_class is "A"
+  def administrative_division?
+    feature_class == "A"
+  end
+
+  # Get the administrative level for administrative divisions
+  # @return [String, nil] Administrative level (ADM1, ADM2, etc.) or nil
+  def administrative_level
+    return nil unless administrative_division?
+    feature_code if feature_code&.start_with?("ADM")
+  end
+
+  # Ensure country codes are stored in uppercase
+  def country_code=(value)
+    super(value&.upcase)
+  end
+
+  # Ensure feature class is stored in uppercase
+  def feature_class=(value)
+    super(value&.upcase)
+  end
+
+  # Ensure feature code is stored in uppercase
+  def feature_code=(value)
+    super(value&.upcase)
+  end
+end

data/lib/has_geo_lookup/models/metro.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+# Metropolitan areas defined by collections of administrative boundaries
+#
+# This model represents metropolitan areas (metro areas, urban agglomerations) as
+# collections of administrative boundaries from GeoBoundaries.org. Rather than storing
+# separate geometry, metros are defined by their constituent geoboundaries, allowing
+# for flexible and maintainable metro definitions.
+#
+# Metro areas are useful for:
+# - Real estate market analysis by metropolitan region
+# - Economic data aggregation across municipal boundaries  
+# - Transportation and infrastructure planning
+# - Population and demographic analysis
+#
+# Each metro can span multiple administrative levels and boundaries, reflecting
+# the real-world nature of metropolitan areas that often cross county, city,
+# and sometimes state boundaries.
+#
+# @attr [String] name Metro area name (e.g., "San Francisco Bay Area", "Greater London")
+# @attr [String] details Additional descriptive information about the metro
+# @attr [String] country_code Primary country code for this metro area
+# @attr [Integer] population Estimated metro population (optional)
+#
+# @example Find metros containing a point
+#   Metro.joins(:geoboundaries)
+#        .where("ST_Contains(geoboundaries.boundary, ST_GeomFromText(?, 4326))", "POINT(-122.4194 37.7749)")
+#
+# @example Find metros in a specific country  
+#   Metro.where(country_code: "US")
+class Metro < ActiveRecord::Base
+  # Associations
+  has_and_belongs_to_many :geoboundaries
+
+  # Validations
+  validates :name, presence: true, uniqueness: true
+  validates :country_code, length: { is: 2 }, allow_blank: true
+  validates :population, numericality: { greater_than: 0 }, allow_nil: true
+
+  # Scopes
+  scope :by_country, ->(country_code) { where(country_code: country_code.upcase) }
+  scope :with_population, -> { where.not(population: nil) }
+  scope :major_metros, -> { with_population.where("population > ?", 1_000_000) }
+
+  scope :containing_point, ->(latitude, longitude) {
+    joins(:geoboundaries)
+    .where("ST_Contains(geoboundaries.boundary, ST_GeomFromText(?, 4326))", 
+           "POINT(#{longitude} #{latitude})")
+    .distinct
+  }
+
+  # Check if this metro contains the given coordinates
+  #
+  # Uses PostGIS spatial queries against all associated geoboundaries to determine
+  # if the point falls within any boundary that defines this metropolitan area.
+  #
+  # @param latitude [Float] Latitude in decimal degrees
+  # @param longitude [Float] Longitude in decimal degrees
+  # @return [Boolean] true if the point is within this metro area
+  #
+  # @example
+  #   metro.contains_point?(37.7749, -122.4194)
+  #   # => true (if coordinates are within San Francisco Bay Area)
+  def contains_point?(latitude, longitude)
+    return false unless latitude && longitude
+    return false unless geoboundaries.any?
+
+    # Check if point is contained within any of the metro's boundaries
+    geoboundaries.joins("INNER JOIN geoboundaries gb ON gb.id = geoboundaries.id")
+                 .where("ST_Contains(gb.boundary, ST_GeomFromText(?, 4326))", 
+                        "POINT(#{longitude} #{latitude})")
+                 .exists?
+  rescue => e
+    Rails.logger.warn "Error checking metro point containment: #{e.message}"
+    false
+  end
+
+  # Calculate the total area of this metro in square kilometers
+  #
+  # Sums the areas of all constituent geoboundaries, with handling for
+  # overlapping boundaries to avoid double-counting.
+  #
+  # @return [Float, nil] Total area in square kilometers, or nil if no boundaries
+  #
+  # @example
+  #   metro.total_area_km2
+  #   # => 18040.5 (total metro area in square kilometers)
+  def total_area_km2
+    return nil unless geoboundaries.any?
+
+    # Calculate total area using ST_Union to handle overlapping boundaries
+    result = self.class.connection.select_value(<<~SQL.squish)
+      SELECT ST_Area(ST_Transform(ST_Union(boundary), 3857)) / 1000000 AS total_area_km2
+      FROM geoboundaries 
+      WHERE id IN (#{geoboundary_ids.join(',')})
+    SQL
+
+    result&.round(2)
+  rescue => e
+    Rails.logger.warn "Error calculating metro area: #{e.message}"
+    nil
+  end
+
+  # Get the geographic center (centroid) of this metro
+  #
+  # Calculates the centroid of all constituent boundaries combined,
+  # providing a representative center point for the metropolitan area.
+  #
+  # @return [Array<Float>, nil] [latitude, longitude] of metro center, or nil if error
+  #
+  # @example
+  #   metro.centroid
+  #   # => [37.4419, -122.1430] (lat, lng of metro center)
+  def centroid
+    return nil unless geoboundaries.any?
+
+    result = self.class.connection.select_one(<<~SQL.squish)
+      SELECT 
+        ST_Y(ST_Centroid(ST_Union(boundary))) AS lat,
+        ST_X(ST_Centroid(ST_Union(boundary))) AS lng
+      FROM geoboundaries 
+      WHERE id IN (#{geoboundary_ids.join(',')})
+    SQL
+
+    result ? [result['lat'].to_f, result['lng'].to_f] : nil
+  rescue => e
+    Rails.logger.warn "Error calculating metro centroid: #{e.message}"
+    nil
+  end
+
+  # Get all boundary names that define this metro
+  #
+  # Returns a list of all constituent boundary names for understanding
+  # the geographic composition of this metropolitan area.
+  #
+  # @return [Array<String>] Array of boundary names
+  #
+  # @example
+  #   metro.boundary_names
+  #   # => ["San Francisco County", "Alameda County", "Santa Clara County", ...]
+  def boundary_names
+    geoboundaries.pluck(:name).compact.sort
+  end
+
+  # Get administrative levels represented in this metro
+  #
+  # Returns the different administrative levels (ADM1, ADM2, etc.) that
+  # make up this metropolitan area.
+  #
+  # @return [Array<String>] Array of administrative levels
+  #
+  # @example
+  #   metro.admin_levels
+  #   # => ["ADM1", "ADM2"] (includes state and county level boundaries)
+  def admin_levels
+    geoboundaries.distinct.pluck(:level).compact.sort
+  end
+
+  # Check if this metro spans multiple states/provinces
+  #
+  # Determines if the metro includes boundaries from multiple ADM1
+  # (state/province) level divisions.
+  #
+  # @return [Boolean] true if metro spans multiple states/provinces
+  #
+  # @example
+  #   metro.multi_state?
+  #   # => true (if metro crosses state boundaries)
+  def multi_state?
+    state_boundaries = geoboundaries.where(level: "ADM1")
+    state_boundaries.count > 1
+  end
+
+  # Get population density (people per km²)
+  #
+  # Calculates population density based on total population and area,
+  # if both values are available.
+  #
+  # @return [Float, nil] Population density in people per km², or nil if data unavailable
+  #
+  # @example
+  #   metro.population_density
+  #   # => 1547.3 (people per square kilometer)
+  def population_density
+    return nil unless population && total_area_km2
+    return nil if total_area_km2.zero?
+    
+    (population.to_f / total_area_km2).round(1)
+  end
+
+  # Returns a human-readable description of this metro
+  #
+  # Combines name, details, country, and constituent boundary information
+  # for comprehensive metro identification.
+  #
+  # @return [String] Formatted description
+  #
+  # @example
+  #   metro.display_name
+  #   # => "San Francisco Bay Area (US) - 9 counties, 2 admin levels"
+  def display_name
+    parts = [name]
+    parts << "(#{country_code})" if country_code.present?
+    
+    if geoboundaries.any?
+      boundary_count = geoboundaries.count
+      level_count = admin_levels.count
+      parts << "#{boundary_count} boundaries, #{level_count} admin level#{'s' if level_count != 1}"
+    end
+    
+    description = parts.join(" - ")
+    description += "\n#{details}" if details.present?
+    description
+  end
+
+  # Ensure country code is stored in uppercase
+  def country_code=(value)
+    super(value&.upcase)
+  end
+
+  # Get a summary of this metro's geographic composition
+  #
+  # Returns detailed information about the boundaries and administrative
+  # levels that make up this metropolitan area.
+  #
+  # @return [Hash] Summary with boundary counts by level and names
+  #
+  # @example
+  #   metro.geographic_summary
+  #   # => {
+  #   #   total_boundaries: 9,
+  #   #   by_level: {"ADM1" => 1, "ADM2" => 8},
+  #   #   boundary_names: ["San Francisco County", "Alameda County", ...],
+  #   #   spans_multiple_states: false
+  #   # }
+  def geographic_summary
+    {
+      total_boundaries: geoboundaries.count,
+      by_level: geoboundaries.group(:level).count,
+      boundary_names: boundary_names,
+      spans_multiple_states: multi_state?,
+      admin_levels: admin_levels,
+      total_area_km2: total_area_km2,
+      population_density: population_density
+    }
+  end
+end

data/lib/has_geo_lookup/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module HasGeoLookup
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path('../tasks/has_geo_lookup.rake', __dir__)
+    end
+  end
+end

data/lib/has_geo_lookup/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HasGeoLookup
+  VERSION = "0.1.0"
+end

data/lib/has_geo_lookup.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/concern"
+require "active_record"
+
+require_relative "has_geo_lookup/version"
+require_relative "has_geo_lookup/concern"
+
+# Require models
+require_relative "has_geo_lookup/models/geoname"
+require_relative "has_geo_lookup/models/geoboundary"
+require_relative "has_geo_lookup/models/feature_code"
+require_relative "has_geo_lookup/models/metro"
+
+# Require utilities
+require_relative "has_geo_lookup/index_checker"
+
+# Require generators and railtie if Rails is available
+if defined?(Rails)
+  require_relative "generators/has_geo_lookup/install_generator"
+  require_relative "has_geo_lookup/railtie"
+end
+
+
+module HasGeoLookup
+  class Error < StandardError; end
+end