Country List API Documentation

Overview

This API retrieves a paginated list of all countries. It returns countries along with their codes and names in different languages.

---

API Endpoint

• URL: {{host}}/hub/b2c/countries/search
• Method: POST
• Content-Type: application/json

---

Headers

Key	Value	Description
Content-Type	application/json	Request/Response format

---

Request Body

The request body must be an empty JSON object {}.

---

Sample Request

curl --location '{{host}}/hub/b2c/countries/search' \
--header 'Content-Type: application/json' \
--data '{}'

---

Sample Response

{
  "durationInMilisecond": 19,
  "totalCount": 250,
  "totalPage": 13,
  "pageSize": 20,
  "pageIndex": 0,
  "clientOverride": false,
  "data": [
    {
      "countryCode": "ZW",
      "name": "Zimbabwe",
      "nameVN": "Zimbabwe",
      "continentCode": "AF"
    },
    {
      "countryCode": "ZM",
      "name": "Zambia",
      "nameVN": "Zambia",
      "continentCode": "AF"
    },
    {
      "countryCode": "ZA",
      "name": "South Africa",
      "nameVN": "Nam Phi",
      "continentCode": "AF"
    },
    {
      "countryCode": "YT",
      "name": "Mayotte",
      "nameVN": "Mayotte",
      "continentCode": "AF"
    },
    {
      "countryCode": "YE",
      "name": "Yemen",
      "nameVN": "Yemen",
      "continentCode": "AS"
    },
    {
      "countryCode": "XK",
      "name": "Kosovo",
      "nameVN": "Cộng hòa Kosovo",
      "continentCode": "EU"
    },
    {
      "countryCode": "WS",
      "name": "Samoa",
      "nameVN": "Samoa",
      "continentCode": "OC"
    },
    {
      "countryCode": "WF",
      "name": "Wallis and Futuna",
      "nameVN": "Wallis và Futuna",
      "continentCode": "OC"
    },
    {
      "countryCode": "VU",
      "name": "Vanuatu",
      "nameVN": "Vanuatu",
      "continentCode": "OC"
    },
    {
      "countryCode": "VN",
      "name": "Viet Nam",
      "nameVN": "Việt Nam",
      "continentCode": "AS"
    },
    {
      "countryCode": "VI",
      "name": "Virgin Islands, U.S.",
      "nameVN": "Quần đảo Virgin thuộc Mỹ",
      "continentCode": "NA"
    },
    {
      "countryCode": "VG",
      "name": "Virgin Islands, British",
      "nameVN": "Quần đảo Virgin thuộc Anh",
      "continentCode": "NA"
    },
    {
      "countryCode": "VE",
      "name": "Venezuela, Bolivarian Republic of",
      "nameVN": "Venezuela (Cộng hòa Bolivar Venezuela)",
      "continentCode": "SA"
    },
    {
      "countryCode": "VC",
      "name": "Saint Vincent and the Grenadines",
      "nameVN": "Saint Vincent và Grenadines",
      "continentCode": "NA"
    },
    {
      "countryCode": "VA",
      "name": "Holy See (Vatican City State)",
      "nameVN": "Vatican",
      "continentCode": "EU"
    },
    {
      "countryCode": "UZ",
      "name": "Uzbekistan",
      "nameVN": "Uzbekistan",
      "continentCode": "AS"
    },
    {
      "countryCode": "UY",
      "name": "Uruguay",
      "nameVN": "Uruguay",
      "continentCode": "SA"
    },
    {
      "countryCode": "US",
      "name": "United States",
      "nameVN": "Hoa Kỳ",
      "continentCode": "NA"
    },
    {
      "countryCode": "UM",
      "name": "United States Minor Outlying Islands",
      "nameVN": "Các tiểu đảo xa của Hoa Kỳ",
      "continentCode": "OC"
    },
    {
      "countryCode": "UG",
      "name": "Uganda",
      "nameVN": "Uganda",
      "continentCode": "AF"
    }
  ]
}

---

Response Field Description

This section describes the fields returned in the API response. All field description tables in this section follow the | Field | Type | Example | Description | format.

Root Level Fields

These fields are present at the top level of the JSON response, providing metadata and the main data payload.

Field	Type	Example	Description
durationInMilisecond	Number	92	Time taken for the API to process the request, in milliseconds.
totalCount	Number	54	Total number of country items matching the filter criteria.
totalPage	Number	3	Total number of pages available based on pageSize and totalCount.
pageSize	Number	20	Number of country items returned per page in the data array.
pageIndex	Number	0	The current page index (0-based) of the returned set of countries.
clientOverride	Boolean	false	Indicates if any client-side override logic was applied to the response.
data	Array	[{}, {}, ...]	An array of Country Objects. See details below.

Country Object

These objects are found within the data array in the response. Each object represents a single country.

Field	Type	Example	Description
countryCode	String	"AF"	The 2-letter ISO 3166-1 alpha-2 country code.
name	String	"Afghanistan"	The common English name of the country.
nameVN	String	"Afghanistan"	The Vietnamese name of the country.
continentCode	String	"AS"	The 2-letter code representing the continent.

---

Notes

• Sending an empty JSON object {} as the request body typically retrieves all entries, paginated by default.
• If the filter parameter is used, it defines specific search conditions.
• countryCode uses the ISO 3166-1 alpha-2 standard.
• continentCode uses 2-letter abbreviations (e.g., "AS" for Asia, "EU" for Europe, "AF" for Africa, "NA" for North America, "SA" for South America, "OC" for Oceania, "AN" for Antarctica).
• The response is paginated. Use pageIndex and pageSize in conjunction with totalCount and totalPage to navigate through results if they span multiple pages.
• The durationInMilisecond field can be useful for monitoring API performance.