探索全球地理信息：City-State Ruby Gem

City-State 是一款简洁而强大的 Ruby 库，它允许您轻松地获取任何国家的州列表以及任何州的城市列表。基于 MaxMind 数据库，它提供了准确且全面的世界各国地理信息。

兼容性

本项目主要针对 Ruby 3 及更高版本进行开发和维护。如果您仍在使用 Ruby 2，请查阅 v0 分支以获得兼容支持。

Ruby 3 和更高版本

• 这是主开发分支。
• 新特性和改进将在此分支上添加。
• 确保您的环境已安装 Ruby 3 或更高版本。

Ruby 2 支持

• 对于 Ruby 2 用户，请切换到 v0 分支。
• v0 分支处于维护模式，只接收错误修复，不再新增功能。

安装与使用

要开始使用 City-State，只需在您的 Gemfile 中加入：

gem 'city-state'

然后运行：

$ bundle install

获取数据

获取指定国家（如美国）的州列表：

CS.states(:US)

列出特定州（如阿拉斯加）及其所在国家（美国）的城市：

CS.cities(:AK, :US)

数据库查询是大小写不敏感的，您可以使用各种变体。

自定义名称

通过创建 db/cities-lookup.yml、db/states-lookup.yml 和 db/countries-lookup.yml 文件，您可以对城市、州或国家名称进行重命名或添加缺失的城市。

例如，将国家 US 改为 America：

# db/countries-lookup.yml
US: "America"

或者将州名 California 更改为 Something Else：

# db/states-lookup.yml
US:
  CA: Something Else

数据库更新

MaxMind 每周二更新其数据库。从 2019 年底开始，尽管需要免费注册并获取许可证密钥，但不需要下载新的数据文件。通过调用 CS.set_license_key 方法，设置您的许可证密钥即可自动更新数据。

使用自定义数据库

若您已有 MaxMind 的 CSV 数据文件，可以使用 CS.set_maxmind_zip_url 设置自定义 URL 来使用它。

开源与许可证

City-State 遵循 MIT 许可证，由 Daniel Loureiro 创建。MaxMind 数据库则遵循 Creative Commons Attribution 3.0 Unported License。

更多信息

了解更多关于 City-State 如何创建的细节以及其他更新，查看 CHANGELOG.md。

这个强大而灵活的库使开发者能快速集成地理信息，无论是在创建地理位置应用，还是在处理与国家和地区相关的数据分析时，都能提供极大的便利。立即尝试 City-State，并为您的项目解锁全球地理数据的潜力！