Country Search API Documentation (Including AS Support)

Overview

This API enables searching for countries based on specified filter criteria. It returns a paginated list of countries matching the query, 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 Parameters

Main Parameters

Field	Type	Required	Description	Example/Values
filter	String	✅ Yes	JSON string representing the filter conditions.	{"and":[{"queryKey":"continentCode","queryType":"text","operation":"eq","queryValue":"AS"}]}

Filter Object (within the JSON string)

The filter string contains a JSON object with the following structure:

Field	Type	Required	Description	Example/Values
and	Array	✅ Yes	An array of filter condition objects.	[...]
or	Array	❌ No	An array of filter condition objects (alternative).	[...]

Filter Condition Object (elements within and or or arrays)

Field	Type	Required	Description	Example/Values
queryKey	String	✅ Yes	The field to apply the filter on.	"continentCode", "countryCode"
queryType	String	✅ Yes	The data type of the field for query.	"text", "number"
operation	String	✅ Yes	The comparison operator.	"eq" (equals), "contains", "neq"
queryValue	String	✅ Yes	The value to compare against.	"AS"

---

Sample Request

curl --location '{{host}}/hub/b2c/countries/search' \
--header 'Content-Type: application/json' \
--data '{
    "filter": "{\"and\":[{\"queryKey\":\"continentCode\",\"queryType\":\"text\",\"operation\":\"eq\",\"queryValue\":\"AS\"}]}"
}'

---

Sample Response

{
  "durationInMilisecond": 92,
  "totalCount": 54,
  "totalPage": 3,
  "pageSize": 20,
  "pageIndex": 0,
  "clientOverride": false,
  "data": [
    {
      "countryCode": "YE",
      "name": "Yemen",
      "nameVN": "Yemen",
      "continentCode": "AS"
    },
    {
      "countryCode": "VN",
      "name": "Viet Nam",
      "nameVN": "Việt Nam",
      "continentCode": "AS"
    },
    {
      "countryCode": "UZ",
      "name": "Uzbekistan",
      "nameVN": "Uzbekistan",
      "continentCode": "AS"
    },
    {
      "countryCode": "TW",
      "name": "Taiwan, Province of China",
      "nameVN": "Đài Loan (Tỉnh của Trung Quốc)",
      "continentCode": "AS"
    },
    {
      "countryCode": "TR",
      "name": "Turkey",
      "nameVN": "Thổ Nhĩ Kỳ",
      "continentCode": "AS"
    },
    {
      "countryCode": "TM",
      "name": "Turkmenistan",
      "nameVN": "Turkmenistan",
      "continentCode": "AS"
    },
    {
      "countryCode": "TL",
      "name": "Timor-Leste",
      "nameVN": "Đông Timor (Timor-Leste)",
      "continentCode": "AS"
    },
    {
      "countryCode": "TJ",
      "name": "Tajikistan",
      "nameVN": "Tajikistan",
      "continentCode": "AS"
    },
    {
      "countryCode": "TH",
      "name": "Thailand",
      "nameVN": "Thái Lan",
      "continentCode": "AS"
    },
    {
      "countryCode": "SY",
      "name": "Syrian Arab Republic",
      "nameVN": "Syria (Cộng hòa Ả Rập Syria)",
      "continentCode": "AS"
    },
    {
      "countryCode": "SG",
      "name": "Singapore",
      "nameVN": "Singapore",
      "continentCode": "AS"
    },
    {
      "countryCode": "SA",
      "name": "Saudi Arabia",
      "nameVN": "Ả Rập Xê Út",
      "continentCode": "AS"
    },
    {
      "countryCode": "QA",
      "name": "Qatar",
      "nameVN": "Qatar",
      "continentCode": "AS"
    },
    {
      "countryCode": "PS",
      "name": "Palestine, State of",
      "nameVN": "Palestine (Nhà nước Palestine)",
      "continentCode": "AS"
    },
    {
      "countryCode": "PK",
      "name": "Pakistan",
      "nameVN": "Pakistan",
      "continentCode": "AS"
    },
    {
      "countryCode": "PH",
      "name": "Philippines",
      "nameVN": "Philippines",
      "continentCode": "AS"
    },
    {
      "countryCode": "OM",
      "name": "Oman",
      "nameVN": "Oman",
      "continentCode": "AS"
    },
    {
      "countryCode": "NP",
      "name": "Nepal",
      "nameVN": "Nepal",
      "continentCode": "AS"
    },
    {
      "countryCode": "MY",
      "name": "Malaysia",
      "nameVN": "Malaysia",
      "continentCode": "AS"
    },
    {
      "countryCode": "MV",
      "name": "Maldives",
      "nameVN": "Maldives",
      "continentCode": "AS"
    }
  ]
}

---

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	"YE"	The 2-letter ISO 3166-1 alpha-2 country code.
name	String	"Yemen"	The common English name of the country.
nameVN	String	"Yemen"	The Vietnamese name of the country.
continentCode	String	"AS"	The 2-letter code representing the continent.

---

Notes

• The filter parameter in the request body is a JSON string that defines search conditions. For example, to find countries in Asia, the filter would be {"and":[{"queryKey":"continentCode","queryType":"text","operation":"eq","queryValue":"AS"}]}.
• 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.