{"id":13483675,"url":"https://github.com/countries/countries","last_synced_at":"2025-12-17T02:59:44.689Z","repository":{"id":38236075,"uuid":"442308","full_name":"countries/countries","owner":"countries","description":"All sorts of useful information about every country packaged as convenient little country objects. It includes data from ISO 3166 (countries and states/subdivisions ), ISO 4217 (currency), and E.164 (phone numbers).","archived":false,"fork":false,"pushed_at":"2024-09-29T18:36:14.000Z","size":14516,"stargazers_count":2230,"open_issues_count":21,"forks_count":669,"subscribers_count":40,"default_branch":"master","last_synced_at":"2024-10-29T16:59:05.353Z","etag":null,"topics":["countries","iso3166","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/countries.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"pmor"}},"created_at":"2009-12-18T22:42:26.000Z","updated_at":"2024-10-28T23:30:19.000Z","dependencies_parsed_at":"2023-02-14T19:32:05.429Z","dependency_job_id":"a15f2d15-1fd9-424a-88cc-89489c2753a1","html_url":"https://github.com/countries/countries","commit_stats":{"total_commits":1117,"total_committers":296,"mean_commits":"3.7736486486486487","dds":0.7735004476275739,"last_synced_commit":"3639158bf98d2860c07f461e6af80d507a1e835f"},"previous_names":["hexorx/countries"],"tags_count":103,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/countries%2Fcountries","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/countries%2Fcountries/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/countries%2Fcountries/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/countries%2Fcountries/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/countries","download_url":"https://codeload.github.com/countries/countries/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234313638,"owners_count":18812686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["countries","iso3166","ruby"],"created_at":"2024-07-31T17:01:14.074Z","updated_at":"2025-12-17T02:59:44.683Z","avatar_url":"https://github.com/countries.png","language":"Ruby","readme":"# Countries\n\nCountries is a collection of all sorts of useful information for every country in the ISO 3166 standard. It contains info for the following standards ISO3166-1 (countries), ISO3166-2 (states/subdivisions), ISO4217 (currency) and E.164 (phone numbers).\n\nThe data used in this gem is also available as git submodules in [YAML](https://github.com/countries/countries-data-yaml) and [JSON](https://github.com/countries/countries-data-json) files.\n\n[![Gem Version](https://badge.fury.io/rb/countries.svg)](https://badge.fury.io/rb/countries) [![Tests](https://github.com/countries/countries/actions/workflows/tests.yml/badge.svg)](https://github.com/countries/countries/actions/workflows/tests.yml)\n [![CodeQL](https://github.com/countries/countries/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/countries/countries/actions/workflows/codeql-analysis.yml)\n\n\n## Installation\n\n```bash\n gem install countries\n ```\n\n Or you can install via Bundler if you are using Rails:\n\n```bash\nbundle add countries\n```\n\n## Basic Usage\n\nSimply load a new country object using Country.new(*alpha2*) or the shortcut Country[*alpha2*]. An example works best.\n\n```ruby\nc = ISO3166::Country.new('US')\n```\n\nGet all country codes (*alpha2*).\n\n```ruby\nISO3166::Country.codes\n#  [\"TJ\", \"JM\", \"HT\",...]\n```\n\n## Configuration\n\n### Country Helper\n\nSome apps might not want to constantly call `ISO3166::Country` this gem has a\nhelper that can provide a `Country` class\n\n```ruby\n# With global Country Helper\nc = Country['US']\n```\n\n**This will conflict with any existing `Country` constant**\n\nTo Use\n\n```ruby\ngem 'countries', require: 'countries/global'\n```\n\n## Upgrading to 4.2 and 5.x\n\nRelease 4.2.0 introduced changes to name attributes and finders and deprecated several methods to resolve some existing confusion regardign official ISO country names vs. the \"common names\" that are commonly used.\n\nThe 5.0 release removed these deprecated methods and also removed support for Ruby 2.5 and 2.6\n\nPlease see [UPGRADE.md](../master/UPGRADE.md) for more information\n\n## Attribute-Based Finder Methods\n\nYou can lookup a country or an array of countries using any of the data attributes via the find\\_country\\_by_*attribute* dynamic methods:\n\n```ruby\nc    = ISO3166::Country.find_country_by_iso_short_name('italy')\nc    = ISO3166::Country.find_country_by_any_name('united states')\nh    = ISO3166::Country.find_all_by(:translated_names, 'França')\nlist = ISO3166::Country.find_all_countries_by_region('Americas')\nc    = ISO3166::Country.find_country_by_alpha2(\"FR\")\n```\n\nFor a list of available attributes please see `ISO3166::DEFAULT_COUNTRY_HASH`.\nNote: searches are *case insensitive and ignore accents*.\n\n_Please note that `find_by_name`, `find_by_names`, `find_*_by_name` and `find_*_by_names`  methods were removed in 5.0. See [UPGRADE.md](../master/UPGRADE.md) for more information_\n\n## Country Info\n\n### Identification Codes\n\n```ruby\nc.number # =\u003e \"840\"\nc.alpha2 # =\u003e \"US\"\nc.alpha3 # =\u003e \"USA\"\nc.gec    # =\u003e \"US\"\n```\n\n### Names \u0026 Translations\n\n```ruby\nc.iso_long_name # =\u003e \"The United States of America\"\nc.iso_short_name # =\u003e \"United States of America\"\nc.iso_short_name_lower_case # =\u003e \"United States of America (the)\"\nc.common_name # =\u003e \"United States\" (This is a shortcut for c.translations('en'))\nc.unofficial_names # =\u003e [\"United States of America\", \"Vereinigte Staaten von Amerika\", \"États-Unis\", \"Estados Unidos\"]\n\n# Get the names for a country translated to its local languages\nc = ISO3166::Country[:BE]\nc.local_names # =\u003e [\"België\", \"Belgique\", \"Belgien\"]\nc.local_name # =\u003e \"België\"\n\n# Get a specific translation\n# `translation` method works with string or symbol locales\nc.translation('de') # =\u003e 'Vereinigte Staaten von Amerika'\nc.translation(:de) # =\u003e 'Vereinigte Staaten von Amerika'\n# `translations` method returns a symbol-keyed hash of translations\nc.translations[:fr] # =\u003e \"États-Unis\"\n\n# Get all translations for a locale, defaults to 'en'\nISO3166::Country.translations         # {\"de:\"Germany\",...}\nISO3166::Country.translations('de')   # {\"DE\"=\u003e\"Deutschland\",...}\nISO3166::Country.all_translated       # ['Germany', ...]\nq # ['Deutschland', ...]\n\n# Nationality\nc.nationality # =\u003e \"American\"\n```\n\n### Subdivisions \u0026 States\n\n```ruby\nc.subdivisions # =\u003e {\"CO\" =\u003e {\"name\" =\u003e \"Colorado\", \"names\" =\u003e \"Colorado\"}, ... }\nc.subdivision_types # =\u003e [\"state\", \"outlying_area\", \"district\"]\nc.subdivisions_of_types(['state']) # =\u003e {\"CO\" =\u003e {\"name\" =\u003e \"Colorado\", \"names\" =\u003e \"Colorado\"}, ... }\nc.humanized_subdivision_types # =\u003e [\"State\", \"Outlying area\", \"District\"]\n\n# This is now deprecated. #states is an alias of #subdivisions and returns all subdivisions regardless of type\nc.states # =\u003e {\"CO\" =\u003e {\"name\" =\u003e \"Colorado\", \"names\" =\u003e \"Colorado\"}, ... }\n\n\n# Get specific translations for the country subdivisions\nc.subdivision_names_with_codes('es') #=\u003e [ ..., [\"Nuevo Hampshire\", \"NH\"], [\"Nueva Jersey\", \"NJ\"], ... ]\n\n# Subdivision code with translations for all loaded locales\nc.subdivisions['NY'].code_with_translations #=\u003e {\"NY\"=\u003e{\"en\"=\u003e\"New York\"}, ...}\n```\n\n`#find_subdivision_by_name` Find a country's state using its code or name in any translation\n\n```ruby\n\u003e ISO3166::Country.new(\"IT\").find_subdivision_by_name(\"Toscana\").geo\n =\u003e {\"latitude\"=\u003e43.771389, \"longitude\"=\u003e11.254167, ... }\n\u003e ISO3166::Country.new(\"IT\").find_subdivision_by_name(\"Tuscany\").geo\n =\u003e {\"latitude\"=\u003e43.771389, \"longitude\"=\u003e11.254167, ... }\n```\n\n### Location\n\n```ruby\nc.latitude # =\u003e \"37.09024\"\nc.longitude # =\u003e \"-95.712891\"\n\nc.world_region # =\u003e \"AMER\"\nc.region # =\u003e \"Americas\"\nc.subregion # =\u003e \"Northern America\"\n```\n\nPlease note that `latitude_dec` and `longitude_dec` were deprecated on release 4.2 and removed in 5.0. These attributes have been redundant for several years, since the `latitude` and `longitude` fields have been switched decimal coordinates.\n\n### Timezones **(optional)**\n\nAdd `tzinfo` to your Gemfile and ensure it's required, Countries will not do this for you.\n\n```ruby\ngem 'tzinfo', '~\u003e 1.2', '\u003e= 1.2.2'\n```\n\n```ruby\nc.timezones.zone_identifiers # =\u003e [\"America/New_York\", \"America/Detroit\", \"America/Kentucky/Louisville\", ...]\nc.timezones.zone_info  # see [tzinfo docs](https://www.rubydoc.info/gems/tzinfo/TZInfo/CountryTimezone)\nc.timezones # see [tzinfo docs](https://www.rubydoc.info/gems/tzinfo/TZInfo/Country)\n```\n\n### Telephone Routing (E164)\n\n```ruby\nc.country_code # =\u003e \"1\"\nc.national_destination_code_lengths # =\u003e 3\nc.national_number_lengths # =\u003e 10\nc.international_prefix # =\u003e \"011\"\nc.national_prefix # =\u003e \"1\"\n```\n\n### Boundary Boxes\n\n```ruby\nc.min_longitude # =\u003e '45'\nc.min_latitude # =\u003e '22.166667'\nc.max_longitude # =\u003e '58'\nc.max_latitude # =\u003e '26.133333'\n\nc.bounds #\u003e {\"northeast\"=\u003e{\"lat\"=\u003e22.166667, \"lng\"=\u003e58}, \"southwest\"=\u003e{\"lat\"=\u003e26.133333, \"lng\"=\u003e45}}\n```\n\n### European Union Membership\n\n```ruby\nc.in_eu? # =\u003e false\n```\n\n### European Economic Area Membership\n\n```ruby\nc.in_eea? # =\u003e false\n```\n\n### European Single Market Membership\n\n```ruby\nc.in_esm? # =\u003e false\n```\n\n### EU VAT Area membership\n\n```ruby\nc.in_eu_vat? # =\u003e false\n```\n\n### UN membership\n\n```ruby\nc.in_un? # false\n```\n\n### GDPR Compliant (European Economic Area Membership or UK)\n\n```ruby\nc.gdpr_compliant? # =\u003e false\n```\n\n### Country Code in Emoji\n\n```ruby\nc = Country['MY']\nc.emoji_flag # =\u003e \"🇲🇾\"\n```\n\n### Country Distance Unit (miles/kilometres)\n\n```ruby\nc.distance_unit # =\u003e \"MI\"\n```\n\n### Country Vehicle Registration Code\n\n```ruby\nc.vehicle_registration_code # =\u003e \"D\"\n```\n\n### Plucking multiple attributes\n\n```ruby\nISO3166::Country.pluck(:alpha2, :iso_short_name) # =\u003e [[\"AD\", \"Andorra\"], [\"AE\", \"United Arab Emirates\"], ...\n```\n\n`.collect_countries_with` allows to collect various countries' information using any valid method and query value:\n```ruby\n\u003e ISO3166::Country.collect_countries_with(\"VR\",:subdivisions,:common_name)\n =\u003e [\"Italy\", \"Monaco\"]\n\u003e ISO3166::Country.collect_countries_with(\"Caribbean\",:subregion,:languages_spoken).flatten.uniq\n =\u003e [\"en\", \"fr\", \"es\", \"ht\", \"nl\"]\n\u003e ISO3166::Country.collect_countries_with(\"Oceania\",:region,:international_prefix).uniq\n =\u003e [\"00\", \"011\", \"0011\", \"19\", \"05\"]\n\u003e ISO3166::Country.collect_countries_with(\"Antarctica\",:continent,:emoji_flag)\n =\u003e [\"🇦🇶\", \"🇬🇸\", \"🇧🇻\", \"🇹🇫\", \"🇭🇲\"]\n\u003e ISO3166::Country.collect_countries_with(\"🇸🇨\",:emoji_flag,:common_name)\n =\u003e [\"Seychelles\"]\n```\n\n`.collect_likely_countries_by_subdivision_name` allows to lookup all countries having the given state code or state name (in any translation)\n\n```ruby\nISO3166::Country.collect_likely_countries_by_subdivision_name(\"San José\",:common_name)\n =\u003e [\"Costa Rica\", \"Uruguay\"]\n```\n\n### Conversions\n\n```ruby\nISO3166::Country.from_alpha3_to_alpha2('USA') # =\u003e \"US\"\nISO3166::Country.from_alpha2_to_alpha3('US') # =\u003e \"USA\"\n\nISO3166::Country.from_alpha2_to_alpha3('--') # =\u003e nil\n```\n\n## Currencies\n\nTo enable currencies extension please add the following to countries initializer.\n\n```ruby\nISO3166.configuration.enable_currency_extension!\n```\n\nPlease note that it requires you to add \"money\" dependency to your gemfile.\n\n```ruby\ngem \"money\", \"~\u003e 6.9\"\n```\n\nCountries now uses the [Money](https://github.com/RubyMoney/money) gem. What this means is you now get back a `Money::Currency` object that gives you access to all the currency information.\n\n```ruby\nc = ISO3166::Country['us']\nc.currency.iso_code # =\u003e 'USD'\nc.currency.name # =\u003e 'United States Dollar'\nc.currency.symbol # =\u003e '$'\n```\n\n## Address Formatting\n\nA template for formatting addresses is available through the address_format method. These templates are compatible with the [Liquid](https://shopify.github.io/liquid/) template system.\n\n```ruby\nc.address_format # =\u003e \"{{recipient}}\\n{{street}}\\n{{city}} {{region}} {{postalcode}}\\n{{country}}\"\n```\n\n## Selective Loading of Locales\n\nAs of 2.0 you can selectively load locales to reduce memory usage in production.\n\nBy default we load `I18n.available_locales` if I18n is present, otherwise only `[:en]`. This means almost any Rails environment will only bring in its supported translations.\n\nYou can add all the locales like this.\n\n```ruby\nISO3166.configure do |config|\n  config.locales = [:af, :am, :ar, :as, :az, :be, :bg, :bn, :br, :bs, :ca, :cs, :cy, :da, :de, :dz, :el, :en, :eo, :es, :et, :eu, :fa, :fi, :fo, :fr, :ga, :gl, :gu, :he, :hi, :hr, :hu, :hy, :ia, :id, :is, :it, :ja, :ka, :kk, :km, :kn, :ko, :ku, :lt, :lv, :mi, :mk, :ml, :mn, :mr, :ms, :mt, :nb, :ne, :nl, :nn, :oc, :or, :pa, :pl, :ps, :pt, :\"pt-BR\", :ro, :ru, :rw, :si, :sk, :sl, :so, :sq, :sr, :sv, :sw, :ta, :te, :th, :ti, :tk, :tl, :tr, :tt, :ug, :uk, :ve, :vi, :wa, :wo, :xh, :\"zh-cn\", :\"zh-tw\", :zu]\nend\n```\n\nor something a bit more simple\n```ruby\nISO3166.configure do |config|\n  config.locales = [:en, :de, :fr, :es]\nend\n```\n\nIf you change the value of `ISO3166.configuration.locales` after initialization, you should call `ISO3166::Data.reset` to reset the data cache, or you may end up with inconsistently loaded locales.\nAs of 5.1.1, subdivision translations also respect this and will only load the selected locales.\n\n## Loading Custom Data\n\nAs of 2.0 countries supports loading custom countries / overriding data in its data set, though if you choose to do this please contribute back to the upstream repo!\n\nAny country registered this way will have its data available for searching etc... If you are overriding an existing country, for cultural reasons, our code uses a simple merge, not a deep merge so you will need to __bring in all data you wish to be available__.  Bringing in an existing country will also remove it from the internal management of translations, __all registered countries will remain in memory__.\n\n```ruby\nISO3166::Data.register(\n  alpha2: 'LOL',\n  iso_short_name: 'Happy Country',\n  translations: {  # Can use string or symbol keys\n    'en' =\u003e 'Happy Country',\n    'de' =\u003e 'glückliches Land'\n  }\n)\n\nISO3166::Country.new('LOL').iso_short_name == 'Happy Country'\n```\n\n## Mongoid\n\nMongoid support has been added. It is required automatically if Mongoid is defined in your project.\n\nUse native country fields in your model:\n\n```ruby\nfield :country, type: Country\n```\n\nAdds native support for searching/saving by a country object or alpha2 code.\n\nSearching:\n\n```ruby\n# By alpha2\nspanish_things = Things.where(country: 'ES')\nspanish_things.first.country.iso_short_name    # =\u003e \"Spain\"\n\n# By object\nspanish_things = Things.where(country: Country.find_by_iso_short_name('Spain')[1])\nspanish_things.first.country.iso_short_name    # =\u003e \"Spain\"\n```\n\nSaving:\n\n```ruby\n# By alpha2\nspanish_things = Thing.new(country: 'ES')\nspanish_things.save!\nspanish_things.country.iso_short_name    # =\u003e \"Spain\"\n\n# By object\nspanish_things = Thing.new(country: Country.find_by_iso_short_name('Spain')[1])\nspanish_things.save!\nspanish_things.country.iso_short_name    # =\u003e \"Spain\"\n```\n\nNote that the database stores only the alpha2 code and rebuilds the object when queried. To return the country name by default you can override the reader method in your model:\n\n```ruby\ndef country\n  super.iso_short_name\nend\n```\n\n## Note on Patches/Pull Requests\n\n**Please do not submit pull requests on `cache/**/*`**. These files generated by a rake task when preparing new releases and are not meant to be manually updated.\n\nIf you with to submit a PR to update or correct country data, please edit the corresponding YAML file `lib/countries/data/**`. Changes to the YAML files will be injected during the next `rake update_cache`.\n\nThis project seeks to follow ISO3166, ISO4217 and E.164 standards in its data.\n\nThis project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## Copyright\n\nCopyright (c) 2012-2015 hexorx \\\nCopyright (c) 2015-2021 hexorx, rposborne \\\nCopyright (c) 2022 hexorx, rposborne, pmor\n\nSee LICENSE for details.\n","funding_links":["https://github.com/sponsors/pmor"],"categories":["Country Data","Ruby","ActiveRecord"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcountries%2Fcountries","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcountries%2Fcountries","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcountries%2Fcountries/lists"}