npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

holema-country-state-city

v1.0.1

Published

Library for fetching Country, its States and Cities

Downloads

79

Readme

country-state-city

Basic library for Country, State and City

Data Source: https://github.com/dr5hn/countries-states-cities-database For any data related issue, you can also raise a Issue here.

Install

npm i country-state-city

Demos - Tree Shaking

  1. Next.js
  2. React.js

Release Info & Documentation

  1. Release v3.2.0
    1. To optimize bundle size, the data JSON files have undergone minification. For instance, the city.json file, which was originally around 25MB in an unminified state, has now been reduced to approximately 8MB through minification.
    2. The structure of the city.json file has been transformed from an Array of Objects to an Array of Arrays of Strings. Previously, the file contained duplicate property names for each object, resulting in a minified file size of 16MB due to JSON formatting requirements. To further minimize this, the file structure has been converted to an Array of Arrays, astonishingly reducing the size to 8MB.
    3. To accommodate this updated structure, modifications were made to the city.ts file. Importantly, these changes do not affect the functionality of existing code. All existing code will continue to work seamlessly without any breaking changes.
  2. Release v3.1.0
    1. Overview
    2. How to contribute to Country, State, City Database, request changes and report issue?
    3. How Data will be Released finally?
  3. Usage
    1. Release : v3.0.0 (Major Version Release - Not backward compatible)
    2. For versions below v2.2.0 and above v0.1.8
  4. Docs

Release : v3.1.0

Overview

  1. The data folder in the root contains all the data of Countries, their States and Cities
  2. The earlier large big JSONs are split into smaller JSONs and stored in separate files and folder
  3. The advantage of doing so is to make it easy to check, test and submit the change. It's easier to review a small file than a large file. It's easier to debug any missing or wrong values in a small file.
  4. This will help in future optimisation
  5. There is a separate folder for each country
    • Each Country folder contains Country's information and its states as sub-child folders
    • The Country's info is also split into - Country Lite, Plain, Geo, TimeZone's.
    • Inside each Country - there are Sub-folder of State
  6. Each State folder contains State's information and its Cities as sub-child files
  7. State's info is also split into - State Lite, Geo
  8. Inside each State - there are JSON files of City
    1. Each City file contains information of all the Cities of that particular State
    2. Cities info is split into two files - City Lite, Geo

How to contribute to Country, State, City Database, request changes and report issue?

  1. Code change - make the necessary change, raise the PR.
  2. Data changes - Database is in data folder in the root. Please follow this guidelines.
  3. Update: Add the necessary changes in the particular files with proper structure and format and then raise the PR.
  4. Add New - Country, State, City - follow the proper folder structure and raise the P.R or simply share the JSONs in an issue with proper and up to date reference.
  5. Deleting - Country, State, City - remove the necessary files/folder - update the necessary files and raise the PR or simply share the updated JSONs in an issue with a proper and up to date reference.
  6. Queries/Issues related to wrong data must be provided with some references.
  7. For any Geo-Political related queries, border conflicts - things will be updated when multiple proper references has been provided.

Data updation guide

Please follow this guidelines

How Data will be Released finally?

  1. After the changes gets merged, a script will be run to combine all the data in a separate but single file for each Country, State, City as we have earlier without affecting out library functions and only those three files are passed to the build code and then it gets released.
  2. In future we will be working on how to use these split files to optimise this library further.

Usage

Release : v3.0.0 (Major Version Release - Not backward compatible)

  • ES6 Module usage

    // Latest version - v3.0.0 with Tree Shaking to reduce bundle size
    import { Country, State, City }  from 'country-state-city';
    console.log(Country.getAllCountries())
    console.log(State.getAllStates())
    
    // Import Interfaces`
    import { ICountry, IState, ICity } from 'country-state-city'
        
  • AMD Module usage

    // Latest version - v3.0.0
    let Country = require('country-state-city').Country;
    let State = require('country-state-city').State;
    
    console.log(Country.getAllCountries())
    console.log(State.getAllStates())
    

For versions below v2.2.0 and above v0.1.8

  • ES6 Module usage

    import csc from 'country-state-city';
  • AMD Module usage

    let csc = require('country-state-city').default;

Docs

Country.getCountryByCode(countryCode)

It accepts a valid CountryCode eg: 'AS' and returns Country Details

type: json | ICountry

{
	"isoCode": "IN",
	"name": "India",
	"phonecode": "91",
	"flag": "🇮🇳",
	"currency": "INR",
	"latitude": "20.00000000",
	"longitude": "77.00000000",
	"timezones": [
		{
			"zoneName": "Asia\/Kolkata",
			"gmtOffset": 19800,
			"gmtOffsetName": "UTC+05:30",
			"abbreviation": "IST",
			"tzName": "Indian Standard Time"
		}
	]
}

State.getStateByCodeAndCountry(stateCode, countryCode)

It accepts a valid StateCode eg: 'TG' CountryCode eg: 'IN' and returns State Details

type: json | ICountry

{
	"name": "Telangana",
	"isoCode": "TG",
	"countryCode": "IN",
	"latitude": "18.11243720",
	"longitude": "79.01929970"
}

State.getStatesOfCountry(countryCode)

It accepts a valid CountryCode and returns all States as Array of JSON

type: array of json | IState

[
	{
		"name": "Delhi",
		"isoCode": "DL",
		"countryCode": "IN",
		"latitude": "28.70405920",
		"longitude": "77.10249020"
	}
]

City.getCitiesOfState(countryCode, stateCode)

It accepts a valid CountryCode, StateCode and returns all Cities as Array of JSON

type: array of json | ICity

[
	{
		"name": "New Delhi",
		"countryCode": "IN",
		"stateCode": "DL",
		"latitude": "28.63576000",
		"longitude": "77.22445000"
	}
]

City.getCitiesOfCountry(countryCode)

It accepts a valid CountryCode and returns all Cities as Array of JSON

type: array of json | ICity

[
	{
		"name": "New Delhi",
		"countryCode": "IN",
		"stateCode": "DL",
		"latitude": "28.63576000",
		"longitude": "77.22445000"
	}
]

Country.getAllCountries

It returns all Countries

type: array of json | ICountry

[
	{
		"isoCode": "IN",
		"name": "India",
		"phonecode": "91",
		"flag": "🇮🇳",
		"currency": "INR",
		"latitude": "20.00000000",
		"longitude": "77.00000000",
		"timezones": [
			{
				"zoneName": "Asia\/Kolkata",
				"gmtOffset": 19800,
				"gmtOffsetName": "UTC+05:30",
				"abbreviation": "IST",
				"tzName": "Indian Standard Time"
			}
		]
	}
]

State.getAllStates

It returns all States

type: array of json | IState

[
	{
		"name": "Delhi",
		"isoCode": "DL",
		"countryCode": "IN",
		"latitude": "28.70405920",
		"longitude": "77.10249020"

	}
]

City.getAllCities

It returns all Cities

type: array of json | ICity

[
	{
		"name": "Delhi",
		"isoCode": "DL",
		"countryCode": "IN",
		"latitude": "28.70405920",
		"longitude": "77.10249020"
	}
]

Special Thanks

@baywet - For mentoring Javascript to Typescript Conversion

@dr5hn - For updated World Data Dictionary

taylorthurlow - For pointing into right direction - Module Tree Shaking