Country-State-City API & SDK

Complete location data solution with cascading dropdowns and REST API

🚀 Key Features

Comprehensive Database

250+ countries, 4,000+ states, and 150,000+ cities with regular updates

Easy Integration

Simple SDK implementation with automatic dropdown population

REST API Access

Direct API endpoints for custom implementations

Lightweight SDK

Only 5KB minified with zero dependencies

Smart Caching

Built-in caching to reduce API calls and improve performance

Enterprise Ready

99.9% uptime with scalable infrastructure

📦 SDK Implementation

Quick Start

Add this script to your HTML (replace with your app_key):

<script src="https://cdn.api1.in/country-state-city/sdk.js?app_key=YOUR_APP_KEY"></script>
Note: The SDK will automatically initialize when the DOM is loaded if elements with default IDs are found.

Basic Usage

Create three dropdown elements with these default IDs:

<select id="country"></select>
<select id="state"></select>
<select id="city"></select>

🌐 Direct API Endpoints

All endpoints require your app_key as a query parameter:

Countries

GET https://api1.in/country-state-city/api/v1/countries?app_key=YOUR_APP_KEY

Example Response:

[
  {
    "id": 101,
    "name": "India",
    "iso2": "IN",
    "iso3": "IND",
    "phone_code": "91",
    "capital": "New Delhi"
  },
  {
    "id": 231,
    "name": "United States",
    "iso2": "US",
    "iso3": "USA",
    "phone_code": "1",
    "capital": "Washington, D.C."
  }
]

States by Country

GET https://api1.in/country-state-city/api/v1/states?country_id=101&app_key=YOUR_APP_KEY

Cities by State

GET https://api1.in/country-state-city/api/v1/cities-by-state?state_id=32&app_key=YOUR_APP_KEY

Cities by Country

GET https://api1.in/country-state-city/api/v1/cities-by-country?country_id=101&app_key=YOUR_APP_KEY
Important: Never expose your app_key in client-side production code. For production use, call these endpoints from your backend server.

🔧 Advanced Usage

Custom Element IDs

<select id="custom-country"></select>
<select id="custom-state"></select>
<select id="custom-city"></select>

<script>
  document.addEventListener('DOMContentLoaded', function() {
    CountryStateCitySDK.init({
      countryId: 'custom-country',
      stateId: 'custom-state',
      cityId: 'custom-city'
    });
  });
</script>

Event Callbacks

CountryStateCitySDK.init({
  onCountryChange: function(countryId) {
    console.log('Country changed:', countryId);
  },
  onStateChange: function(stateId) {
    console.log('State changed:', stateId);
  },
  onCityChange: function(cityId) {
    console.log('City changed:', cityId);
  }
});

Manual Refresh

// Refresh all data
CountryStateCitySDK.refresh();

// Refresh with specific country preselected
CountryStateCitySDK.refresh('101');

📚 API Reference

SDK Methods

Method Description Parameters
init(options) Initialize with custom options countryId, stateId, cityId,
onCountryChange, onStateChange, onCityChange
refresh(countryId) Reload all data countryId (optional)
version Current SDK version None

Response Codes

Code Description
200 Success
400 Invalid request
401 Unauthorized (invalid app_key)
404 Not found
429 Rate limit exceeded

❓ Frequently Asked Questions

How accurate is the location data?

Our database is updated monthly with the latest geopolitical changes. Accuracy levels:

What's the rate limit?

Standard plans include:

Can I use this in mobile apps?

Yes! The SDK works in web views, or you can call the API directly from native code.

How do I get support?

Email support@api1.in for technical assistance.