Question 1

What does CountryStateCity do?

Accepted Answer

CountryStateCity is a free, open-source geographic reference database exposed as a REST API, providing structured data for all 250 countries in the world, their states and provinces, and their cities and local government areas. For Nigerian developers, it is particularly valuable because it includes all 36 Nigerian states plus the Federal Capital Territory (FCT), all 774 Local Government Areas (LGAs), and major Nigerian cities — providing the authoritative administrative geography of Nigeria in a machine-readable format.

**What CountryStateCity Does**

CountryStateCity exposes a hierarchical geographic database through a simple RESTful API. The three levels of the hierarchy are:

1. **Countries**: 250 countries with ISO2 code, ISO3 code, phone code, currency, flag emoji, region (continent), and subregion. Example: Nigeria → ISO2: NG, ISO3: NGA, phone: 234, currency: NGN.

2. **States**: All states, provinces, regions, and administrative divisions within each country, with their ISO code, state code, latitude, longitude, and type (State, Province, Region, Territory, etc.).

3. **Cities**: All cities and towns within each state, with latitude and longitude coordinates.

For Nigeria specifically:
- **36 states + FCT**: Abia, Adamawa, Akwa Ibom, Anambra, Bauchi, Bayelsa, Benue, Borno, Cross River, Delta, Ebonyi, Edo, Ekiti, Enugu, FCT Abuja, Gombe, Imo, Jigawa, Kaduna, Kano, Katsina, Kebbi, Kogi, Kwara, Lagos, Nasarawa, Niger, Ogun, Ondo, Osun, Oyo, Plateau, Rivers, Sokoto, Taraba, Yobe, Zamfara
- **774 LGAs**: All Local Government Areas of Nigeria, enabling granular administrative-level targeting
- **Major cities**: Lagos, Abuja, Kano, Ibadan, Port Harcourt, Benin City, and hundreds of secondary cities and towns

**How Developers Use CountryStateCity**

**Option 1: REST API**

After registering for a free API key at countrystatecity.in, you make GET requests with the key in the header:

```
GET https://api.countrystatecity.in/v1/countries/NG/states
Headers: X-CSCAPI-KEY: YOUR_KEY
```

This returns all Nigerian states as a JSON array. To get LGAs for a specific state:

```
GET https://api.countrystatecity.in/v1/countries/NG/states/LA/cities
Headers: X-CSCAPI-KEY: YOUR_KEY
```

Returns all cities in Lagos State.

**Option 2: npm Package (No API Call Required)**

CountryStateCity is also available as an npm package (`csc-js`) that bundles the entire database locally:

```
npm install country-state-city
```

```javascript
import { Country, State, City } from 'country-state-city';
const nigerianStates = State.getStatesOfCountry('NG');
const lagosCities = City.getCitiesOfState('NG', 'LA');
```

This approach is fully offline — no API key, no rate limits, no network calls. The data is bundled with your application. This is ideal for forms and dropdowns where you need instant local lookup without network latency.

**Pricing and Rate Limits**

- **Free API Plan**: 100 requests per hour with an API key. Suitable for moderate production use; cache responses on the client side to stay within limits.
- **npm Package**: Completely free, no limits, no API key. The entire database is included in the package (~1-2MB).
- **No Credit Card Required**: The free plan is free forever with no payment required.

For most Nigerian applications that use the data for dropdown population (which loads once and caches), the free API tier or the npm package will be more than sufficient.

**Authentication**

API authentication uses a custom header: `X-CSCAPI-KEY: YOUR_KEY`. Unlike many APIs that use query parameter authentication, CountryStateCity uses headers for cleaner URLs. The npm package requires no authentication at all.

**Data Quality and Coverage**

CountryStateCity is an open-source project actively maintained on GitHub. The Nigerian data is comprehensive:

- All 36 states are present with correct ISO codes
- FCT (Federal Capital Territory) is correctly listed separately
- All 774 LGAs are catalogued as cities within their respective states
- Major Nigerian cities include coordinates for mapping use

Accuracy is generally high for administrative boundaries. However, as with any community-maintained dataset, there may be occasional discrepancies in transliterations of local place names or boundary changes following administrative reorganizations.

**Use Case: Nigeria Registration Form**

A common challenge in Nigerian SaaS applications is building registration forms with valid state and LGA dropdowns. Hard-coding these lists creates maintenance overhead (LGA boundaries sometimes change), and asking users to type free-text creates data quality issues. CountryStateCity solves this cleanly:

1. On page load, fetch all Nigerian states from CountryStateCity
2. Populate the "State" dropdown
3. When the user selects a state, fetch the LGAs for that state
4. Populate the "LGA" dropdown dynamically

This creates a clean, validated, always-up-to-date address form without any custom data management.

**Use Case: Multi-Country International Forms**

For Nigerian platforms expanding internationally or serving the diaspora, CountryStateCity eliminates the need to maintain custom country/state/city lists for every market. A single integration covers all 250 countries, making international checkout forms, shipping address forms, and user registration forms easy to build and maintain.

**Use Case: Analytics and Reporting**

Nigerian businesses with location-based data (field sales tracking, delivery routing, customer distribution mapping) can use CountryStateCity's standardized state and LGA codes to normalize location data collected from multiple sources, enabling clean aggregation and reporting by administrative region.

**Compliance Considerations**

CountryStateCity returns administrative boundary data — countries, states, cities. This data itself is not personal information and does not raise NDPR or GDPR compliance concerns. When used in conjunction with user location data (i.e., storing which LGA a specific user is in), standard data minimization principles apply.

**Company Background**

CountryStateCity is an open-source project started by developer Darshan Gada and maintained on GitHub with contributions from developers worldwide. It has accumulated thousands of GitHub stars and is widely used in the developer community. The npm package has millions of weekly downloads, making it one of the most trusted geographic reference datasets available as a developer tool. The REST API wrapper is provided as an additional convenience for non-JavaScript environments.

**Alternatives**

- **REST Countries API**: Countries only (no states/cities)
- **GeoNames**: More comprehensive but complex and requires attribution
- **Google Places API**: Real-time and accurate but paid and requires Google billing
- **OpenStreetMap / Nominatim**: Best for geocoding but overkill for simple dropdown population

CountryStateCity strikes the ideal balance of simplicity, completeness, and zero cost — making it the default choice for Nigerian developers building any form that requires country/state/LGA selection.

Question 2

How much does CountryStateCity cost?

Accepted Answer

CountryStateCity is free to start, with paid tiers for higher usage (freemium). Free plan: 100 requests/hour with API key. Free npm/composer packages available for offline use. No credit card required.

Question 3

How do I authenticate with the CountryStateCity API?

Accepted Answer

API Key (Header: X-CSCAPI-KEY)

Question 4

Is there a rate limit on CountryStateCity?

Accepted Answer

100 requests/hour on free plan.

Question 5

Does CountryStateCity offer a sandbox or test mode?

Accepted Answer

Yes — CountryStateCity provides a sandbox or test environment so you can integrate and test before going live.

Question 6

What is CountryStateCity best suited for?

Accepted Answer

Developers building registration forms, address pickers, and location dropdowns who need a structured global database of all countries, states/provinces, and cities — with full Nigerian states and LGA data included.

Question 7

Is there anything else I should know before integrating CountryStateCity?

Accepted Answer

CountryStateCity provides a fully structured JSON database of all 250 countries, their states/regions, and cities. Nigeria's 36 states + FCT and all 774 LGAs are included. Also available as a free npm package for offline/bundled use.

Question 8

Where can I find CountryStateCity's documentation?

Accepted Answer

The official API documentation is at https://countrystatecity.in/docs/api/countries/. The provider's website is https://countrystatecity.in.

Question 9

Does CountryStateCity support Nigerian developers?

Accepted Answer

Yes — CountryStateCity explicitly supports Nigerian developers/use cases.

CountryStateCity

Features Included

Not Supported

Key Highlights

Required Access Documents

Use Cases

Ask question or give feedback

Sign in to participate

Discover similar API's

Ask question or give feedback

Sign in to participate