1# city-state-country-please
2
3A blazing-fast JavaScript utility for city, state, and country lookups—**autocomplete, fuzzy search, typo correction, and more**—all from a local dataset.  
4Perfect for forms, apps, and location-based features in Node.js or the browser.
5
6---
7
8## 🚀 Installation
9
10```bash
11npm install city-state-country-please

---

🏁 Quick Start

1const {
2  findByCity,
3  findCitiesByState,
4  findCitiesByCountry,
5  findCitiesByStateCountry,
6  fuzzyFindCities,
7  autocompleteCities,
8  typoFuzzyFindCities,
9  getStatesByCountry,
10  getAllCountries,
11  autocompleteStates,
12  fuzzyFindStates,
13  getAllCities,
14  cities,
15} = require('city-state-country-please');
16
17console.log(findByCity('Chicago'));
18// [{ city: 'Chicago', state: 'Illinois', country: 'United States' }]
19
20console.log(findCitiesByState('California'));
21// [ ...all cities in California ]
22
23console.log(fuzzyFindCities('angel'));
24// [ { city: 'Los Angeles', ... } ]
25
26console.log(autocompleteCities('San'));
27// [ { city: 'San Diego', ... }, { city: 'San Francisco', ... }, ... ]
28
29console.log(typoFuzzyFindCities('Huston'));
30// [ { city: 'Houston', ... } ]
31
32console.log(getStatesByCountry('United States'));
33// [ 'California', 'Texas', ... ]
34
35console.log(getAllCountries());
36// [ 'United States' ]
37
38console.log(autocompleteStates('Ne', 'United States'));
39// [ 'Nebraska', 'Nevada', ... ]

---

📖 API Reference

Data

• cities: Full array of { city, state, country } objects.

Lookup Functions

• findByCity(city: string): Array

  All cities with exact name (case-insensitive).

• findCitiesByState(state: string): Array

  All cities in a state.

• findCitiesByCountry(country: string): Array

  All cities in a country.

• findCitiesByStateCountry(state: string, country: string): Array

  All cities matching state & country.

Autocomplete & Fuzzy Search

• autocompleteCities(prefix: string, [limit]): Array

  Cities starting with prefix.

• fuzzyFindCities(query: string, [limit]): Array

  Cities where name contains query.

• typoFuzzyFindCities(query: string, [maxDistance], [limit]): Array

  Cities with names typo-matching query (Levenshtein).

• autocompleteStates(prefix: string, country: string, [limit]): Array

  State names for a country starting with prefix.

• fuzzyFindStates(query: string, [limit]): Array

  State names containing query.

Other Utilities

• getStatesByCountry(country: string): Array

  All unique states in a country.

• getAllCountries(): Array

  List of all unique countries.

• getAllCities(): Array

  Returns the whole city list.

---

⚡️ Performance Tips

• For very large lookups or frequent fuzzy searches, consider pre-indexing or offloading to a database for production.
• Works great for autocomplete fields and quick lookups!

---

📝 License

MIT (c) 2025 [Asray Gopa]

---

🌎 Contributing

Pull requests and suggestions welcome! For feature requests or bug reports, open an issue.

---

⭐ Example

1const { autocompleteCities } = require('city-state-country-please');
2console.log(autocompleteCities('Denv'));
3// [ { city: 'Denver', state: 'Colorado', country: 'United States' } ]