countriesdb-validator

Backend validation package for CountriesDB. Provides server-side validation for country and subdivision codes using ISO 3166-1 and ISO 3166-2 standards.

📖 Full Documentation | 🌐 Website | 📦 GitHub Repository

Important: This package only provides validation methods. Data fetching for frontend widgets must be done through frontend packages (@countriesdb/widget-core, @countriesdb/widget).

Getting Started

⚠️ API Key Required: This package requires a CountriesDB private API key to function. You must create an account at countriesdb.com to obtain your private API key. Test accounts are available with limited functionality.

🔑 Get your API key - Create an account and get your private key
📚 View documentation - Complete API reference and examples
💬 Support - Get help and support

Features

✅ ISO 3166 Compliant - Validates ISO 3166-1 (countries) and ISO 3166-2 (subdivisions) codes
✅ Multiple Validation Options - Support for follow_upward, follow_related, and allow_parent_selection
✅ Batch Validation - Validate multiple countries or subdivisions in a single request
✅ Rails Integration - Built-in ActiveModel validators for seamless Rails integration
✅ Detailed Error Messages - Returns specific error messages from the CountriesDB API

Installation

gem install countriesdb-validator

Or add to your Gemfile:

gem 'countriesdb-validator'

Usage

Standalone Validator

require 'countriesdb-validator'

validator = CountriesDB::Validator.new(api_key: 'YOUR_API_KEY')

# Validate a single country
result = validator.validate_country('US')
if result[:valid]
  puts "Valid country"
else
  puts "Invalid: #{result[:message]}"
end

# Validate a single subdivision
result = validator.validate_subdivision('US-CA', 'US')
if result[:valid]
  puts "Valid subdivision"
end

# Validate multiple countries
results = validator.validate_countries(['US', 'CA', 'MX'])
results.each do |result|
  puts "#{result[:code]}: #{result[:valid] ? 'Valid' : 'Invalid'}"
end

# Validate multiple subdivisions
results = validator.validate_subdivisions(
  ['US-CA', 'US-NY', 'US-TX'],
  'US'
)

Rails Validation

Configuration

Add to config/application.rb or config/environments/*.rb:

config.countriesdb = {
  api_key: 'YOUR_API_KEY'
}

Using Validators

class User < ApplicationRecord
  validates :country, countriesdb: true
  validates :subdivision, countriesdb: { subdivision: true, country: :country }
end

# With options
class User < ApplicationRecord
  validates :country, countriesdb: { follow_upward: true }
  validates :subdivision, countriesdb: {
    subdivision: true,
    country: :country,
    follow_related: true,
    allow_parent_selection: true
  }
end

API Reference

`CountriesDB::Validator`

Main validator class.

Constructor

CountriesDB::Validator.new(api_key:)

Parameters:

api_key (required): Your CountriesDB API key

Methods

`validate_country(code, follow_upward: false)`

Validate a single country code.

Parameters:

code (String): ISO 3166-1 alpha-2 country code
follow_upward (Boolean): Check if country is referenced in a subdivision (default: false)

Returns: Hash with :valid (Boolean) and optional :message (String)

`validate_countries(codes, follow_upward: false)`

Validate multiple country codes.

Parameters:

codes (Array): Array of ISO 3166-1 alpha-2 country codes
follow_upward (Boolean): Always false for multi-value (disabled)

Returns: Array of results with :code, :valid, and optional :message

`validate_subdivision(code, country, follow_related: false, allow_parent_selection: false)`

Validate a single subdivision code.

Parameters:

code (String, nil): Subdivision code (e.g., 'US-CA') or nil/empty string
country (String): ISO 3166-1 alpha-2 country code
follow_related (Boolean): Check if subdivision redirects to another country (default: false)
allow_parent_selection (Boolean): Allow selecting parent subdivisions (default: false)

Returns: Hash with :valid (Boolean) and optional :message (String)

`validate_subdivisions(codes, country, follow_related: false, allow_parent_selection: false)`

Validate multiple subdivision codes.

Parameters:

codes (Array): Array of subdivision codes or nil/empty strings
country (String): ISO 3166-1 alpha-2 country code
follow_related (Boolean): Always false for multi-value (disabled)
allow_parent_selection (Boolean): Allow selecting parent subdivisions (default: false)

Returns: Array of results with :code, :valid, and optional :message

Examples

Runnable examples using this package are available in the countriesdb/examples repository:

ruby/backend-faraday – HTTP client examples using Faraday

Sinatra Example

require 'sinatra'
require 'countriesdb-validator'

validator = CountriesDB::Validator.new(api_key: 'YOUR_API_KEY')

post '/api/user' do
  country = params[:country]
  subdivision = params[:subdivision]

  country_result = validator.validate_country(country)
  unless country_result[:valid]
    status 422
    return { error: country_result[:message] }.to_json
  end

  subdivision_result = validator.validate_subdivision(subdivision, country)
  unless subdivision_result[:valid]
    status 422
    return { error: subdivision_result[:message] }.to_json
  end

  # Validation passed
  { message: 'Valid data' }.to_json
end

Requirements

Ruby 2.7+
Valid CountriesDB API key

License

This software is the proprietary property of NAYEE LLC. For licensing inquiries, please contact NAYEE LLC.