Location API - API Documentation

🌍 Overview

The Location Services API provides comprehensive location data including countries, states, and cities with built-in language detection and performance tracking. All location endpoints automatically detect the user's language preference from metadata and return localized results with comprehensive server-side metrics.

Key Features:

✅ Automatic language detection from metadata (en, hi, es, etc.)
✅ Comprehensive server-side performance tracking
✅ Complete metadata collection and analysis
✅ Language fallback system (language_override → device_locale → default)
✅ Pagination support for large datasets

🚀 Quick Start

Basic Query Structure:

            query GetCountries {
  fetchCountries(input: {
    meta: {
      core: {
        device_id: "device-123"
        session_id: "session-456"
        request_id: "request-789"
      }
      device: {
        device_locale: "en_US"
      }
    }
    page: 1
    per_page: 20
  }) {
    success
    data {
      cnty_code
      cnty_name
      cnty_flag
    }
    performance {
      response_time_ms
      request_size_bytes
      response_size_bytes
    }
    meta_summary {
      language_used
      language_source
    }
  }
}
        

📡 Available Endpoints

Countries API

fetchCountries

Get all countries with automatic language detection

View Documentation →

States API

fetchStates

Get states by country with language filtering

View Documentation →

Cities API

fetchCities

Get cities by state with language filtering

View Documentation →

Metadata Guide

Complete Reference

Understanding metadata and performance tracking

View Documentation →

🌐 Automatic Language Detection

The system automatically detects language preference from metadata with a smart fallback system:

Language Priority Chain:

1

language_override

User's explicit language preference (en_US → en)

2

device_locale

Device locale setting (hi_IN → hi)

3

default

Fallback to English (en)

Note: All language codes are normalized to 2-letter format (en, hi, es, fr, etc.) regardless of input format.

📊 Standard Response Structure

All location endpoints return a consistent response structure with comprehensive metrics:

            {
  "success": true,
  "status": 200,
  "reason": "COUNTRIES_FETCHED",
  "message": "Countries fetched successfully",
  "data": [ /* location data */ ],
  "performance": {
    "response_time_ms": 45.2,
    "request_size_bytes": 1234,
    "response_size_bytes": 5678,
    "memory_usage_mb": 8.5,
    "query_count": 3,
    "server_timestamp": "2026-05-30T10:30:45Z"
  },
  "meta_summary": {
    "device_id": "device-123",
    "language_used": "en",
    "language_source": "language_override",
    "ip_address": "192.168.1.1",
    "server_timestamp": "2026-05-30T10:30:45Z"
  }
}
        

✅ Client-Side (Must Send)

• meta.core.device_id (Required)
• meta.core.session_id (Required)
• meta.core.request_id (Required)
• meta.device.device_locale (Optional)
• meta.app.language_override (Optional)

🖥️ Server-Side (Automatic)

• Language extraction & normalization
• Response time measurement
• Request/response size tracking
• Memory usage monitoring
• IP address & user agent capture

⚠️ Error Handling

The API uses standard HTTP status codes and descriptive error messages:

Status Code	Reason	Description
200	SUCCESS	Request completed successfully
400	MISSING_REQUIRED_FIELDS	Required metadata fields are missing
204	NO_DATA_FOUND	No location data found for given criteria
500	INTERNAL_ERROR	Server error occurred