Frequently Asked Questions

curl -X GET 'https://api.countrystatecity.in/v1/countries' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

X-CSCAPI-KEY: YOUR_API_KEY

curl -X GET 'https://api.countrystatecity.in/v1/countries' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY' \
  -w "HTTP Status: %{http_code}\n"

{
  "status": "error",
  "message": "Daily usage limit exceeded. Please try again tomorrow or contact support for higher limits.",
  "details": {
    "limit": 100,
    "period": "daily",
    "resetAt": "2026-08-14T00:00:00.000Z",
    "upgradeUrl": "https://app.countrystatecity.in/pricing",
    "tier": "community"
  }
}

{
  "status": "error",
  "message": "This feature is not available on your current plan.",
  "details": {
    "feature": "fuzzySearch",
    "currentTier": "community",
    "requiredTier": "professional",
    "upgradeUrl": "https://app.countrystatecity.in/pricing"
  }
}

class APICache {
  constructor(ttl = 24 * 60 * 60 * 1000) {
    this.cache = new Map();
    this.ttl = ttl;
  }

  get(key) {
    const item = this.cache.get(key);
    if (!item || Date.now() - item.timestamp > this.ttl) {
      return null;
    }
    return item.data;
  }

  set(key, data) {
    this.cache.set(key, { data, timestamp: Date.now() });
  }
}

{
  "id": 12345,
  "name": "Los Angeles",
  "latitude": "34.05223",
  "longitude": "-118.24368",
  "country_code": "US",
  "state_code": "CA"
}

const [selectedCountry, setSelectedCountry] = useState('');
const [states, setStates] = useState([]);
const [cities, setCities] = useState([]);

// Load states when country changes
useEffect(() => {
  if (selectedCountry) {
    loadStates(selectedCountry);
    setCities([]); // Clear cities when country changes
  }
}, [selectedCountry]);

const loadStates = async (countryCode) => {
  const statesData = await api.getStates(countryCode);
  setStates(statesData);
};

async function makeAPIRequest(endpoint) {
  try {
    const response = await fetch(endpoint, { headers });

    if (response.status === 401) {
      throw new Error('INVALID_API_KEY');
    } else if (response.status === 404) {
      throw new Error('NOT_FOUND');
    } else if (!response.ok) {
      throw new Error('API_ERROR');
    }

    return await response.json();

  } catch (error) {
    if (error.message === 'INVALID_API_KEY') {
      // Notify user to check API configuration
      console.error('Invalid API key configuration');
    }
    throw error;
  }
}

// Browser localStorage
const cacheKey = 'countries_data';
const cachedData = localStorage.getItem(cacheKey);
const isExpired = Date.now() - cachedData?.timestamp > 24 * 60 * 60 * 1000;

if (cachedData && !isExpired) {
  return JSON.parse(cachedData).data;
}

// Server-side caching (Redis, Memcached, etc.)
const redis = require('redis');
const client = redis.createClient();

const cached = await client.get('countries');
if (cached) return JSON.parse(cached);

const data = await fetchFromAPI();
await client.setex('countries', 86400, JSON.stringify(data)); // 24h TTL

// First, verify the country exists
const countries = await api.getCountries();
const country = countries.find(c => c.iso2 === 'US');
console.log('Country found:', country);

// Then check states
const states = await api.getStates('US');
console.log('States count:', states.length);

// Instead of sequential requests
const countries = await api.getCountries();
const states = await api.getStates('US');

// Use parallel requests
const [countries, states] = await Promise.all([
  api.getCountries(),
  api.getStates('US')
]);

// Add request debugging
console.log('Request URL:', fullUrl);
console.log('Request headers:', headers);
console.log('Response status:', response.status);
console.log('Response headers:', [...response.headers.entries()]);

// Add cache-busting parameter for testing
const url = `${baseUrl}?_t=${Date.now()}`;

curl -X GET 'https://api.countrystatecity.in/v1/countries' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY' \
  -w "HTTP Status: %{http_code}\n"

describe('Country State City API', () => {
  test('should fetch countries successfully', async () => {
    const countries = await api.getCountries();
    expect(countries).toBeInstanceOf(Array);
    expect(countries.length).toBeGreaterThan(0);
    expect(countries[0]).toHaveProperty('iso2');
  });

  test('should handle invalid country code', async () => {
    await expect(api.getStates('INVALID')).rejects.toThrow();
  });
});