CmGeocoder

CmGeocoder is a Ruby gem that provides IP-based geocoding functionality for Rails applications. It allows you to determine the country of origin for IP addresses using comprehensive IPv4 and IPv6 network mappings.

Features

  • IP-based geocoding for both IPv4 and IPv6 addresses
  • Pre-built databases of IP networks and their corresponding country information
  • Easy integration with Rails applications
  • Comprehensive country information based on IP addresses
  • Regular updates to IP network mappings

Installation

Add this line to your application's Gemfile:

gem 'cm-geocoder'

And then execute:

bundle install

Usage

Models

CmGeocoder provides two main models:

  1. CmGeoIpNetwork
  • Represents IP network ranges and their associated locations
  • Used internally for IP-based geocoding
  1. CmGeoIpLocation
    • Stores geolocation information (country, continent, etc.)
    • Associated with IP networks through CmGeoIpNetwork

Methods

The gem provides several methods for IP-based geocoding:

# Get country ISO code for an IP address
CmGeoIpNetwork.geo_country_iso_code('192.0.2.1')
# Returns: 'US' (or nil if not found)

# Get country name for an IP address
CmGeoIpNetwork.geo_country_name('192.0.2.1')
# Returns: 'United States' (or nil if not found)

# Get full country information for an IP address
CmGeoIpNetwork.geo_country('192.0.2.1')
# Returns: CmGeoIpLocation object with attributes like:
# {
#   id: 1,
#   locale_code: "en",
#   continent_code: "AS",
#   continent_name: "Asia",
#   country_iso_code: "IN",
#   country_name: "India",
#   is_in_european_union: false
# }

Database Setup

The gem provides database migrations for setting up the required tables. Run these migrations after installing the gem:

rails generate cm_geocoder:install
rails db:migrate

This will create:

  • cm_geo_ip_networks table for storing IP network ranges
  • cm_geo_ip_locations table for storing geolocation data

To seed the IP data:

rake cm_geocoder:import_ip_data

Or you can use the fast import method but you can't use geocoder till you run the import:

rake cm_geocoder:import_ip_data_fast

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/commutatus/cm-geocoder. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the CmGeocoder project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.