Frankdroid7/rest_countries_package

rest_countries_data

rest_countries_data Logo

---

A Dart wrapper around the REST Countries v3.1 API that provides a fully-typed, developer-friendly interface for accessing detailed country data.

---

✨ Features

• Get all countries with selected fields (limited to 10 fields)
• Query countries by:
  • Capital
  • Full name or partial name
  • ISO 3166-1 code or list of codes
  • Region / Subregion
  • Language / Currency / Demonym
  • Translation
  • Independence status
• Built-in CountryModel to map the API response
• Enum-based CountryFields selector for fine-grained queries
• Clean separation of concerns via Repository, API and Domain layers

---

🚀 Getting Started

1. Install the Package

Add to your pubspec.yaml:

dependencies:
  rest_countries_data: ^1.0.0

Then run:

# For Dart users
dart pub get

# For Flutter users
flutter pub get

2. Import It

import 'package:rest_countries_data/rest_countries_data.dart';

---

📦 Usage

Fetch All Countries with Selected Fields

final countries = await RestCountries.getAllCountries(
  fields: [CountryFields.name, CountryFields.capital, CountryFields.region],
);

Field Limitation ⚠️

When using the fields parameter in methods like getAllCountries, the maximum number of allowed fields is 10. This limit is enforced by the REST Countries API.

Also note: Whenever you specify the fields property, the properties that will be available in the returned CountryModel depend entirely on which CountryFields you request. If you omit a field, the corresponding property in CountryModel may be null.

Get Countries by Capital

final country = await RestCountries.getCountryByCapital(capital: 'Paris');

Get a Country by ISO Code

final country = await RestCountries.getCountryByCode(code: 'NG');

Get Countries by Currency

final countries = await RestCountries.getCountriesByCurrency(currency: 'USD');

Get Countries by Region

final countries = await RestCountries.getCountriesByRegion(region: 'Europe');

Get Countries by SubRegion

final countries = await RestCountries.getCountriesBySubRegion(subRegion: 'Eastern Africa');

Get Country by Full Name

final country = await RestCountries.getCountryByFullName(fullName: 'Federal Republic of Nigeria');

Get Countries by Language, Demonym, or Translation

final countries = await RestCountries.getCountriesByLanguage(language: 'en');
final countries = await RestCountries.getCountriesByDemonym(demonym: 'Nigerian');
final countries = await RestCountries.getCountriesByTranslation(translation: 'Niger');

Get Countries by Independence Status

final countries = await RestCountries.getCountriesByIndependentStatus(
  independent: true,
  fields: [CountryFields.name, CountryFields.flag],
);

---

📚 Data Model

CountryModel (Simplified)

class CountryModel {
  final Name? name;
  final List<String>? capital;
  final String? region;
  final String? subregion;
  final Map<String, dynamic>? flags;
  // ...
}

class Name {
  final String common;
  final String official;
  final Map<String, NativeName>? nativeName;
}

CountryFields Enum

Use the CountryFields enum to limit which fields are returned from the API:

CountryFields.name
CountryFields.capital
CountryFields.region
CountryFields.area
CountryFields.languages
// etc.

Note: Maximum 10 fields per request for getAllCountries()

🧩 Utility Getter

getCountryPhoneNumberCode

This convenience getter is available on the CountryModel and returns the full numeric dialing code (e.g., +234 for the country Nigeria). It is constructed by combining idd.root and idd.suffixes in the CountryModel.

---

🔍 API Overview

Method	Description
getAllCountries({required fields})	Get all countries with selected fields
getCountryByCapital({required capital})	Filter by capital city
getCountryByCode({required code})	Get a single country by ISO code
getCountriesByCodes({required codes})	Get multiple countries by ISO codes
getCountriesByCurrency({required currency})	Filter by currency
getCountriesByDemonym({required demonym})	Filter by demonym
getCountriesByLanguage({required language})	Filter by spoken language
getCountriesByRegion({required region})	Filter by region
getCountriesBySubRegion({required subRegion})	Filter by subregion
getCountriesByTranslation({required translation})	Filter by translated country name
getCountryByFullName({required fullName})	Get a country by its full name
getCountriesByName({required name})	Filter by partial or full name
getCountriesByIndependentStatus(...)	Filter by independence and optionally fields
CountryModel.getCountryPhoneNumberCode	Get the phone dialing code of a country (e.g. +234)

📊 Example (Run it)

import 'package:rest_countries_data/rest_countries_data.dart';

void main() async {
  final countries = await RestCountries.getCountriesByRegion(region: 'Africa');

  for (var country in countries) {
    print(country.name?.common);
  }
}

---

🚪 Contributing

Pull requests are welcome! If you have ideas or find bugs, feel free to open an issue.

---

Development Setup

After cloning the repository, install the git hooks for automatic formatting and linting:

./install-hooks.sh

This will set up a pre-commit hook that:

• Automatically formats all Dart files
• Runs dart analyze to check for issues
• Prevents commits if there are analysis errors

👋 Author

Maintained by Franklin Oladipo

---

📄 License

BSD 3-Clause