> ## Documentation Index
> Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Examples

> Comprehensive integration examples and real-world use cases for the Country State City API in multiple programming languages

## Complete Integration Examples

### Basic API Client Setup

Set up a robust API client with proper authentication and error handling:

<CodeGroup>
  ```javascript JavaScript/Node.js theme={null}
  class CountryStateCityAPI {
    constructor(apiKey) {
      this.apiKey = apiKey;
      this.baseURL = 'https://api.countrystatecity.in/v1';
    }

    async request(endpoint) {
      try {
        const response = await fetch(`${this.baseURL}${endpoint}`, {
          headers: {
            'X-CSCAPI-KEY': this.apiKey,
            'Content-Type': 'application/json'
          }
        });

        if (!response.ok) {
          if (response.status === 401) {
            throw new Error('Invalid API key. Please check your credentials.');
          } else if (response.status === 429) {
            throw new Error('Too many requests. Please try again later.');
          } else {
            throw new Error(`API error: ${response.status}`);
          }
        }

        return await response.json();
      } catch (error) {
        console.error('API request failed:', error);
        throw error;
      }
    }

    async getCountries() {
      return await this.request('/countries');
    }

    async getStates(countryCode) {
      return await this.request(`/countries/${countryCode}/states`);
    }

    async getCities(countryCode, stateCode = null) {
      const endpoint = stateCode 
        ? `/countries/${countryCode}/states/${stateCode}/cities`
        : `/countries/${countryCode}/cities`;
      return await this.request(endpoint);
    }

    async getCountryDetails(countryCode) {
      return await this.request(`/countries/${countryCode}`);
    }
  }

  // Usage
  const api = new CountryStateCityAPI('YOUR_API_KEY');
  const countries = await api.getCountries();
  const usStates = await api.getStates('US');
  const californiaCities = await api.getCities('US', 'CA');
  ```

  ```python Python theme={null}
  import requests
  from typing import Optional, Dict, List

  class CountryStateCityAPI:
      def __init__(self, api_key: str):
          self.api_key = api_key
          self.base_url = 'https://api.countrystatecity.in/v1'
          self.session = requests.Session()
          self.session.headers.update({
              'X-CSCAPI-KEY': api_key,
              'Content-Type': 'application/json'
          })
          
      def _request(self, endpoint: str) -> Dict:
          """Make authenticated request to API endpoint"""
          try:
              response = self.session.get(f"{self.base_url}{endpoint}")
              
              if response.status_code == 401:
                  raise ValueError('Invalid API key. Please check your credentials.')
              elif response.status_code == 429:
                  raise ValueError('Too many requests. Please try again later.')
              elif not response.ok:
                  raise ValueError(f'API error: {response.status_code}')
                  
              return response.json()
              
          except requests.exceptions.RequestException as e:
              raise ConnectionError(f'Request failed: {str(e)}')
      
      def get_countries(self) -> List[Dict]:
          """Get all countries"""
          return self._request('/countries')
      
      def get_states(self, country_code: str) -> List[Dict]:
          """Get states for a specific country"""
          return self._request(f'/countries/{country_code}/states')
      
      def get_cities(self, country_code: str, state_code: Optional[str] = None) -> List[Dict]:
          """Get cities for a country, optionally filtered by state"""
          endpoint = f'/countries/{country_code}/states/{state_code}/cities' if state_code else f'/countries/{country_code}/cities'
          return self._request(endpoint)
      
      def get_country_details(self, country_code: str) -> Dict:
          """Get detailed information for a specific country"""
          return self._request(f'/countries/{country_code}')

  # Usage
  api = CountryStateCityAPI('YOUR_API_KEY')
  countries = api.get_countries()
  us_states = api.get_states('US')
  california_cities = api.get_cities('US', 'CA')
  ```

  ```php PHP theme={null}
  <?php
  class CountryStateCityAPI {
      private $apiKey;
      private $baseUrl = 'https://api.countrystatecity.in/v1';
      
      public function __construct($apiKey) {
          $this->apiKey = $apiKey;
      }
      
      private function request($endpoint) {
          $curl = curl_init();
          
          curl_setopt_array($curl, [
              CURLOPT_URL => $this->baseUrl . $endpoint,
              CURLOPT_RETURNTRANSFER => true,
              CURLOPT_HTTPHEADER => [
                  'X-CSCAPI-KEY: ' . $this->apiKey,
                  'Content-Type: application/json'
              ],
              CURLOPT_TIMEOUT => 30
          ]);
          
          $response = curl_exec($curl);
          $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
          
          if (curl_error($curl)) {
              curl_close($curl);
              throw new Exception('Request failed: ' . curl_error($curl));
          }
          
          curl_close($curl);
          
          if ($httpCode === 401) {
              throw new Exception('Invalid API key. Please check your credentials.');
          } elseif ($httpCode === 429) {
              throw new Exception('Too many requests. Please try again later.');
          } elseif ($httpCode !== 200) {
              throw new Exception('API error: ' . $httpCode);
          }
          
          return json_decode($response, true);
      }
      
      public function getCountries() {
          return $this->request('/countries');
      }
      
      public function getStates($countryCode) {
          return $this->request("/countries/{$countryCode}/states");
      }
      
      public function getCities($countryCode, $stateCode = null) {
          $endpoint = $stateCode 
              ? "/countries/{$countryCode}/states/{$stateCode}/cities"
              : "/countries/{$countryCode}/cities";
          return $this->request($endpoint);
      }
  }

  // Usage
  $api = new CountryStateCityAPI('YOUR_API_KEY');
  $countries = $api->getCountries();
  $usStates = $api->getStates('US');
  ?>
  ```

  ```java Java theme={null}
  import java.io.IOException;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;
  import java.time.Duration;

  public class CountryStateCityAPI {
      private final String apiKey;
      private final String baseUrl = "https://api.countrystatecity.in/v1";
      private final HttpClient httpClient;
      
      public CountryStateCityAPI(String apiKey) {
          this.apiKey = apiKey;
          this.httpClient = HttpClient.newBuilder()
              .connectTimeout(Duration.ofSeconds(30))
              .build();
      }
      
      private String request(String endpoint) throws IOException, InterruptedException {
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(baseUrl + endpoint))
              .header("X-CSCAPI-KEY", apiKey)
              .header("Content-Type", "application/json")
              .GET()
              .build();
              
          HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
          
          if (response.statusCode() == 401) {
              throw new RuntimeException("Invalid API key. Please check your credentials.");
          } else if (response.statusCode() == 429) {
              throw new RuntimeException("Too many requests. Please try again later.");
          } else if (response.statusCode() != 200) {
              throw new RuntimeException("API error: " + response.statusCode());
          }
          
          return response.body();
      }
      
      public String getCountries() throws IOException, InterruptedException {
          return request("/countries");
      }
      
      public String getStates(String countryCode) throws IOException, InterruptedException {
          return request("/countries/" + countryCode + "/states");
      }
  }

  // Usage
  CountryStateCityAPI api = new CountryStateCityAPI("YOUR_API_KEY");
  String countries = api.getCountries();
  ```

  ```csharp C# theme={null}
  using System;
  using System.Net.Http;
  using System.Threading.Tasks;

  public class CountryStateCityAPI
  {
      private readonly HttpClient _httpClient;
      private readonly string _baseUrl = "https://api.countrystatecity.in/v1";

      public CountryStateCityAPI(string apiKey)
      {
          _httpClient = new HttpClient();
          _httpClient.DefaultRequestHeaders.Add("X-CSCAPI-KEY", apiKey);
          _httpClient.DefaultRequestHeaders.Add("Content-Type", "application/json");
          _httpClient.Timeout = TimeSpan.FromSeconds(30);
      }

      private async Task<string> RequestAsync(string endpoint)
      {
          try
          {
              var response = await _httpClient.GetAsync($"{_baseUrl}{endpoint}");
              
              if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
              {
                  throw new UnauthorizedAccessException("Invalid API key. Please check your credentials.");
              }
              else if (response.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
              {
                  throw new InvalidOperationException("Too many requests. Please try again later.");
              }
              
              response.EnsureSuccessStatusCode();
              return await response.Content.ReadAsStringAsync();
          }
          catch (HttpRequestException ex)
          {
              throw new Exception($"Request failed: {ex.Message}");
          }
      }

      public async Task<string> GetCountriesAsync()
      {
          return await RequestAsync("/countries");
      }

      public async Task<string> GetStatesAsync(string countryCode)
      {
          return await RequestAsync($"/countries/{countryCode}/states");
      }

      public void Dispose()
      {
          _httpClient?.Dispose();
      }
  }

  // Usage
  var api = new CountryStateCityAPI("YOUR_API_KEY");
  var countries = await api.GetCountriesAsync();
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "io"
      "net/http"
      "time"
  )

  type CountryStateCityAPI struct {
      apiKey  string
      baseURL string
      client  *http.Client
  }

  func NewCountryStateCityAPI(apiKey string) *CountryStateCityAPI {
      return &CountryStateCityAPI{
          apiKey:  apiKey,
          baseURL: "https://api.countrystatecity.in/v1",
          client: &http.Client{
              Timeout: 30 * time.Second,
          },
      }
  }

  func (api *CountryStateCityAPI) request(endpoint string) ([]byte, error) {
      req, err := http.NewRequest("GET", api.baseURL+endpoint, nil)
      if err != nil {
          return nil, err
      }
      
      req.Header.Set("X-CSCAPI-KEY", api.apiKey)
      req.Header.Set("Content-Type", "application/json")
      
      resp, err := api.client.Do(req)
      if err != nil {
          return nil, err
      }
      defer resp.Body.Close()
      
      if resp.StatusCode == 401 {
          return nil, fmt.Errorf("invalid API key")
      } else if resp.StatusCode == 429 {
          return nil, fmt.Errorf("too many requests")
      } else if resp.StatusCode != 200 {
          return nil, fmt.Errorf("API error: %d", resp.StatusCode)
      }
      
      return io.ReadAll(resp.Body)
  }

  func (api *CountryStateCityAPI) GetCountries() ([]byte, error) {
      return api.request("/countries")
  }

  func (api *CountryStateCityAPI) GetStates(countryCode string) ([]byte, error) {
      return api.request("/countries/" + countryCode + "/states")
  }

  // Usage
  func main() {
      api := NewCountryStateCityAPI("YOUR_API_KEY")
      countries, err := api.GetCountries()
      if err != nil {
          fmt.Println("Error:", err)
      }
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  class CountryStateCityAPI
    def initialize(api_key)
      @api_key = api_key
      @base_url = 'https://api.countrystatecity.in/v1'
    end

    private

    def request(endpoint)
      uri = URI("#{@base_url}#{endpoint}")
      
      http = Net::HTTP.new(uri.host, uri.port)
      http.use_ssl = true
      http.read_timeout = 30
      
      request = Net::HTTP::Get.new(uri)
      request['X-CSCAPI-KEY'] = @api_key
      request['Content-Type'] = 'application/json'
      
      response = http.request(request)
      
      case response.code.to_i
      when 401
        raise 'Invalid API key. Please check your credentials.'
      when 429
        raise 'Too many requests. Please try again later.'
      when 200
        JSON.parse(response.body)
      else
        raise "API error: #{response.code}"
      end
    end

    public

    def get_countries
      request('/countries')
    end

    def get_states(country_code)
      request("/countries/#{country_code}/states")
    end

    def get_cities(country_code, state_code = nil)
      endpoint = state_code ? 
        "/countries/#{country_code}/states/#{state_code}/cities" : 
        "/countries/#{country_code}/cities"
      request(endpoint)
    end
  end

  # Usage
  api = CountryStateCityAPI.new('YOUR_API_KEY')
  countries = api.get_countries
  us_states = api.get_states('US')
  ```
</CodeGroup>

## Real-World Use Cases

### 1. Complete Registration Form with Cascading Dropdowns

Build a comprehensive user registration form with dependent location selectors:

<CodeGroup>
  ```javascript React Example theme={null}
  import React, { useState, useEffect } from 'react';

  const LocationSelector = ({ apiKey, onLocationChange }) => {
    const [countries, setCountries] = useState([]);
    const [states, setStates] = useState([]);
    const [cities, setCities] = useState([]);
    const [selectedCountry, setSelectedCountry] = useState('');
    const [selectedState, setSelectedState] = useState('');
    const [selectedCity, setSelectedCity] = useState('');
    const [loading, setLoading] = useState(false);

    const api = new CountryStateCityAPI(apiKey);

    // Load countries on component mount
    useEffect(() => {
      const loadCountries = async () => {
        try {
          setLoading(true);
          const countriesData = await api.getCountries();
          setCountries(countriesData);
        } catch (error) {
          console.error('Failed to load countries:', error);
        } finally {
          setLoading(false);
        }
      };
      loadCountries();
    }, []);

    // Load states when country changes
    useEffect(() => {
      if (selectedCountry) {
        const loadStates = async () => {
          try {
            setLoading(true);
            const statesData = await api.getStates(selectedCountry);
            setStates(statesData);
            setSelectedState(''); // Reset state selection
            setCities([]); // Clear cities
            setSelectedCity(''); // Reset city selection
          } catch (error) {
            console.error('Failed to load states:', error);
          } finally {
            setLoading(false);
          }
        };
        loadStates();
      }
    }, [selectedCountry]);

    // Load cities when state changes
    useEffect(() => {
      if (selectedCountry && selectedState) {
        const loadCities = async () => {
          try {
            setLoading(true);
            const citiesData = await api.getCities(selectedCountry, selectedState);
            setCities(citiesData);
            setSelectedCity(''); // Reset city selection
          } catch (error) {
            console.error('Failed to load cities:', error);
          } finally {
            setLoading(false);
          }
        };
        loadCities();
      }
    }, [selectedState]);

    return (
      <div className="location-selector">
        <div className="form-group">
          <label htmlFor="country">Country *</label>
          <select
            id="country"
            value={selectedCountry}
            onChange={(e) => setSelectedCountry(e.target.value)}
            disabled={loading}
            required
          >
            <option value="">Select Country</option>
            {countries.map(country => (
              <option key={country.iso2} value={country.iso2}>
                {country.emoji} {country.name}
              </option>
            ))}
          </select>
        </div>

        <div className="form-group">
          <label htmlFor="state">State/Province *</label>
          <select
            id="state"
            value={selectedState}
            onChange={(e) => setSelectedState(e.target.value)}
            disabled={loading || !selectedCountry}
            required
          >
            <option value="">Select State</option>
            {states.map(state => (
              <option key={state.iso2} value={state.iso2}>
                {state.name}
              </option>
            ))}
          </select>
        </div>

        <div className="form-group">
          <label htmlFor="city">City *</label>
          <select
            id="city"
            value={selectedCity}
            onChange={(e) => setSelectedCity(e.target.value)}
            disabled={loading || !selectedState}
            required
          >
            <option value="">Select City</option>
            {cities.map(city => (
              <option key={city.id} value={city.id}>
                {city.name}
              </option>
            ))}
          </select>
        </div>

        {loading && <div className="loading">Loading...</div>}
      </div>
    );
  };
  ```

  ```python Flask Example theme={null}
  from flask import Flask, render_template, request, jsonify

  app = Flask(__name__)

  class LocationService:
      def __init__(self, api_key):
          self.api = CountryStateCityAPI(api_key)
      
      def get_countries_for_dropdown(self):
          """Format countries for HTML select dropdown"""
          try:
              countries = self.api.get_countries()
              return [
                  {'value': country['iso2'], 'text': f"{country.get('emoji', '')} {country['name']}"}
                  for country in countries
              ]
          except Exception as e:
              print(f"Error fetching countries: {e}")
              return []
      
      def get_states_for_dropdown(self, country_code):
          """Format states for HTML select dropdown"""
          try:
              states = self.api.get_states(country_code)
              return [
                  {'value': state['iso2'], 'text': state['name']}
                  for state in states
              ]
          except Exception as e:
              print(f"Error fetching states: {e}")
              return []

  location_service = LocationService('YOUR_API_KEY')

  @app.route('/')
  def registration_form():
      countries = location_service.get_countries_for_dropdown()
      return render_template('registration.html', countries=countries)

  @app.route('/api/states/<country_code>')
  def get_states(country_code):
      states = location_service.get_states_for_dropdown(country_code)
      return jsonify(states)

  @app.route('/register', methods=['POST'])
  def register_user():
      user_data = {
          'name': request.form.get('name'),
          'email': request.form.get('email'),
          'country': request.form.get('country'),
          'state': request.form.get('state'),
          'city': request.form.get('city')
      }
      
      if not all([user_data['country'], user_data['state'], user_data['city']]):
          return jsonify({'error': 'All location fields are required'}), 400
      
      return jsonify({'message': 'User registered successfully', 'user': user_data})

  if __name__ == '__main__':
      app.run(debug=True)
  ```
</CodeGroup>

### 2. E-commerce Shipping Calculator

Calculate shipping costs and delivery times based on geographical locations:

```javascript theme={null}
class ShippingCalculator {
  constructor(apiKey) {
    this.api = new CountryStateCityAPI(apiKey);
    this.shippingRates = {
      domestic: { base: 5.99, perKg: 1.50, deliveryDays: '2-3' },
      international: { 
        asia: { base: 25.99, perKg: 8.50, deliveryDays: '7-10' },
        europe: { base: 29.99, perKg: 9.50, deliveryDays: '7-12' },
        americas: { base: 19.99, perKg: 7.50, deliveryDays: '5-8' },
        africa: { base: 35.99, perKg: 12.50, deliveryDays: '10-15' }
      }
    };
  }

  async calculateShipping(fromCountryCode, toCountryCode, weight) {
    try {
      const [fromCountry, toCountry] = await Promise.all([
        this.api.getCountryDetails(fromCountryCode),
        this.api.getCountryDetails(toCountryCode)
      ]);

      // Domestic shipping
      if (fromCountryCode === toCountryCode) {
        const rate = this.shippingRates.domestic;
        return {
          cost: rate.base + (weight * rate.perKg),
          deliveryTime: rate.deliveryDays,
          type: 'Domestic',
          from: fromCountry.name,
          to: toCountry.name
        };
      }

      // International shipping
      const toRegion = this.getRegion(toCountry.region);
      const rate = this.shippingRates.international[toRegion];
      
      return {
        cost: rate.base + (weight * rate.perKg),
        deliveryTime: rate.deliveryDays,
        type: 'International',
        region: toRegion,
        from: fromCountry.name,
        to: toCountry.name
      };

    } catch (error) {
      throw new Error(`Shipping calculation failed: ${error.message}`);
    }
  }

  getRegion(countryRegion) {
    const regionMap = {
      'Asia': 'asia',
      'Europe': 'europe',
      'Americas': 'americas',
      'Africa': 'africa'
    };
    return regionMap[countryRegion] || 'international';
  }
}

// Usage
const calculator = new ShippingCalculator('YOUR_API_KEY');
const shippingInfo = await calculator.calculateShipping('US', 'CA', 2.5);
console.log(`Shipping cost: $${shippingInfo.cost.toFixed(2)}`);
console.log(`Delivery: ${shippingInfo.deliveryTime} business days`);
```

### 3. Multi-Currency Price Display

Display prices in local currencies based on user location:

```javascript theme={null}
class PriceLocalization {
  constructor(apiKey) {
    this.api = new CountryStateCityAPI(apiKey);
    this.exchangeRates = {}; // Cache exchange rates
    this.baseCurrency = 'USD';
  }

  async getLocalizedPrice(basePrice, userCountryCode) {
    try {
      const country = await this.api.getCountryDetails(userCountryCode);
      const currency = country.currency;

      if (currency === this.baseCurrency) {
        return {
          amount: basePrice,
          currency: currency,
          symbol: country.currency_symbol || '$',
          formatted: `${country.currency_symbol || '$'}${basePrice.toFixed(2)}`
        };
      }

      // Get exchange rate (you'd typically use a service like exchangerates-api.io)
      const rate = await this.getExchangeRate(this.baseCurrency, currency);
      const localAmount = basePrice * rate;

      return {
        amount: localAmount,
        currency: currency,
        symbol: country.currency_symbol || '',
        formatted: `${country.currency_symbol || ''}${localAmount.toFixed(2)}`,
        exchangeRate: rate,
        originalPrice: basePrice,
        originalCurrency: this.baseCurrency
      };

    } catch (error) {
      console.error('Price localization failed:', error);
      // Fallback to base price
      return {
        amount: basePrice,
        currency: this.baseCurrency,
        symbol: '$',
        formatted: `$${basePrice.toFixed(2)}`
      };
    }
  }

  async getExchangeRate(from, to) {
    // This is a placeholder - use a real exchange rate service
    const cacheKey = `${from}-${to}`;
    
    if (this.exchangeRates[cacheKey] && 
        this.exchangeRates[cacheKey].timestamp > Date.now() - 3600000) {
      return this.exchangeRates[cacheKey].rate;
    }

    // Mock exchange rate - replace with real service
    const mockRates = { 'EUR': 0.85, 'GBP': 0.73, 'CAD': 1.25, 'INR': 74.5 };
    const rate = mockRates[to] || 1;
    
    this.exchangeRates[cacheKey] = {
      rate: rate,
      timestamp: Date.now()
    };
    
    return rate;
  }
}
```

## Best Practices and Optimization

### Caching Strategy for Performance

Implement intelligent caching to minimize API calls and improve performance:

```javascript theme={null}
class OptimizedCountryStateCityAPI extends CountryStateCityAPI {
  constructor(apiKey, cacheOptions = {}) {
    super(apiKey);
    this.cache = new Map();
    this.cacheTTL = cacheOptions.ttl || 3600000; // 1 hour default
    this.requestQueue = new Map(); // Prevent duplicate requests
  }

  async request(endpoint) {
    // Check cache first
    const cached = this.cache.get(endpoint);
    if (cached && Date.now() - cached.timestamp < this.cacheTTL) {
      return cached.data;
    }

    // Check if request is already in progress
    if (this.requestQueue.has(endpoint)) {
      return await this.requestQueue.get(endpoint);
    }

    // Make request and cache the promise
    const requestPromise = super.request(endpoint);
    this.requestQueue.set(endpoint, requestPromise);

    try {
      const data = await requestPromise;
      this.cache.set(endpoint, {
        data,
        timestamp: Date.now()
      });
      return data;
    } finally {
      this.requestQueue.delete(endpoint);
    }
  }

  // Preload commonly used data
  async preloadEssentials() {
    const essentials = [
      '/countries',
      '/countries/US/states',
      '/countries/GB/states',
      '/countries/CA/states'
    ];

    await Promise.all(essentials.map(endpoint => this.request(endpoint)));
  }
}
```

## Need More Help?

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference">
    Complete API documentation with all endpoints and parameters.
  </Card>

  <Card title="SDKs & Libraries" icon="code" href="/api/sdks">
    Official SDKs and community libraries for popular programming languages.
  </Card>

  <Card title="Support" icon="headset" href="/api/faq">
    Get help from our community and support team.
  </Card>
</CardGroup>

<Note>
  All code examples are production-ready and include proper error handling and caching. Remember to replace `YOUR_API_KEY` with your actual API key from the [Country State City portal](https://app.countrystatecity.in).
</Note>