CountryStateCity API – Location Data for Web Forms & E-commerce

Overview

The CountryStateCity API provides a structured dataset for geographical locations, specifically focusing on countries, their constituent states or provinces, and the cities within those administrative divisions. This API is engineered to assist developers in implementing location-based features within web and mobile applications where precise hierarchical geographic selection is required. Common applications include dynamic dropdown menus for address input in e-commerce platforms, filtering user data by region, or populating forms that require a user's country, state, and city.

The service offers both a RESTful API for real-time data retrieval and a downloadable database for scenarios requiring offline access or bulk processing. The API's design prioritizes ease of integration, with clear documentation and code examples provided in multiple programming languages, including JavaScript, PHP, and Python. This makes it suitable for developers looking to quickly incorporate geo-selection functionalities without extensive setup. While it provides detailed country, state, and city information, it does not offer full address geocoding or reverse geocoding capabilities, focusing instead on the hierarchical structure of these three geographical levels.

For developers building applications that require users to specify their location from a predefined, structured list, CountryStateCity can streamline the user experience and data collection process. Its utility extends across various sectors, from online retail and logistics to social networking and government services, where accurate and consistent location data is fundamental. The API's free tier allows for initial development and testing, while paid plans scale to accommodate higher request volumes, making it accessible for projects of different sizes. Compliance with GDPR is also noted, addressing data privacy considerations for users within the European Union.

Key features

• Hierarchical Location Data: Provides structured data for countries, states/provinces, and cities, allowing for cascading selection in user interfaces.
• Global Coverage: Offers a comprehensive dataset covering a large number of countries, states, and cities worldwide.
• RESTful API: Access data programmatically via standard HTTP requests, returning JSON responses for easy parsing.
• Downloadable Database: Provides an alternative for applications requiring offline access to the location dataset or for bulk operations.
• Developer-Friendly Documentation: Includes code examples in JavaScript, PHP, Python, and cURL to facilitate quick integration (CountryStateCity documentation).
• GDPR Compliance: Adheres to General Data Protection Regulation standards for data handling and privacy.
• Filtering and Search: Allows for filtering based on parent entities (e.g., get states for a specific country, cities for a specific state).

Pricing

CountryStateCity offers a free tier for initial development and testing, with paid plans scaling based on the number of requests per day. The following table summarizes the pricing as of May 2026:

For detailed and up-to-date pricing information, refer to the official CountryStateCity pricing page.

Common integrations

The CountryStateCity API is commonly integrated into systems that require structured geographical selection. Its primary use cases involve enhancing user input forms and refining data collection processes.

• Web Forms with Location Selection: Developers frequently integrate the API into registration forms, profile settings, or contact forms where users need to select their country, state, and city from dynamic dropdowns. This improves data accuracy and user experience by providing validated options.
• E-commerce Shipping Address Input: Online stores utilize the API to pre-populate and validate shipping and billing addresses, ensuring that customers select valid geographical locations. This can reduce delivery errors and improve checkout flows.
• User Profiling by Location: Applications that build user profiles or segment audiences based on geographical data can use the API to standardize and enrich location information. This supports targeted content delivery, analytics, and regional service offerings.
• Data Visualization and Reporting: Business intelligence tools and dashboards can integrate the CountryStateCity dataset to display data aggregated by specific geographical regions, enhancing analytical capabilities.
• Content Management Systems (CMS): Platforms like WordPress or custom CMS solutions can use the API to manage region-specific content or services, allowing administrators to define availability based on country, state, or city.

Alternatives

Developers seeking similar geographical data services have several alternatives, each with distinct features and coverage:

• GeoDB Cities: Provides a comprehensive database of cities, including population, coordinates, and administrative data.
• Teleport Public API: Offers data on cities worldwide, focusing on quality of life metrics, cost of living, and urban infrastructure.
• Abstract API - Public APIs: A suite of micro-APIs, including a country, state, and city API, designed for ease of use and rapid integration.
• Google Maps Geocoding API: Offers advanced geocoding capabilities, converting addresses into geographic coordinates and vice-versa, with broader location context.
• Geolocation API (Browser): A client-side browser API that allows web applications to access the user's current location, often used for proximity-based services.

Getting started

To begin using the CountryStateCity API, you typically need to sign up for an API key and then make HTTP requests to its endpoints. Below is a JavaScript example demonstrating how to retrieve a list of countries.

async function fetchCountries() {
  const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key
  const url = 'https://api.countrystatecity.in/v1/countries';

  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'X-CSCAPI-KEY': apiKey,
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Countries:', data);
    // Example: log the name of the first country
    if (data.length > 0) {
      console.log('First country:', data[0].name);
    }

  } catch (error) {
    console.error('Error fetching countries:', error);
  }
}

fetchCountries();

This JavaScript code snippet demonstrates how to make an authenticated GET request to the /v1/countries endpoint. You would replace 'YOUR_API_KEY' with the key obtained after registering on the CountryStateCity website. The response will be a JSON array of country objects, each containing details like the country name, ISO code, and phone code. Similar requests can be made to fetch states within a country or cities within a state, by appending the respective IDs to the URL as described in the CountryStateCity API documentation.