Countries API - Location Services

📡 Endpoint Overview

Mutation: fetchCountries(input: CountryQueryInput!): CountryResponse!

Returns all countries filtered by the user's language preference. The system automatically extracts the language code from metadata and returns country names in the appropriate language with fallback to default language if no translation is available.

📥 Input Parameters

Required Client-Side Parameters:

Field	Type	Description	Source
`meta.core.device_id`	String!	Unique device identifier	Client Required
`meta.core.session_id`	String!	Current session identifier	Client Required
`meta.core.request_id`	String!	Unique request identifier	Client Required

Optional Client-Side Parameters:

Field	Type	Description	Example
`meta.device.device_locale`	String	Device locale (we extract first 2 letters)	"en_US" → "en"
`meta.app.language_override`	String	User's language preference (highest priority)	"hi_IN" → "hi"
`page`	Int	Page number for pagination	1
`per_page`	Int	Items per page	20

📤 Response Structure

Country Object:

Field	Type	Description
`cnty_code`	String!	Country code (e.g., "US", "IN", "GB")
`cnty_name`	String!	Country name in detected language
`cnty_flag`	String	Country flag emoji or URL
`cnty_lng`	String!	Language code of returned name
`is_default`	Boolean!	Whether this is the default translation

Performance Metrics (Server-Side):

            {
  "response_time_ms": 45.2,        // Server processing time (100% reliable)
  "request_size_bytes": 1234,      // Actual request payload size
  "response_size_bytes": 5678,     // Actual response size
  "memory_usage_mb": 8.5,           // Server memory used
  "memory_peak_mb": 12.3,           // Peak memory usage
  "query_count": 3,                 // Database queries executed
  "query_time_ms": 12.5,            // Total DB query time
  "slow_queries": 0,                // Queries > 100ms
  "server_timestamp": "2026-05-30T10:30:45Z"
}
        

Meta Summary (Server-Captured):

            {
  "device_id": "device-123",         // From client meta
  "session_id": "session-456",       // From client meta
  "request_id": "request-789",       // From client meta
  "language_used": "hi",             // Extracted from metadata
  "language_source": "language_override", // Where language came from
  "device_type": "mobile",           // From client meta
  "device_os": "android",           // From client meta
  "app_name": "MyApp",              // From client meta
  "environment": "prod",            // From client meta
  "location_detected": true,       // If GPS coords provided
  "ip_address": "192.168.1.1",     // Server captured
  "server_timestamp": "2026-05-30T10:30:45Z"
}
        

💻 Example Query

            query GetCountries {
  fetchCountries(input: {
    meta: {
      core: {
        device_id: "device-123"
        session_id: "session-456"
        request_id: "request-789"
      }
      device: {
        device_type: "mobile"
        device_locale: "en_US"
        device_os: "android"
      }
      app: {
        app_name: "MyApp"
        app_version: "2.1.0"
        language_override: "hi_IN"
        environment: "prod"
      }
      network: {
        network_type: "wifi"
      }
    }
    page: 1
    per_page: 20
  }) {
    success
    status
    reason
    message
    data {
      cnty_code
      cnty_name
      cnty_flag
      cnty_lng
      is_default
    }
    performance {
      response_time_ms
      request_size_bytes
      response_size_bytes
      memory_usage_mb
      query_count
      server_timestamp
    }
    meta_summary {
      device_id
      language_used
      language_source
      device_type
      ip_address
      server_timestamp
    }
  }
}
        

Example Response:

            {
  "data": {
    "fetchCountries": {
      "success": true,
      "status": 200,
      "reason": "COUNTRIES_FETCHED",
      "message": "Countries fetched successfully",
      "data": [
        {
          "cnty_code": "US",
          "cnty_name": "United States",
          "cnty_flag": "🇺🇸",
          "cnty_lng": "en",
          "is_default": true
        },
        {
          "cnty_code": "IN",
          "cnty_name": "India",
          "cnty_flag": "🇮🇳",
          "cnty_lng": "hi",
          "is_default": false
        }
      ],
      "performance": {
        "response_time_ms": 45.2,
        "request_size_bytes": 1234,
        "response_size_bytes": 5678,
        "memory_usage_mb": 8.5,
        "query_count": 2,
        "server_timestamp": "2026-05-30T10:30:45Z"
      },
      "meta_summary": {
        "device_id": "device-123",
        "language_used": "hi",
        "language_source": "language_override",
        "device_type": "mobile",
        "ip_address": "192.168.1.1",
        "server_timestamp": "2026-05-30T10:30:45Z"
      }
    }
  }
}
        

🌐 Language Detection Logic

The system automatically detects language using this priority chain:

1

language_override (Highest Priority)

User's explicit language preference from app settings

Example: "hi_IN" → "hi", "en_US" → "en"

2

device_locale

Device's system locale setting

Example: "es_ES" → "es", "fr_FR" → "fr"

3

default (Fallback)

System default to English

Always returns "en" as last resort

🔧 Server vs Client Parameters

C Client-Side (Must Send)

Required:

• meta.core.device_id
• meta.core.session_id
• meta.core.request_id

Optional:

• meta.device.device_locale
• meta.app.language_override
• page, per_page

S Server-Side (Automatic)

Performance:

• Response time calculation
• Request/response size
• Memory usage tracking
• Database query metrics

Security & Info:

• IP address capture
• User agent logging
• Request timestamp
• Language extraction

⚠️ Error Responses

400 - Missing Required Fields

                    {
  "success": false,
  "status": 400,
  "reason": "MISSING_REQUIRED_FIELDS",
  "message": "device_id and session_id are required in meta.core",
  "data": []
}
                

204 - No Countries Found

                    {
  "success": false,
  "status": 204,
  "reason": "NO_COUNTRIES_FOUND",
  "message": "No countries available in database",
  "data": []
}
                