has_geo_lookup 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 556e93ddd252169fbee37ee0bfcb91c43ec80815c66db3dcafa0ff3d47cfe56e
+  data.tar.gz: a49a34d5cf6f0ab901a18203a9da65be64f7f65faec1e54a4d4d9d7bdb102f40
+SHA512:
+  metadata.gz: 446d6d3e34e04ba14f418ef6d3ce62d7dc4a8045931ad6d3a9f2b12b8b315f996d2a6eeb279b43da40c4881fd5914ed194c7ff34e927f1b03425e790dc236ad0
+  data.tar.gz: 1bc6c467f8d9e3b592a8522dae18013d11e7d2ea6ea93001972fc528ebcddc3a423b62bff07d36b7ab122dfd0127bfe7b257f0c0f69a5eba4584355160a049a8

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-08-18
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Michael Edlund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,389 @@
+# HasGeoLookup
+
+Rails gem for geographic lookup functionality using GeoBoundaries.org and Geonames.org datasets. Provides coordinate validation with automatic radian/degree detection, spatial containment queries, distance-based lookups, and metropolitan area support.
+
+## Features
+
+- **Coordinate Validation** - Automatically detect and convert between radians and degrees using country boundary validation
+- **Spatial Queries** - PostGIS-optimized boundary containment with graceful fallback for other databases
+- **Distance-Based Lookup** - Find nearest geographic features within specified radius
+- **Administrative Boundaries** - Query points against ADM1-ADM4 level boundaries from GeoBoundaries.org
+- **Metro Area Support** - Define custom metropolitan areas as collections of administrative boundaries
+- **Multi-Source Comparison** - Compare geographic data across different sources with extensible hooks
+- **Data Coverage Analysis** - Utilities for analyzing geographic data completeness
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'has_geo_lookup'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Setup
+
+### 1. Generate Database Migrations
+
+```bash
+rails generate has_geo_lookup:install
+```
+
+This creates migrations for all required tables:
+- `geonames` - Geographic place data from Geonames.org
+- `geoboundaries` - Administrative boundaries from GeoBoundaries.org
+- `feature_codes` - Classification codes for geographic features
+- `metros` - Metropolitan area definitions
+- `metros_geoboundaries` - Join table for metro-boundary associations
+
+### 2. Run Migrations
+
+```bash
+rails db:migrate
+```
+
+### 3. Import Geographic Data
+
+Import geoboundaries and geonames for specific countries:
+
+```bash
+# Import both datasets for United States (recommended)
+rails geo:import[US]
+
+# Import for multiple countries
+rails geo:import[CA]  # Canada
+rails geo:import[GB]  # United Kingdom
+
+# Or import datasets separately
+rails geoboundaries:import[US]  # Administrative boundaries only
+rails geonames:import[US]       # Geographic place names only
+```
+
+### 4. Include in Your Models
+
+Add the concern to any model with `latitude` and `longitude` attributes:
+
+```ruby
+class Listing < ApplicationRecord
+  include HasGeoLookup
+  
+  # Your model must have these attributes:
+  # - latitude (decimal)
+  # - longitude (decimal)
+end
+```
+
+## Database Requirements
+
+### MySQL 8.0+ with Spatial Extensions (Recommended)
+
+The gem works well with MySQL 8.0+ spatial support:
+
+```ruby
+# Gemfile
+gem 'mysql2'
+```
+
+MySQL 8.0+ provides:
+- GEOMETRY column type for storing boundary polygons
+- ST_Contains, ST_GeomFromText, and other spatial functions
+- Coordinate validation using actual country boundaries
+- Spatial indexing for performance
+
+### PostgreSQL with PostGIS (Also Supported)
+
+For PostgreSQL databases with PostGIS:
+
+```ruby
+# Gemfile
+gem 'activerecord-postgis-adapter'
+```
+
+PostGIS provides enhanced spatial capabilities and may offer better performance for complex spatial operations.
+
+### Other Databases
+
+For SQLite and databases without spatial extensions:
+- Spatial queries will be limited but functional
+- Coordinate validation uses fallback detection methods
+- Basic geographic lookup functionality remains available
+
+## Usage
+
+### Basic Geographic Lookup
+
+```ruby
+listing = Listing.find(123)
+
+# Find nearest populated places within 50km
+places = listing.nearest_geonames(
+  feature_code: "PPL",    # Populated place
+  radius_km: 50,
+  limit: 10
+)
+
+# Find containing administrative boundaries
+boundaries = listing.containing_geoboundaries(level: "ADM2") # Counties
+
+# Get geographic summary
+summary = listing.compare_geo_sources
+puts summary
+```
+
+### Coordinate Validation
+
+The gem automatically handles coordinate format detection:
+
+```ruby
+# These coordinates could be in radians or degrees
+lat, lng = 0.768131687, 0.077125907  # Uzès, France in radians
+
+# Automatically detects format and converts to degrees
+validated_lat, validated_lng = listing.validate_and_convert_coordinates(lat, lng, "FR")
+# => [44.011, 4.419] (converted to degrees)
+
+# Already in degrees - no conversion needed
+validated_lat, validated_lng = listing.validate_and_convert_coordinates(44.011, 4.419, "FR")
+# => [44.011, 4.419] (unchanged)
+```
+
+### Metro Area Support
+
+Define custom metropolitan areas:
+
+```ruby
+# Create a metro area
+bay_area = Metro.create!(
+  name: "San Francisco Bay Area",
+  country_code: "US",
+  population: 7_750_000
+)
+
+# Associate with counties (geoboundaries)
+sf_county = Geoboundary.find_by(name: "San Francisco County")
+alameda_county = Geoboundary.find_by(name: "Alameda County")
+bay_area.geoboundaries << [sf_county, alameda_county]
+
+# Check if coordinates are in metro area
+bay_area.contains_point?(37.7749, -122.4194) # => true
+
+# Get metro area statistics
+bay_area.total_area_km2      # => 18040.5
+bay_area.population_density   # => 429.8
+bay_area.boundary_names      # => ["San Francisco County", "Alameda County", ...]
+```
+
+### Data Coverage Analysis
+
+```ruby
+# Analyze data completeness
+coverage = HasGeoLookup::DataCoverage.coverage_status("US")
+puts coverage[:geonames_count]      # Number of geonames records
+puts coverage[:boundaries_count]    # Number of boundary records
+puts coverage[:feature_coverage]    # Coverage by feature type
+
+# Check if specific data exists
+HasGeoLookup::DataCoverage.has_boundary_data?("US", "ADM2")  # => true
+HasGeoLookup::DataCoverage.has_geonames_data?("US")          # => true
+```
+
+### Advanced Usage
+
+#### Custom Source Comparison
+
+Extend geographic comparison for your specific data sources:
+
+```ruby
+class Listing < ApplicationRecord
+  include HasGeoLookup
+  
+  # Define additional data sources for comparison
+  def additional_source_columns
+    ['api_latitude', 'api_longitude', 'geocoded_lat', 'geocoded_lng']
+  end
+  
+  def additional_source_legend
+    {
+      'API' => 'Third-party API data',
+      'Geocoded' => 'Address-based geocoding'
+    }
+  end
+  
+  def get_source_value(column_name)
+    case column_name
+    when 'api_latitude', 'api_longitude'
+      # Custom logic to fetch from your API
+    when 'geocoded_lat', 'geocoded_lng'  
+      # Custom logic for geocoded coordinates
+    end
+  end
+end
+```
+
+#### Distance Calculations
+
+```ruby
+# Find records within radius using database query
+nearby_listings = Listing.joins(:nearest_geonames)
+                         .where("geonames.feature_code = 'PPL'")
+                         .where(geonames: { country_code: "US" })
+
+# Calculate distance between two points
+distance_km = listing.distance_to_point(40.7128, -74.0060)
+```
+
+## Configuration
+
+### Rails Generators
+
+Customize migration generation:
+
+```ruby
+# config/application.rb
+config.generators do |g|
+  g.has_geo_lookup_skip_migrations = false  # Set to true to skip auto-generation
+end
+```
+
+### PostGIS Configuration
+
+For PostGIS databases, ensure the extension is enabled:
+
+```ruby
+# In a migration or database setup
+enable_extension 'postgis'
+```
+
+## Data Sources
+
+This gem integrates data from:
+
+- **[GeoBoundaries.org](https://www.geoboundaries.org/)** - Administrative boundary polygons (ADM1-ADM4 levels)
+- **[Geonames.org](http://www.geonames.org/)** - Geographic place names and coordinates
+- **[ISO 3166](https://en.wikipedia.org/wiki/ISO_3166)** - Country code validation
+
+## Performance Considerations
+
+### Database Setup and Optimization
+
+The gem includes built-in tools to analyze and set up the complete database requirements for HasGeoLookup functionality:
+
+```bash
+# Check HasGeoLookup setup for all models (columns and indexes)
+rake has_geo_lookup:check_setup
+
+# Preview what setup changes would be made (dry run)
+rake has_geo_lookup:preview_setup
+
+# Generate Rails migration for complete HasGeoLookup setup
+rake has_geo_lookup:create_setup
+
+# Analyze a specific model in detail
+rake has_geo_lookup:analyze_model[Listing]
+```
+
+**Programmatic Setup Management:**
+
+```ruby
+# Get performance analysis for all models
+results = HasGeoLookup::IndexChecker.analyze_all_models
+
+# Check a specific model
+analysis = HasGeoLookup::IndexChecker.check_model(Listing)
+puts "Missing indexes: #{analysis[:missing_indexes]}"
+puts "Recommendations: #{analysis[:recommendations]}"
+
+# Generate migration file for missing columns and indexes
+migration_path = HasGeoLookup::IndexChecker.generate_index_migration
+# Or for a specific model:
+migration_path = HasGeoLookup::IndexChecker.generate_index_migration(Listing)
+
+# Generate a comprehensive performance report
+puts HasGeoLookup::IndexChecker.performance_report
+```
+
+**Complete Database Setup:**
+
+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:
+
+- **Required columns**: Adds `latitude` and `longitude` decimal columns if missing
+- **Recommended indexes**: Creates optimized database indexes for geographic queries
+- **Proper rollback**: Includes reversible `down` migration methods
+
+This ensures all environments get the same database structure and maintains proper migration history.
+
+### Database Optimization
+
+For large datasets:
+
+```ruby
+# Coordinate indexes (essential for spatial queries)
+add_index :your_table, [:latitude, :longitude]
+add_index :your_table, :latitude
+add_index :your_table, :longitude
+
+# Geographic attribute indexes (for filtering and joining)
+add_index :your_table, :country
+add_index :your_table, :state_or_province  
+add_index :your_table, :city
+add_index :your_table, :postal_code
+
+# For geoboundaries and geonames tables
+add_index :geonames, [:country_code, :feature_code]
+add_index :geoboundaries, [:level, :shape_iso]
+
+# For PostGIS, spatial indexes are created automatically
+```
+
+### Query Optimization
+
+```ruby
+# Use specific feature codes to limit results
+places = listing.nearest_geonames(
+  feature_code: ["PPL", "PPLA", "PPLA2"],  # Cities and towns only
+  limit: 5
+)
+
+# Specify administrative levels for boundaries
+boundaries = listing.containing_geoboundaries(level: ["ADM1", "ADM2"])
+```
+
+## Development
+
+### Running Tests
+
+```bash
+cd has_geo_lookup
+bundle install
+ruby -Ilib -Itest test/has_geo_lookup_test.rb
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Add tests for your changes
+4. Ensure tests pass
+5. Commit your changes (`git commit -am 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Create a Pull Request
+
+## License
+
+This gem is available as open source under the terms of the MIT License.
+
+## Changelog
+
+### Version 0.1.0
+- Initial release
+- Coordinate validation with radian/degree detection
+- PostGIS spatial queries with fallback support
+- GeoBoundaries and Geonames integration
+- Metro area support
+- Comprehensive test suite
+- Rails generators for easy setup

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/generators/has_geo_lookup/install_generator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module HasGeoLookup
+  module Generators
+    # Generates database migrations for HasGeoLookup gem
+    #
+    # Creates all necessary tables for geographic lookup functionality:
+    # - geonames: Geographic place data from Geonames.org
+    # - geoboundaries: Administrative boundaries from GeoBoundaries.org
+    # - feature_codes: Classification codes for geographic features
+    # - metros: Metropolitan area definitions
+    # - geoboundaries_metros: Join table for metro-boundary associations
+    # - geonames_metros: Join table for geoname-metro associations
+    #
+    # @example Generate migrations
+    #   rails generate has_geo_lookup:install
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Generate HasGeoLookup database migrations'
+
+      # Provide a migration timestamp
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def create_migrations
+        migration_template 'create_geonames.rb.erb', 'db/migrate/create_geonames.rb'
+        sleep 1 # Ensure different timestamps
+        migration_template 'create_geoboundaries.rb.erb', 'db/migrate/create_geoboundaries.rb'
+        sleep 1
+        migration_template 'create_feature_codes.rb.erb', 'db/migrate/create_feature_codes.rb'
+        sleep 1
+        migration_template 'create_metros.rb.erb', 'db/migrate/create_metros.rb'
+        sleep 1
+        migration_template 'create_geoboundaries_metros.rb.erb', 'db/migrate/create_geoboundaries_metros.rb'
+        sleep 1
+        migration_template 'create_geonames_metros.rb.erb', 'db/migrate/create_geonames_metros.rb'
+      end
+
+      def display_readme
+        readme "INSTALL.md"
+      end
+
+      private
+
+      def migration_version
+        if Rails.version.start_with?('8')
+          '[8.0]'
+        elsif Rails.version.start_with?('7')
+          '[7.0]'
+        elsif Rails.version.start_with?('6')
+          '[6.0]'
+        else
+          '[5.0]'
+        end
+      end
+    end
+  end
+end

data/lib/generators/has_geo_lookup/templates/INSTALL.md

@@ -0,0 +1,60 @@
+# HasGeoLookup Installation Complete
+
+The HasGeoLookup gem migrations have been generated successfully!
+
+## Next Steps
+
+1. **Run the migrations:**
+   ```bash
+   bin/rails db:migrate
+   ```
+
+2. **For PostGIS users (recommended):**
+   - Ensure PostGIS extension is available in your PostgreSQL database
+   - The migrations will automatically enable PostGIS and create spatial indexes
+   - This provides optimal performance for boundary queries and coordinate validation
+
+3. **For non-PostGIS databases:**
+   - The gem will work with MySQL, SQLite, or other databases
+   - Spatial queries will be limited, but basic geographic lookup functionality remains available
+   - Coordinate validation will use fallback methods instead of boundary containment
+
+4. **Import geographic data:**
+   ```bash
+   # Import geoboundaries and geonames for a specific country (recommended)
+   bin/rails geo:import[US]
+   
+   # Or import datasets separately
+   bin/rails geoboundaries:import[US]  # Administrative boundaries
+   bin/rails geonames:import[US]       # Geographic place names
+   ```
+
+5. **Include the concern in your models:**
+   ```ruby
+   class Listing < ApplicationRecord
+     include HasGeoLookup
+     
+     # Your model must have latitude and longitude attributes
+     # The gem will provide geographic lookup methods
+   end
+   ```
+
+## Available Tables
+
+The following tables have been created:
+
+- **`geonames`** - Geographic place data from Geonames.org
+- **`geoboundaries`** - Administrative boundary polygons from GeoBoundaries.org  
+- **`feature_codes`** - Classification codes for geographic features
+- **`metros`** - Custom metropolitan area definitions
+- **`metros_geoboundaries`** - Join table linking metros to their constituent boundaries
+
+## Key Features
+
+- **Coordinate validation** - Automatically detect and convert between radians/degrees
+- **Boundary containment** - Find which administrative boundaries contain a point
+- **Distance-based lookup** - Find nearest geographic features within a radius
+- **Metro area support** - Group boundaries into custom metropolitan regions
+- **Multi-source comparison** - Compare geographic data across different sources
+
+For detailed usage examples and API documentation, see the gem's README.