Countrywise City

A TypeScript library for countries, country flags, states, provinces, cities, ISO codes, currencies and geographic search.

Features

• 250+ countries
• 5,000+ states and regions
• 150,000+ cities
• Country flag emojis
• ISO2 and ISO3 codes
• Currency and phone information
• Latitude and longitude
• Country, state and city search
• TypeScript support
• ESM and CommonJS support

Installation

npm install countrywise-city

Replace the GitHub and author metadata in package.json with your real repository details before publishing.

Usage

import {
  countryCodeToFlag,
  getCitiesOfState,
  getCountries,
  getCountryByCode,
  getStatesOfCountry,
  searchCountries,
} from "countrywise-city";

const countries = await getCountries();
const bangladesh = await getCountryByCode("BD");
const states = await getStatesOfCountry("BD");
const cities = await getCitiesOfState("US", "CA");
const searchResults = await searchCountries("bangla");

console.log(countries.length);
console.log(bangladesh);
console.log(states);
console.log(cities);
console.log(searchResults);
console.log(countryCodeToFlag("BD"));

API

Country functions

• getCountries()
• getCountryByCode(countryCode)
• getCountryWithStates(countryCode)
• getFullCountryData(countryCode)

State functions

• getStatesOfCountry(countryCode)
• getStateByCode(countryCode, stateCode)
• getStateWithCities(countryCode, stateCode)

City functions

• getCitiesOfState(countryCode, stateCode)

Search functions

• searchCountries(query, options)
• searchStates(countryCode, query, options)
• searchCities(countryCode, stateCode, query, options)

Search options:

interface LocationSearchOptions {
  limit?: number;
  caseSensitive?: boolean;
  exact?: boolean;
}

Flag functions

• countryCodeToFlag(iso2)
• safeCountryCodeToFlag(iso2)

CommonJS

const {
  getCountries,
  getStatesOfCountry,
  getCitiesOfState,
} = require("countrywise-city");

async function main() {
  const countries = await getCountries();
  console.log(countries);
}

main();

Development

npm install
npm run typecheck
npm test
npm run build

Run all checks:

npm run check

Publishing

Before publishing, update these fields in package.json and this README:

• name
• author
• homepage
• repository
• bugs

Then verify:

npm run check
npm pack --dry-run
npm publish --access public

Data Attribution

Geographic data is provided through the CountryStateCity project:

• https://github.com/dr5hn/countries-states-cities-database
• https://github.com/dr5hn/countrystatecity-npm

The geographic data is licensed under ODbL 1.0.

License

ODbL-1.0