Countries

This guide explains how to interact with the Countries API in the Sumaya369.

List Countries

Endpoint

• Method: GET
• URL: /v1/mobile/countries

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Query Parameters

Parameter	Type	Description	Required
per_page	integer	Number of countries per page (default: 10)	No
list	boolean	Return simplified list format	No
select_country	boolean	Include user's current country based on IP (default: Saudi Arabia)	No
search_text	string	Search in country name and short name	No
priority	true	Filter by priority	No
orderBy	string	Sort field (default: short_name)	No

Success Response (List Format)

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "countries": [
            {
                "id": "18e1ceab-f28a-4fcc-929f-526b8f6e1557",
                "name": "السعودية",
                "phone_code": "+966",
                "selected": true
            },
            {
                "id": "baf72ad4-7d31-4ba0-ac4f-df292ba7133a",
                "name": "الإمارات",
                "phone_code": "+971",
                "selected": false
            },
            {
                "id": "ee336268-8656-4378-80d9-5e5e0f01e5dd",
                "name": "الكويت",
                "phone_code": "+965",
                "selected": false
            },
            {
                "id": "a902c239-6de9-457c-ab0d-0f9d2c6a520f",
                "name": "العراق",
                "phone_code": "+964",
                "selected": false
            },
            {
                "id": "c5172f20-b432-4db1-a32d-ba2f24b83054",
                "name": "الجزائر",
                "phone_code": "+213",
                "selected": false
            }
        ]
    },
    "status_code": 200
}

Success Response (Paginated Format)

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "current_page": 1,
        "first_page_url": "http://testing-api.sumaya369.net/v1/mobile/countries?per_page=80&page=1",
        "from": 1,
        "last_page": 4,
        "last_page_url": "http://testing-api.sumaya369.net/v1/mobile/countries?per_page=80&page=4",
        "links": [
            {
                "url": null,
                "label": "« السابق",
                "active": false
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/mobile/countries?per_page=80&page=1",
                "label": "1",
                "active": true
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/mobile/countries?per_page=80&page=2",
                "label": "2",
                "active": false
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/mobile/countries?per_page=80&page=3",
                "label": "3",
                "active": false
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/mobile/countries?per_page=80&page=4",
                "label": "4",
                "active": false
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/mobile/countries?per_page=80&page=2",
                "label": "التالي »",
                "active": false
            }
        ],
        "next_page_url": "http://testing-api.sumaya369.net/v1/mobile/countries?per_page=80&page=2",
        "path": "http://testing-api.sumaya369.net/v1/mobile/countries",
        "per_page": 80,
        "prev_page_url": null,
        "to": 80,
        "total": 249,
        "countries": [
            {
                "id": "22137252-cc11-4bd0-900d-aa886e6b143f",
                "name": "بالاو",
                "phone_code": "+680"
            },
            {
                "id": "9dd4de52-4c4a-40d1-8e85-151a6ab2310e",
                "name": "جزر بيتكيرن",
                "phone_code": "+872"
            },
            {
                "id": "5aec82ba-e9e0-4517-9213-3dece54e5827",
                "name": "رومانيا",
                "phone_code": "+40"
            },
            {
                "id": "6c5b06b4-24d5-4c0a-86f2-2b4d449ed08a",
                "name": "كوريا الشمالية",
                "phone_code": "+850"
            },
            {
                "id": "9aa06167-3b5b-4983-a01b-ee8eb716d154",
                "name": "جزر الولايات المتحدة الصغيرة النائية",
                "phone_code": ""
            },
            {
                "id": "c6ea122b-bea3-465b-ab90-6628f9493209",
                "name": "كاليدونيا الجديدة",
                "phone_code": "+687"
            },
            {
                "id": "0f81805d-0f13-4b0f-a171-924c6bf2ca98",
                "name": "نييوي",
                "phone_code": "+683"
            },
            {
                "id": "bf9c6845-e682-4fcd-8573-8172af01e45c",
                "name": "موزمبيق",
                "phone_code": "+258"
            }
        ]
    },
    "status_code": 200
}

Example Implementation Flow

1. Country Listing
   • Application sends request to /v1/mobile/countries
   • Optional query parameters:
     • Use list=true for simplified format
     • Use select_country=true to include the user's current country based on IP
     • Filter by priority
     • Search by name or short name
   • Display countries with pagination or as a simple list

Key Considerations

• Response caching is implemented for better performance
• Default sorting is by priority and then short name
• Saudi Arabia (SA) is set as the default selected country when requested and no geolocation service is available. (currently disabled)
• Selected country only works when list=true is used, otherwise it won't appear in the paginated result.
• Supports both list and paginated response formats
• Includes phone codes for international calling