{"_id":"@br-geo-kit/ibge","name":"@br-geo-kit/ibge","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@br-geo-kit/ibge","version":"1.0.0","description":"Brazilian states, municipalities, IBGE codes, area codes and CEP ranges as a typed offline dataset","license":"MIT","engines":{"node":">=20"},"type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./web":{"types":"./dist/web.d.ts","import":"./dist/web.js","require":"./dist/web.cjs"},"./data/*":"./data/*"},"dependencies":{"@br-geo-kit/core":"1.0.0"},"publishConfig":{"access":"public"},"keywords":["ibge","municipios","estados","ddd","cep","brasil","br-geo-kit"],"repository":{"type":"git","url":"git+https://github.com/arielff3/br-geo-kit.git","directory":"packages/ibge"},"homepage":"https://github.com/arielff3/br-geo-kit/tree/main/packages/ibge#readme","bugs":{"url":"https://github.com/arielff3/br-geo-kit/issues"},"scripts":{"build":"tsup","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""},"_id":"@br-geo-kit/ibge@1.0.0","_integrity":"sha512-U611XJ7x43AeWoD6TZbfUBfLQdSP4uNOIJzlRrHS2Dp+ViLUUB7N6bKf43/FmRsZPJXx8JaDRGtqZXmOGeeI/Q==","_resolved":"C:\\Users\\ariel\\AppData\\Local\\Temp\\c8aa7077f37068c7d9fdc022aa7d8911\\br-geo-kit-ibge-1.0.0.tgz","_from":"file:br-geo-kit-ibge-1.0.0.tgz","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-U611XJ7x43AeWoD6TZbfUBfLQdSP4uNOIJzlRrHS2Dp+ViLUUB7N6bKf43/FmRsZPJXx8JaDRGtqZXmOGeeI/Q==","shasum":"82495e152036d6bdfbe60c08d12913449b541f2c","tarball":"https://registry.npmjs.org/@br-geo-kit/ibge/-/ibge-1.0.0.tgz","fileCount":26,"unpackedSize":862769,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBrwn/fanUMT9+8LlGOmTOd9ab+GQZ8CgzzY4MXGtl0UAiEAycVYvrbSOelA6QUEGHrVj2PlkLXJoS81XfuORK+BDoE="}]},"_npmUser":{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"},"directories":{},"maintainers":[{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ibge_1.0.0_1789134618214_0.027788710713796405"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-11T13:50:18.045Z","1.0.0":"2026-09-11T13:50:18.381Z","modified":"2026-09-11T13:50:18.588Z"},"maintainers":[{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"}],"description":"Brazilian states, municipalities, IBGE codes, area codes and CEP ranges as a typed offline dataset","homepage":"https://github.com/arielff3/br-geo-kit/tree/main/packages/ibge#readme","keywords":["ibge","municipios","estados","ddd","cep","brasil","br-geo-kit"],"repository":{"type":"git","url":"git+https://github.com/arielff3/br-geo-kit.git","directory":"packages/ibge"},"bugs":{"url":"https://github.com/arielff3/br-geo-kit/issues"},"license":"MIT","readme":"# @br-geo-kit/ibge\n\n> Brazilian states, municipalities, IBGE codes, geographic regions, area\n> codes and CEP blocks — offline, versioned, and traceable to the source.\n\n```bash\npnpm add @br-geo-kit/ibge\n```\n\n```ts\nimport { ibge } from '@br-geo-kit/ibge'\n\nibge.municipalities('SP')        // 645 records, for a dropdown\nibge.municipality('3550308')     // { name: 'São Paulo', ddd: '11', ... }\nibge.search('santa rita', { uf: 'PB' })\nibge.stateOfCep('01310-100')     // 'SP' — a range lookup, not a request\nibge.stateOfDdd('11')            // 'SP'\nibge.capitalOf('TO')             // Palmas\n```\n\nNo network, no API key, no rate limit. Most of what applications call\nthe IBGE's API for at runtime is a table that changes about once a\ndecade.\n\n---\n\n## What is in it\n\n| Table | Records |\n| --- | --- |\n| States | 27 |\n| Municipalities | 5 571 |\n| Geographic regions (immediate + intermediate) | 643 |\n| Area codes | 67 |\n| CEP blocks | 30 |\n\nGenerated by a pipeline that downloads from the IBGE's Localidades API,\nvalidates, and emits deterministic JSON. Every version carries its\nsource, its checksums, and what it does *not* know.\n\n---\n\n## Three levels of \"is this CEP valid\", each cheaper than the next\n\n```ts\nisWellFormedCep('01310100')      // shape only. No data, no I/O.\nibge.isCepPlausible('01310100')  // falls in a block allocated to a state\nawait cep.lookup('01310100')     // exists, and here it is\n```\n\n`stateOfCep` is a binary search over 30 ranges. It rejects a CEP in an\nunallocated block before you spend a request on it, and it tells a form\nwhich state to preselect while the lookup is still in flight.\n\nTwo blocks belong to nobody: everything below `01000-000`, and the whole\nof `789xxxxx` — Rondônia's original block, vacated when the state was\nrenumbered into 768–769.\n\nIt is a *range* lookup, not an existence check. `19999999` is inside São\nPaulo's block and is assigned to nobody.\n\n---\n\n## What it admits it does not know\n\n**136 of 5 571 municipalities have no area code** — 97.56% covered.\n\nThe IBGE does not publish area codes; they are joined by exact\nnormalized name within a state. The misses are almost all municipalities\nrenamed since the source list was compiled. A nearest-name match would\nfill most of them and would occasionally be wrong, silently, on a field\napplications use to build phone numbers.\n\n```ts\nibge.metadata.coverage['municipalities.ddd']   // 136\n```\n\n**Three states have no single time zone.** AM, PA and PE each span two,\nand resolving which side a municipality falls on needs geometry this\ndataset does not carry.\n\n```ts\nibge.timezoneOf('SP')    // 'America/Sao_Paulo'\nibge.timezoneOf('PE')    // null\nibge.timezonesOf('PE')   // ['America/Recife', 'America/Noronha']\n```\n\nDeclaring a gap is the point. A dataset that quietly ships one is\nindistinguishable from a complete one, until somebody's form breaks.\n\n---\n\n## Provenance\n\n```ts\nibge.metadata.version         // '2026'\nibge.metadata.source          // 'IBGE — API de Localidades; ...'\nibge.metadata.dataChecksum    // reproducible across runs\n```\n\nPin a version when reproducibility matters:\n\n```ts\nconst dataset = ibge.load('2026')\n```\n\nAsking for a version the installed package does not ship **throws**\nrather than falling back to the newest.\n\n---\n\n## In a browser\n\nThe default entry reads from disk and is Node-only. In a browser, supply\nthe data yourself:\n\n```ts\nimport { createIbge, IBGE_TABLE_NAMES } from '@br-geo-kit/ibge/web'\n\nconst ibge = createIbge({ metadata, tables })\n```\n\nThe whole dataset is 730 KB raw, about 80 KB gzipped, and the raw files\nare published under `@br-geo-kit/ibge/data/*` so a build step can put\nthem on your CDN. The same validation and freezing run on both paths.\n\nSee [browser and React](https://github.com/arielff3/br-geo-kit/blob/main/docs/browser.md).\n\n---\n\n## Frozen\n\nEvery table is deep-frozen on load. The dataset is a process-wide\nsingleton, so without it one consumer calling `.sort()` corrupts it for\nevery other. To sort, copy first:\n\n```ts\nconst ordered = [...ibge.municipalities('SP')].sort(byName)\n```\n\n---\n\n## Licence\n\nMIT for the code.\n\nThe territorial data comes from the **IBGE**, a Brazilian federal\nagency, and is public; it is redistributed here unmodified in content\nand with attribution on every dataset version. The IBGE publishes no\nSPDX licence identifier for this endpoint, so this package does not\nassert one — if your compliance process needs a definite answer, get it\nfrom the IBGE.\n\nArea codes are joined from [BrasilAPI](https://github.com/BrasilAPI/BrasilAPI)\n(MIT). The CEP block allocation is transcribed from the Correios'\npublished Guia Postal; the DNE street database itself is **not**\nredistributed.\n\nFull provenance, and what is and is not verified, in\n[docs/licensing.md](https://github.com/arielff3/br-geo-kit/blob/main/docs/licensing.md).\n","readmeFilename":"README.md","_rev":"1-3445ebf25ca60870ff59473c0420378c"}