country-state-city-langes

Fork of country-state-city, we part of the version 3 of this package, the available countries are LATAM + Spain and USA.

If you need all the world info use instead

https://github.com/harpreetkhalsagtbit/country-state-city

I translate to spanish Cuba information, and fix some data related to states and cities of this country.

I create this package to have all the features of filtering that the fork has. Also fix and translate cuba info avoiding slow to pull requests countries-states-cities-database.

I wish in the future to make contributions to countries-states-cities-database and improve size json of country-state-city. harpreetkhalsagtbit has made an excellent work!!!

All the credit are for countries-states-cities-database and country-state-city. Thanks.

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-langes

Documentation

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 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

Compatible with release : v3.0.0 of country-state-city (This examples are the same of the original repository)

• 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())
  

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

[@harpreetkhalsagtbit] https://github.com/harpreetkhalsagtbit/country-state-city

@baywet - For mentoring Javascript to Typescript Conversion

@dr5hn - For updated World Data Dictionary

taylorthurlow - For pointing into right direction - Module Tree Shaking