African-states-and-tribes

A lightweight zero-dependency JavaScript/TypeScript utility library for African countries and their corresponding states and tribes, dynamically loaded by country code. It provides structured access to comprehensive data on African countries and their administrative geography and ethnic groups.

The library includes country-level metadata (such as name, capital, currency, phone code, flag, and ISO codes), supports geographic hierarchies including local government areas (LGAs) and other administrative subdivisions across all countries, and offers detailed tribal distributions by region or state, as well as major ethnic group data per country.

🚀 Features

✅ List all African countries

✅ Fetch a single country by its ISO code

✅ Get state/tribal data for each country (on-demand)

✅ Lightweight and async — loads only what you need

✅ Simple, modular, and TypeScript-friendly

Install

npm i african-states-and-tribes

Usage

• ES6 Module usage

  import { 
     getCountries, 
     getCountry, 
     getCountryStates, 
     getCountriesAndStates, 
     getCountryAndState 
  } from 'african-states-and-tribes'

• ES5 Module usage

  const africanStates = require('african-states-and-tribes')

Docs

• Get all Countries

  import { getCountries } from 'african-states-and-tribes'
  
  getCountries().then(countries =>{
      console.log(countries)
  })

  Output:

      [
          {
                  phoneCode: 244,
                  capitalCity: "Luanda",
                  colonialMaster: [
                      {
                          name: "Portugal",
                          countryCode: "PT"
                      }
                  ],
                  countryCode: "AO",
                  flagEmoji: "🇦🇴",
                  name: "Angola",
                  currency: "Angolan kwanza",
                  currencyCode: "AOA",
                  currencySymbol: "Kz",
                  officialLanguage: "Portuguese",
                  majorEthnicGroups: ["Bakongo", "Mbundu", "Ovimbundu"],
                  timezones: [
                      {
                          iana: "Africa/Luanda",
                          gmtOffset: "+01:00"
                      }
                  ]
          },
          {
                  phoneCode: 229,
                  capitalCity: "Porto-Novo",
                  colonialMaster: [
                      {
                          name: "France",
                          countryCode: "FR"
                      }
                  ],
                  countryCode: "BJ",
                  flagEmoji: "🇧🇯",
                  name: "Benin",
                  currency: "West African CFA franc",
                  currencyCode: "XOF",
                  currencySymbol: "Fr",
                  officialLanguage: "French",
                  majorEthnicGroups: ["Bariba", "Fon (Dahomey)", "Yoruba"],
                   timezones: [
                      {
                          iana: "Africa/Porto-Novo",
                          gmtOffset: "+01:00"
                      }
                  ]
          }
          ...
      ]

• Get All African Countries + State/Tribal Data

  import { getCountriesAndStates } from 'african-states-and-tribes'
  
  getCountriesAndStates().then(countries =>{
      console.log(countries)
  })

  Output:

   [
      {
          phoneCode: 244,
          capitalCity: "Luanda",
          colonialMaster:"",
          countryCode:"AO",
          flagEmoji: "🇦🇴",
          name: "Angola",
          currency: "Angolan kwanza",
          currencyCode:"AOA",
          currencySymbol:"Kz",
          officialLanguage: "Portuguese",
          majorEthnicGroups: ["Bakongo", "Mbundu", "Ovimbundu"],
          states:[
              {
                  capitalCity:"Caxito",
                  subdivisions:["Ambriz", "Bula Atumba", "Dande", "Dembos","Nambuangongo", "Pango Aluquém"],
                  geoPoliticalZone:"",
                  location:"North",
                  name: "Bengo",
                  stateCode: "BGO",
                  tribes:["Bakongo", "Kimbundu (Mbundu)", "Kikongo","Songo"],
                  type: "province"
              },
              {
                  capitalCity:"Benguela",
                  subdivisions:[],
                  geoPoliticalZone:"",
                  location:"West Central",
                  name: "Benguela",
                  stateCode: "BGU",
                  tribes:["Herero", "Khoisan (San)", "Nyaneka-Nkhumbi", "Ovimbundu"],
                  type: "province"
              },
              ... // list of state/province/region and tribes that can be found there.
          ]
      }
      ...
   ]
  

• Get Specific Country by CountryCode

  import { getCountry } from 'african-states-and-tribes'
  
  getCountry("NG").then(country =>{
      console.log(country)
  })
  

  Output:

      {
          phoneCode: 234,
          capitalCity: "Abuja",
          colonialMaster: [
              {
                  name: "United Kingdom",
                  countryCode: "GB"
              }
          ],
          countryCode:"NG",
          flagEmoji: "🇳🇬",
          name: "Nigeria",
          currency: "Nigerian naira",
          currencyCode:"NGN",
          currencySymbol:"₦",
          officialLanguage: "English",
          majorEthnicGroups:["Fulani", "Hausa", "Igbo", "Yoruba"],
          timezones: [
              {
                  "iana": "Africa/Lagos",
                  "gmtOffset": "+01:00"
              }
          ]
      }
  

• Get Specific Country + State/Tribal Data by CountryCode

  import { getCountryAndState } from 'african-states-and-tribes'
  
   getCountryAndState("NG").then(country =>{
      console.log(country)
  })

  Output:

      {
          phoneCode: 234,
          capitalCity: "Abuja",
          colonialMaster: [
              {
                  name: "United Kingdom",
                  countryCode: "GB"
              }
          ],
          countryCode:"NG",
          flagEmoji: "🇳🇬",
          name: "Nigeria",
          currency: "Nigerian naira",
          currencyCode:"NGN",
          currencySymbol:"₦",
          officialLanguage: "English",
          majorEthnicGroups:["Fulani", "Hausa", "Igbo", "Yoruba"],
          states:[
               {
                  capitalCity:"Umuahia",
                  subdivisions: ["Aba North", "Aba South", "Arochukwu", "Bende", "Ikwuano", "Isiala Ngwa North", "Isiala Ngwa South", "Isuikwuato", "Obi Ngwa", "Ohafia", "Osisioma", "Ugwunagbo", "Ukwa East", "Ukwa West", "Umuahia North", "Umuahia South"],
                  geoPoliticalZone: "South East",
                  location:"South East",
                  name: "Abia",
                  stateCode: "AB",
                  tribes:["Igbo"],
                  type: "state"
              }
          ]
      }
  

• Get a Country's State/Tribal Data Only

  import { getCountryStates } from 'african-states-and-tribes'
  
  getCountryStates("NG").then(tribes =>{
      console.log(tribes)
  })

  Output:

    [
       {
          capitalCity:"Umuahia",
          subdivisions: ["Aba North", "Aba South", "Arochukwu", "Bende", "Ikwuano", "Isiala Ngwa North", "Isiala Ngwa South", "Isuikwuato", "Obi Ngwa", "Ohafia", "Osisioma", "Ugwunagbo", "Ukwa East", "Ukwa West", "Umuahia North", "Umuahia South"],
          geoPoliticalZone: "South East",
          location:"South East",
          name: "Abia",
          stateCode: "AB",
          tribes:["Igbo"],
          type: "state"
      },
      {
          capitalCity:"Uyo",
          subdivisions: ["Abak", "Eastern Obolo", "Eket", "Esit Eket", "Essien Udim", "Etim Ekpo", "Etinan", "Ibeno", "Ibesikpo Asutan", "Ibiono Ibom", "Ika", "Ikono", "Ikot Abasi", "Ikot Ekpene", "Ini", "Itu", "Mbo", "Mkpat Enin", "Nsit Atai", "Nsit Ibom", "Nsit Ubium", "Obot Akara", "Okobo", "Onna", "Oron", "Oruk Anam", "Udung Uko", "Ukanafun", "Uruan", "Urue Offong/Oruko", "Uyo"],
          geoPoliticalZone: "South South",
          location:"South South",
          name: "Akwa Ibom",
          stateCode: "AK",
          tribes:["Anang","Andoni", "Eket", "Ibeno", "Ibibio", "Obolo", "Okobo (Okkobor)", "Oron" ],
          type: "state"
      },
      ...
    ]

  Notes

  • All functions are asynchronous – you must use await or .then()

  • Tribe/state data is dynamically imported using import() for performance

  | Key | Description
  |----------------------------------------|----------------------------- | capitalCity | Country's capital city
  | colonialMaster | Country's colonial master
  | countryCode | Country's 2-alphabet country code
  | flagEmoji | Country's flag emoji | name | Country name | currency | Country's official currency | currencyCode | Country's official currency code | currencySymbol | Country's official currency symbol | officialLanguage | Country's official language | majorEthnicGroups | Major ethnic found in the country | states | Array containing country's states/provinces/regions | states.capitalCity | state/region/province capital city | states.subdivisions | state/region/province administrative sub divisions such as Local Government | states.geoPoliticalZone | Geopolitical zone in which the state/region/province falls under | states.location | state/region/province location on country's map | states.name | state/region/province | states.stateCode | state/region/province official code | states.tribes | Tribes found in state/region/province | states.type | type of either state/region/province

Data Sources

• https://www.vanguardngr.com/2017/05/full-list-of-all-371-tribes-in-nigeria-states-where-they-originate/
• https://euaa.europa.eu/
• https://www.citypopulation.de/
• https://www.odsef.fss.ulaval.ca/sites/odsef.fss.ulaval.ca/files/odsef_assani_web.pdf