🇧🇷 brazil-cities

A lightweight TypeScript/JavaScript utility for handling Brazilian states and cities with simple, typed access. Includes fast lookup, filtering, sorting, grouping, and analytics functions.

📦 Installation

Using npm:

npm install brazil-cities

Using yarn:

yarn add brazil-cities

Using pnpm:

pnpm add brazil-cities

🧩 Basic Usage

import { State, City, utils } from "brazil-cities";

// Find a state by abbreviation
const sp = utils.findStateByAbbr("SP");
console.log(sp?.name); // "São Paulo"

// Find a state by name
const rj = utils.findStateByName("Rio de Janeiro");

// Get all states
const allStates = utils.getAllStates();

// Find a city by name
const campinas = utils.findCityByName("Campinas");

// Filter cities by prefix across all states
const citiesWithSan = utils.filterCitiesByPrefix("San");

// Filter cities within a specific state by prefix
const citiesInSP = utils.filterCitiesInStateByPrefix(sp!, "Camp");

// Filter cities by substring ignoring accents
const citiesNormalized = utils.filterCitiesByNormalizedSubstring("sao");

// Filter cities by suffix
const citiesWithSuffix = utils.filterCitiesBySuffix("ópolis");

// Filter cities by word count
const twoWordCities = utils.filterCitiesByWordCount(2);

// Filter cities using regex
const citiesMatchingRegex = utils.filterCitiesByRegex(/^S/);

// Filter cities by state abbreviation
const citiesInState = utils.filterCitiesByStateAbbr("SP");

// Filter cities by ID range
const citiesInIdRange = utils.filterCitiesByIdRange(5300108, 5301000);

// Get states sorted alphabetically
const sortedStates = utils.getStatesSortedByName();

// Get cities sorted alphabetically
const sortedCities = utils.getCitiesSortedByName();

// Group cities alphabetically
const citiesGroupedByLetter = utils.groupCitiesByInitialLetter();

// Group cities by state
const citiesGroupedByState = utils.groupCitiesByState();

// Get top states by city count
const topStates = utils.getMostPopulatedStatesByCityCount(5);

// Get city name statistics
const stats = utils.getCityNameStats();
console.log(stats.total, stats.avgLength, stats.maxLength, stats.minLength);

🗺️ Data Structures

State

interface State {
  name: string; // e.g. "São Paulo"
  abbr: string; // e.g. "SP"
  cities: City[]; // List of cities in that state
}

City

interface City {
  id: number; // e.g. 3509502
  name: string; // e.g. "Campinas"
  stateAbbr: string; // e.g. "SP"
  stateName: string; // e.g. "São Paulo"
}

⚙️ API Reference

| Function | Description | Returns | | -------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------- | | findStateByAbbr(abbr) | Finds a state by its abbreviation | State \| undefined | | findStateByName(name) | Finds a state by its full name | State \| undefined | | getAllStates() | Returns all states | State[] | | getAllStateAbbrs() | Returns all state abbreviations | string[] | | getAllStateNames() | Returns all state names | string[] | | getStatesWithoutCities() | Returns states without city lists | Omit<State, "cities">[] | | getStatesWithCities() | Returns states with their cities | State[] | | findCityByName(name) | Finds a city by its name | City \| undefined | | getAllCities() | Returns all cities in Brazil | City[] | | getCitiesFromState(identifier) | Returns all cities from a given state | City[] | | filterCitiesByPrefix(prefix) | Filters all cities starting with a given prefix | City[] | | filterCitiesInStateByPrefix(state, prefix) | Filters cities within a given state by prefix | City[] | | filterCitiesByInitialLetter(letter) | Filters cities by their first letter | City[] | | filterCitiesBySubstring(substring) | Filters cities containing a substring | City[] | | filterCitiesByNormalizedSubstring(substring) | Filters cities containing a substring ignoring accents | City[] | | filterCitiesBySuffix(suffix) | Filters cities ending with a specific suffix | City[] | | filterCitiesByWordCount(count) | Filters cities by number of words in their name | City[] | | filterCitiesByRegex(pattern) | Filters cities matching a regular expression | City[] | | filterCitiesByStateAbbr(abbr) | Filters cities from a specific state | City[] | | filterCitiesByIdRange(minId, maxId?) | Filters cities by ID range | City[] | | filterCitiesInStateBySubstring(state, substring) | Filters cities within a given state by substring | City[] | | getStatesSortedByName() | Returns all states sorted alphabetically | State[] | | getCitiesSortedByName() | Returns all cities sorted alphabetically | City[] | | getCitiesSortedByNameLength() | Returns all cities sorted by name length | City[] | | groupCitiesByInitialLetter() | Groups cities alphabetically by first letter | Record<string, City[]> | | groupCitiesByState() | Groups cities by state abbreviation | Record<string, City[]> | | getMostPopulatedStatesByCityCount(limit) | Returns top states by number of cities | State[] | | getCityNameStats() | Returns statistics about city names | { total, avgLength, maxLength, minLength } |

🧠 TypeScript Support

Fully written in TypeScript, with clear type exports and all utility functions accessible via utils:

import { State, City, utils } from "brazil-cities";

// Example usage:
const sp: State | undefined = utils.findStateByAbbr("SP");
const campinas: City | undefined = utils.findCityByName("Campinas");

All types (State, City) and functions (utils) are fully typed for autocomplete and safety.

🪶 License

MIT © 2025 — brazil-cities