has_geo_lookup 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d873a9710e8df280355b3d488e2329a5d1cf6e9ab1c6f768a4e1b814e567b4c0
-  data.tar.gz: 3269979fbb084f3dca2edaa0ea6f045c924e9d79ce7236869e4049c9a550dbe6
+  metadata.gz: c346daadf2a1be6115c2c5a5568f3298a90fa7320b8418ffbb1404c48f1e3be4
+  data.tar.gz: 39fbae916da78a3aa2646e5ef0770f67fb65d15d37b276e9963f045354974882
 SHA512:
-  metadata.gz: f2a2ae74c77015a2196d91a1c8e0c0dd82253ef316620b803484e7956f040c806c5898a6452f396ca41663cd4e91d9aca26e18775e09067ad5d0f5fce3684643
-  data.tar.gz: a5e3462c0ebc72b7ba367ec271d12b732f5be9d19ca30a1a8f62c0e9246ea2d9d1f1a2e5f47202b1fcab6b572a33c46fb296bf0b176ff604a35d9b0c89bf9ff8
+  metadata.gz: b116a1d609b20c28140e37cf62389b520d4caef383a6abf34e9eacd7b60415929ac3ea9ad464f0ea15abf9fb563d59375dbc47eabdb860b4a19e08944777b2a0
+  data.tar.gz: df4d371bd9667eb8605a32dafbd23271e00b86bfb16a4e38f2d328a294c8e97789c2cec9a87802d4badf2ebfa85b952003d020df9923b8ee5f4175570108403d

data/README.md

@@ -269,25 +269,25 @@ This gem integrates data from:
 
 ## Performance Considerations
 
-### Database Setup and Optimization
+### Index Analysis and Optimization
 
-The gem includes built-in tools to analyze and set up the complete database requirements for HasGeoLookup functionality:
+The gem includes built-in tools to analyze and optimize database indexes for HasGeoLookup functionality:
 
 ```bash
-# Check HasGeoLookup setup for all models (columns and indexes)
-rake has_geo_lookup:check_setup
+# Check index coverage for all models using HasGeoLookup
+rake has_geo_lookup:check_indexes
 
-# Preview what setup changes would be made (dry run)
-rake has_geo_lookup:preview_setup
+# Preview what indexes would be created (dry run)
+rake has_geo_lookup:preview_indexes
 
-# Generate Rails migration for complete HasGeoLookup setup
-rake has_geo_lookup:create_setup
+# Generate Rails migration for missing columns and indexes  
+rake has_geo_lookup:create_indexes
 
 # Analyze a specific model in detail
 rake has_geo_lookup:analyze_model[Listing]
 ```
 
-**Programmatic Setup Management:**
+**Programmatic Index Management:**
 
 ```ruby
 # Get performance analysis for all models
@@ -307,9 +307,9 @@ migration_path = HasGeoLookup::IndexChecker.generate_index_migration(Listing)
 puts HasGeoLookup::IndexChecker.performance_report
 ```
 
-**Complete Database Setup:**
+**Setup and Index Creation:**
 
-The `create_setup` task generates proper Rails migration files that can be committed to version control and run as part of your deployment process. The migration includes:
+The `create_indexes` task generates proper Rails migration files that can be committed to version control and run as part of your deployment process. The migration includes:
 
 - **Required columns**: Adds `latitude` and `longitude` decimal columns if missing
 - **Recommended indexes**: Creates optimized database indexes for geographic queries

data/lib/has_geo_lookup/boundary_importer.rb

@@ -0,0 +1,414 @@
+# frozen_string_literal: true
+
+require "open-uri"
+require "json"
+require "rgeo"
+require "fileutils"
+require "digest/sha1"
+require "iso_3166"
+
+module HasGeoLookup
+  class BoundaryImporter
+    class << self
+      # Import all available ADM levels (1-4) for a country
+      #
+      # @param iso2_code [String] 2-letter ISO country code (e.g., "US", "FR")
+      # @param options [Hash] Import options
+      # @option options [String] :cache_dir Directory for caching downloaded files
+      # @option options [Boolean] :verbose Enable detailed progress output (default: true)
+      #
+      # @return [Hash] Import results with :success, :total_processed, :errors keys
+      def import_country(iso2_code, options = {})
+        iso2 = iso2_code&.upcase
+        raise ArgumentError, "Please provide a 2-letter country code" unless iso2
+        
+        cache_dir = options[:cache_dir] || default_cache_dir
+        verbose = options.fetch(:verbose, true)
+        
+        # Convert ISO2 to ISO3 using iso_3166 gem with fallbacks
+        iso3, country_name = resolve_country_codes(iso2, verbose)
+        
+        errors = []
+        total_processed = 0
+        factory = create_geometry_factory
+        
+        (1..5).each do |level|
+          adm = "ADM#{level}"
+          puts "📍 Importing #{adm} boundaries..." if verbose
+          
+          result = import_adm_level(iso3, adm, factory, cache_dir, errors, verbose)
+          
+          unless result[:success]
+            puts "⏭️  Skipping remaining ADM levels (#{adm} and higher not available)" if verbose
+            break
+          end
+          
+          total_processed += result[:count]
+        end
+        
+        {
+          success: true,
+          total_processed: total_processed,
+          errors: errors,
+          country: { iso2: iso2, iso3: iso3, name: country_name }
+        }
+      end
+      
+      # Import boundaries for a specific ADM level
+      #
+      # @param iso2_code [String] 2-letter ISO country code
+      # @param adm_level [String] Administrative level ("ADM1", "ADM2", "ADM3", "ADM4", "ADM5")
+      # @param options [Hash] Import options (same as import_country)
+      #
+      # @return [Hash] Import results
+      def import_level(iso2_code, adm_level, options = {})
+        iso2 = iso2_code&.upcase
+        raise ArgumentError, "Please provide a 2-letter country code" unless iso2
+        raise ArgumentError, "Please provide ADM level (ADM1-ADM5)" unless adm_level&.match?(/\AADM[1-5]\z/)
+        
+        cache_dir = options[:cache_dir] || default_cache_dir
+        verbose = options.fetch(:verbose, true)
+        
+        iso3, country_name = resolve_country_codes(iso2, verbose)
+        
+        errors = []
+        factory = create_geometry_factory
+        
+        result = import_adm_level(iso3, adm_level, factory, cache_dir, errors, verbose)
+        
+        {
+          success: result[:success],
+          total_processed: result[:count],
+          errors: errors,
+          country: { iso2: iso2, iso3: iso3, name: country_name }
+        }
+      end
+      
+      private
+      
+      def default_cache_dir
+        if defined?(Rails)
+          Rails.root.join("db", "boundaries")
+        else
+          File.join(Dir.tmpdir, "has_geo_lookup_boundaries")
+        end
+      end
+      
+      def create_geometry_factory
+        RGeo::Cartesian.factory(
+          srid: 4326,
+          uses_lenient_assertions: true,
+          has_z_coordinate: false,
+          wkt_parser: { support_ewkt: true }
+        )
+      end
+      
+      def resolve_country_codes(iso2, verbose = true)
+        country = Iso3166.for_code(iso2)
+        
+        if country
+          iso3 = country.code3
+          country_name = country.name.downcase.split(' ').map(&:capitalize).join(' ')
+          puts "🌍 Converting #{iso2} → #{iso3} (#{country_name})" if verbose
+          [iso3, country_name]
+        else
+          # Fallback for codes not recognized by iso_3166 gem
+          puts "⚠️  Country code '#{iso2}' not found in iso_3166 gem, trying direct lookup..." if verbose
+          
+          # Common manual mappings for missing territories
+          manual_mappings = {
+            'BL' => { iso3: 'BLM', name: 'Saint Barthélemy' },
+            'MF' => { iso3: 'MAF', name: 'Saint Martin' },
+            'SX' => { iso3: 'SXM', name: 'Sint Maarten' }
+          }
+          
+          if manual_mappings[iso2]
+            mapping = manual_mappings[iso2]
+            puts "🌍 Using manual mapping: #{iso2} → #{mapping[:iso3]} (#{mapping[:name]})" if verbose
+            [mapping[:iso3], mapping[:name]]
+          else
+            # Last resort: use ISO2 as ISO3 and try the API call
+            puts "🌍 Using direct code: #{iso2} → #{iso2} (attempting API lookup)" if verbose
+            [iso2, iso2]
+          end
+        end
+      end
+      
+      def import_adm_level(iso3, adm_level, factory, cache_dir, errors = [], verbose = true)
+        api_url = "https://www.geoboundaries.org/api/current/gbOpen/#{iso3}/#{adm_level}/"
+        puts "🌍 Fetching metadata from #{api_url}..." if verbose
+
+        # Get metadata (not cached since it's small and may change)
+        begin
+          metadata_response = URI.open(api_url).read
+          metadata = JSON.parse(metadata_response)
+        rescue OpenURI::HTTPError => e
+          if e.message.include?("404")
+            puts "⚠️  #{adm_level} boundaries not available for #{iso3} (404 Not Found)" if verbose
+            return { success: false, count: 0 }
+          else
+            puts "❌ HTTP error fetching metadata: #{e.message}" if verbose
+            return { success: false, count: 0 }
+          end
+        rescue JSON::ParserError => e
+          puts "❌ Invalid JSON in API response: #{e.message}" if verbose
+          return { success: false, count: 0 }
+        rescue => e
+          puts "❌ Unexpected error fetching metadata: #{e.class}: #{e.message}" if verbose
+          return { success: false, count: 0 }
+        end
+
+        # Use simplified geometry if available, fall back to full resolution
+        geojson_url = metadata["simplifiedGeometryGeoJSON"] || metadata["gjDownloadURL"]
+        unless geojson_url
+          puts "⚠️  No download URL found in API response for #{adm_level}" if verbose
+          return { success: false, count: 0 }
+        end
+        
+        simplified = metadata["simplifiedGeometryGeoJSON"] ? "(simplified)" : "(full resolution)"
+        puts "📐 Using #{simplified} geometry" if verbose
+
+        # Check if GeoJSON is already cached
+        cached_file = local_geojson_path(iso3, adm_level, geojson_url, cache_dir)
+        if File.exist?(cached_file)
+          puts "📂 Using cached GeoJSON: #{cached_file}" if verbose
+          begin
+            data = JSON.parse(File.read(cached_file, encoding: "UTF-8"))
+          rescue JSON::ParserError => e
+            puts "❌ Invalid JSON in cached file, re-downloading: #{e.message}" if verbose
+            File.delete(cached_file)
+            data = download_and_cache_geojson(geojson_url, cached_file, verbose)
+            return { success: false, count: 0 } unless data
+          rescue Encoding::UndefinedConversionError => e
+            puts "❌ Encoding error in cached file, re-downloading: #{e.message}" if verbose
+            File.delete(cached_file)
+            data = download_and_cache_geojson(geojson_url, cached_file, verbose)
+            return { success: false, count: 0 } unless data
+          end
+        else
+          data = download_and_cache_geojson(geojson_url, cached_file, verbose)
+          return { success: false, count: 0 } unless data
+        end
+
+        unless data["features"] && data["features"].any?
+          puts "⚠️  No boundary features found in GeoJSON for #{adm_level}" if verbose
+          return { success: false, count: 0 }
+        end
+
+        count = process_features(data["features"], adm_level, geojson_url, factory, errors, verbose)
+        
+        puts "✅ Processed #{count} boundaries for #{adm_level}." if verbose
+        { success: true, count: count }
+      end
+      
+      def process_features(features, adm_level, geojson_url, factory, errors, verbose)
+        count = 0
+        
+        features.each do |feature|
+          props = feature["properties"]
+          coords = feature["geometry"]["coordinates"]
+          next unless coords && props
+
+          name = props["shapeName"]
+          shape_id = props["shapeID"]
+          shape_iso = props["shapeISO"]
+          shape_group = props["shapeGroup"]
+
+          puts "🔍 Importing #{name.inspect}..." if verbose
+
+          # Process geometry
+          multi = create_multipolygon_from_feature(feature, factory, name, errors, verbose)
+          next unless multi
+          
+          wkt = multi.as_text
+
+          # Insert into database using the gem's Geoboundary model
+          Geoboundary.connection.execute(<<~SQL)
+            INSERT INTO geoboundaries (name, level, shape_id, shape_iso, shape_group, source_url, boundary, created_at, updated_at)
+            VALUES (
+              #{ActiveRecord::Base.connection.quote(name)},
+              #{ActiveRecord::Base.connection.quote(adm_level)},
+              #{ActiveRecord::Base.connection.quote(shape_id)},
+              #{ActiveRecord::Base.connection.quote(shape_iso)},
+              #{ActiveRecord::Base.connection.quote(shape_group)},
+              #{ActiveRecord::Base.connection.quote(geojson_url)},
+              ST_GeomFromText('#{wkt}', 4326),
+              NOW(), NOW()
+            )
+            ON DUPLICATE KEY UPDATE
+              name = VALUES(name),
+              level = VALUES(level),
+              shape_iso = VALUES(shape_iso),
+              shape_group = VALUES(shape_group),
+              source_url = VALUES(source_url),
+              boundary = VALUES(boundary),
+              updated_at = NOW()
+          SQL
+
+          count += 1
+        rescue => e
+          # Enhanced error info with debug context
+          error_info = {
+            name: name || "Unknown",
+            adm_level: adm_level,
+            message: "#{e.class}: #{e.message}",
+            details: build_error_details(e, wkt, feature&.dig("geometry", "type"), coords&.class, coords&.size),
+            backtrace: e.is_a?(NoMethodError) ? e.backtrace.first(3) : nil
+          }
+          errors << error_info
+          puts "❌ Failed to process #{name.inspect}: #{e.class} (error details saved for summary)" if verbose
+        end
+        
+        count
+      end
+      
+      def create_multipolygon_from_feature(feature, factory, name, errors, verbose)
+        coords = feature["geometry"]["coordinates"]
+        geom_type = feature["geometry"]["type"]
+        
+        # Collect debug geometry structure silently
+        coords_structure = "#{coords.class} -> #{coords.first&.class} -> #{coords.first&.first&.class}"
+        
+        polygon_groups = geom_type == "MultiPolygon" ? coords : [coords]
+        debug_info = []
+        
+        reversed_polygons = polygon_groups.map.with_index do |poly_coords, poly_index|
+          # Collect debug info silently for problematic geometries
+          unless poly_coords.is_a?(Array) && poly_coords.any?
+            debug_info << "poly_coords[#{poly_index}] is #{poly_coords.class}: #{poly_coords.inspect[0..200]}..."
+            next nil
+          end
+          
+          raw_ring = poly_coords.first
+          unless raw_ring.is_a?(Array) && raw_ring.any?
+            debug_info << "raw_ring is #{raw_ring.class}: #{raw_ring.inspect[0..200]}..."
+            debug_info << "poly_coords structure: #{poly_coords.map(&:class)}"
+            next nil
+          end
+
+          outer =
+            if raw_ring.size == 2 && raw_ring.all? { |pt| pt.is_a?(Array) && pt.size == 2 }
+              puts "⚠️  Constructing rectangular fallback for #{name.inspect} (2 points)" if verbose
+              (lon1, lat1), (lon2, lat2) = raw_ring
+
+              rectangle = [
+                [lat1, lon1],
+                [lat2, lon1],
+                [lat2, lon2],
+                [lat1, lon2],
+                [lat1, lon1]
+              ].map { |lat, lon| factory.point(lat, lon) }
+
+              factory.linear_ring(rectangle)
+            else
+              ring_points = raw_ring.map { |lon, lat| factory.point(lat, lon) }
+              factory.linear_ring(ring_points)
+            end
+
+          # Process holes with better validation
+          holes = []
+          if poly_coords.size > 1
+            debug_info << "Processing #{poly_coords.size - 1} holes"
+            holes = poly_coords[1..].filter_map.with_index do |ring, hole_index|
+              unless ring.is_a?(Array) && ring.any?
+                debug_info << "hole[#{hole_index}] is #{ring.class}: #{ring.inspect[0..100]}..."
+                next nil
+              end
+              
+              begin
+                debug_info << "hole[#{hole_index}] has #{ring.size} points, first point: #{ring.first.inspect}"
+                hole_points = ring.map { |lon, lat| factory.point(lat, lon) }
+                factory.linear_ring(hole_points)
+              rescue => e
+                debug_info << "hole[#{hole_index}] failed: #{e.class}: #{e.message}"
+                debug_info << "hole[#{hole_index}] structure: #{ring.map(&:class).uniq}"
+                debug_info << "hole[#{hole_index}] sample: #{ring.first(3).inspect}"
+                nil
+              end
+            end
+            debug_info << "Successfully processed #{holes.size} holes"
+          end
+
+          begin
+            # RGeo factory.polygon expects: outer_ring, hole1, hole2, hole3...
+            debug_info << "Creating polygon with outer: #{outer.class}, holes: #{holes.size} (#{holes.map(&:class)})"
+            factory.polygon(outer, *holes)
+          rescue => e
+            debug_info << "polygon creation failed: #{e.class}: #{e.message}"
+            debug_info << "outer ring valid: #{outer.respond_to?(:exterior_ring)}"
+            debug_info << "holes valid: #{holes.all? { |h| h.respond_to?(:exterior_ring) }}"
+            # Try without holes as fallback
+            begin
+              debug_info << "Retrying without holes..."
+              factory.polygon(outer)
+            rescue => e2
+              debug_info << "outer ring also failed: #{e2.class}: #{e2.message}"
+              nil
+            end
+          end
+        end.compact
+
+        # Skip if no valid polygons were created
+        if reversed_polygons.empty?
+          debug_info << "No valid polygons found, skipping"
+          return nil
+        end
+
+        factory.multi_polygon(reversed_polygons)
+      end
+      
+      def local_geojson_path(iso3, adm_level, geojson_url, cache_dir)
+        # Create a safe filename from the URL and parameters
+        url_hash = Digest::SHA1.hexdigest(geojson_url)[0..8]
+        filename = "#{iso3}-#{adm_level}-#{url_hash}.geojson"
+        File.join(cache_dir, filename)
+      end
+      
+      def build_error_details(error, wkt, geom_type, coords_class, coords_size)
+        details = []
+        details << "WKT length: #{wkt&.length || 'n/a'}"
+        details << "Geometry type: #{geom_type || 'n/a'}"
+        details << "Coordinates: #{coords_class}"
+        details << "Coordinates size: #{coords_size || 'n/a'}"
+        
+        if error.is_a?(NoMethodError)
+          details << "Method called on: #{error.receiver&.class || 'unknown'}"
+        end
+        
+        details.join(", ")
+      end
+      
+      def download_and_cache_geojson(geojson_url, cached_file, verbose = true)
+        puts "⬇️  Downloading GeoJSON from #{geojson_url}..." if verbose
+        
+        begin
+          geojson_response = URI.open(geojson_url, "rb") do |file|
+            file.read.force_encoding("UTF-8")
+          end
+          data = JSON.parse(geojson_response)
+          
+          # Ensure directory exists
+          FileUtils.mkdir_p(File.dirname(cached_file))
+          
+          # Cache the file
+          File.write(cached_file, geojson_response, encoding: "UTF-8")
+          puts "💾 Cached GeoJSON to #{cached_file}" if verbose
+          
+          return data
+        rescue OpenURI::HTTPError => e
+          puts "❌ HTTP error downloading GeoJSON: #{e.message}" if verbose
+          return nil
+        rescue JSON::ParserError => e
+          puts "❌ Invalid JSON in GeoJSON file: #{e.message}" if verbose
+          return nil
+        rescue Encoding::UndefinedConversionError => e
+          puts "❌ Encoding error in GeoJSON file: #{e.message}" if verbose
+          return nil
+        rescue => e
+          puts "❌ Unexpected error downloading GeoJSON: #{e.class}: #{e.message}" if verbose
+          return nil
+        end
+      end
+    end
+  end
+end

data/lib/has_geo_lookup/concern.rb

@@ -154,7 +154,7 @@ module HasGeoLookup
   end
 
   # Looks up the closest township-level area using feature_code = ADM3.
-  # Falls back to ADM4 if no ADM3 match is found.
+  # Falls back to ADM4, then ADM5 if no ADM3 match is found.
   #
   # Options:
   #   :radius_km — limit search radius (default: 25)
@@ -162,7 +162,7 @@ module HasGeoLookup
   #
   # Returns a Result struct with distance and matched geoname.
   def closest_township(radius_km: 25, country_code: nil)
-    %w[ADM3 ADM4].each do |code|
+    %w[ADM3 ADM4 ADM5].each do |code|
       result = nearest_geonames(
         feature_class: "A",
         feature_code: code,
@@ -254,10 +254,10 @@ module HasGeoLookup
   end
 
   # GeoBoundary equivalent of closest_township  
-  # Returns ADM3 or ADM4 boundary that contains this point, with fallback
+  # Returns ADM3, ADM4 or ADM5 boundary that contains this point, with fallback
   def township_boundary
-    # Try ADM3 first, then ADM4
-    %w[ADM3 ADM4].each do |level|
+    # Try ADM3 first, then ADM4, then ADM5
+    %w[ADM5 ADM4 ADM3].each do |level|
       boundary = containing_boundary(level)
       return GeoboundaryResult.new(boundary, 0.0, level, boundary.name) if boundary
     end
@@ -286,7 +286,7 @@ module HasGeoLookup
     return geoname_result unless geoname_result
     
     # Add boundary context to help validate the subdivision
-    boundaries = containing_boundaries(levels: %w[ADM2 ADM3 ADM4])
+    boundaries = containing_boundaries(levels: %w[ADM2 ADM3 ADM4 ADM5])
     geoname_result.record.define_singleton_method(:containing_boundaries) { boundaries }
     
     geoname_result
@@ -770,8 +770,9 @@ module HasGeoLookup
     # Check if boundary data exists for a country
     # 
     # @param iso2 [String] 2-letter country code
+    # @param level [String, nil] Optional specific ADM level to check (e.g., "ADM2")
     # @return [Boolean] true if boundary data exists
-    def has_boundary_data?(iso2)
+    def has_boundary_data?(iso2, level = nil)
       # Special cases for territories that don't have separate boundary data
       territories_without_boundaries = %w[PR VI GU AS MP TC] # US territories + others
       return true if territories_without_boundaries.include?(iso2)
@@ -782,9 +783,54 @@ module HasGeoLookup
       
       iso3 = country.code3
       
-      # Check if we have any boundaries for this country's ISO3 code
-      # Boundaries are stored with country info in shape_group or can be inferred from shape_iso
-      Geoboundary.where("shape_iso LIKE ? OR shape_group LIKE ?", "%#{iso3}%", "%#{iso3}%").exists?
+      # Build query for boundaries with optional level filter
+      query = Geoboundary.where("shape_iso LIKE ? OR shape_group LIKE ?", "%#{iso3}%", "%#{iso3}%")
+      query = query.where(level: level) if level
+      
+      query.exists?
+    end
+    
+    # Get detailed boundary coverage by ADM level for a country
+    #
+    # @param iso2 [String] 2-letter country code
+    # @return [Hash] Hash with ADM levels as keys and counts as values
+    # @example
+    #   boundary_coverage_by_level('US')
+    #   # => { 'ADM1' => 51, 'ADM2' => 3142, 'ADM3' => 0, 'ADM4' => 0, 'ADM5' => 0 }
+    def boundary_coverage_by_level(iso2)
+      # Special cases for territories
+      territories_without_boundaries = %w[PR VI GU AS MP TC]
+      if territories_without_boundaries.include?(iso2)
+        return %w[ADM1 ADM2 ADM3 ADM4 ADM5].index_with { |_| 1 } # Assume coverage
+      end
+      
+      # Convert ISO2 to ISO3
+      country = Iso3166.for_code(iso2)
+      return {} unless country
+      
+      iso3 = country.code3
+      
+      # Count boundaries by level for this country
+      boundaries_by_level = Geoboundary.where("shape_iso LIKE ? OR shape_group LIKE ?", "%#{iso3}%", "%#{iso3}%")
+                                      .group(:level)
+                                      .count
+      
+      # Ensure all ADM levels are represented (with 0 counts for missing)
+      %w[ADM1 ADM2 ADM3 ADM4 ADM5].index_with do |level|
+        boundaries_by_level[level] || 0
+      end
+    end
+    
+    # Get list of missing ADM levels for a country
+    #
+    # @param iso2 [String] 2-letter country code
+    # @return [Array<String>] Array of missing ADM level strings
+    # @example
+    #   missing_adm_levels('US')
+    #   # => ['ADM3', 'ADM4', 'ADM5']
+    def missing_adm_levels(iso2)
+      coverage = boundary_coverage_by_level(iso2)
+      coverage.select { |_level, count| count == 0 }.keys
     end
     
     # Check if geonames data exists for a country
@@ -803,15 +849,28 @@ module HasGeoLookup
     # Get comprehensive coverage status for a country
     #
     # @param iso2 [String] 2-letter country code
-    # @return [Hash] Coverage status with :boundaries, :geonames, :complete keys
+    # @return [Hash] Coverage status with detailed boundary information
+    # @example
+    #   coverage_status('US')
+    #   # => {
+    #   #   boundaries: true,
+    #   #   geonames: true,
+    #   #   complete: false,
+    #   #   boundary_coverage: { 'ADM1' => 51, 'ADM2' => 3142, 'ADM3' => 0, 'ADM4' => 0, 'ADM5' => 0 },
+    #   #   missing_adm_levels: ['ADM3', 'ADM4', 'ADM5']
+    #   # }
     def coverage_status(iso2)
       boundaries = has_boundary_data?(iso2)
       geonames = has_geonames_data?(iso2)
+      boundary_coverage = boundary_coverage_by_level(iso2)
+      missing_levels = missing_adm_levels(iso2)
       
       {
         boundaries: boundaries,
         geonames: geonames, 
-        complete: boundaries && geonames
+        complete: boundaries && geonames && missing_levels.empty?,
+        boundary_coverage: boundary_coverage,
+        missing_adm_levels: missing_levels
       }
     end
     

data/lib/has_geo_lookup/models/geoboundary.rb

@@ -13,12 +13,13 @@
 # - ADM2: County/district boundaries (e.g., Los Angeles County)
 # - ADM3: Municipality boundaries (e.g., city limits)
 # - ADM4: Neighborhood/ward boundaries
+# - ADM5: Sub-neighborhood boundaries (city blocks, micro-districts)
 #
 # 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] level Administrative level (ADM0, ADM1, ADM2, ADM3, ADM4, ADM5)
 # @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)
@@ -36,7 +37,7 @@ class Geoboundary < ActiveRecord::Base
 
   # Validations
   validates :name, presence: true
-  validates :level, presence: true, inclusion: { in: %w[ADM0 ADM1 ADM2 ADM3 ADM4] }
+  validates :level, presence: true, inclusion: { in: %w[ADM0 ADM1 ADM2 ADM3 ADM4 ADM5] }
   validates :boundary, presence: true
 
   # Scopes for different administrative levels
@@ -45,6 +46,7 @@ class Geoboundary < ActiveRecord::Base
   scope :counties_districts, -> { where(level: "ADM2") }
   scope :municipalities, -> { where(level: "ADM3") }
   scope :neighborhoods, -> { where(level: "ADM4") }
+  scope :sub_neighborhoods, -> { where(level: "ADM5") }
 
   scope :by_country, ->(country_code) {
     iso3 = country_code_to_iso3(country_code)
@@ -146,6 +148,7 @@ class Geoboundary < ActiveRecord::Base
     when "ADM2" then "County/District"
     when "ADM3" then "Municipality"
     when "ADM4" then "Neighborhood/Ward"
+    when "ADM5" then "Sub-Neighborhood/Block"
     else level
     end
     
@@ -185,6 +188,12 @@ class Geoboundary < ActiveRecord::Base
     level == "ADM4"
   end
 
+  # Check if this is a sub-neighborhood-level boundary
+  # @return [Boolean] true if level is "ADM5"
+  def sub_neighborhood?
+    level == "ADM5"
+  end
+
   private
 
   # Convert 2-letter country code to 3-letter ISO3 code

data/lib/has_geo_lookup/version.rb

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

data/lib/has_geo_lookup.rb

@@ -15,6 +15,7 @@ require_relative "has_geo_lookup/models/metro"
 
 # Require utilities
 require_relative "has_geo_lookup/index_checker"
+require_relative "has_geo_lookup/boundary_importer"
 
 # Require generators and railtie if Rails is available
 if defined?(Rails)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: has_geo_lookup
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Michael Edlund
@@ -145,6 +145,7 @@ files:
 - lib/generators/has_geo_lookup/templates/create_geonames_metros.rb.erb
 - lib/generators/has_geo_lookup/templates/create_metros.rb.erb
 - lib/has_geo_lookup.rb
+- lib/has_geo_lookup/boundary_importer.rb
 - lib/has_geo_lookup/concern.rb
 - lib/has_geo_lookup/index_checker.rb
 - lib/has_geo_lookup/models/feature_code.rb