{"_id":"@br-geo-kit/provider-viacep","name":"@br-geo-kit/provider-viacep","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@br-geo-kit/provider-viacep","version":"1.0.0","description":"ViaCEP provider for br-geo-kit, with reverse lookup","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"}},"dependencies":{"@br-geo-kit/core":"1.0.0"},"publishConfig":{"access":"public"},"keywords":["viacep","cep","endereco","brasil","br-geo-kit"],"repository":{"type":"git","url":"git+https://github.com/arielff3/br-geo-kit.git","directory":"providers/viacep"},"homepage":"https://github.com/arielff3/br-geo-kit/tree/main/providers/viacep#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/provider-viacep@1.0.0","_integrity":"sha512-ELizbYeesyx4DjvpMiUfOGw8BeweuORXgB1m9jxdO1Sp9oUJGE+9cZVDr5pvOl6q7JRfzMP/YirFBzd6jNWErg==","_resolved":"C:\\Users\\ariel\\AppData\\Local\\Temp\\9610b844611105abf70ede11c0979104\\br-geo-kit-provider-viacep-1.0.0.tgz","_from":"file:br-geo-kit-provider-viacep-1.0.0.tgz","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-ELizbYeesyx4DjvpMiUfOGw8BeweuORXgB1m9jxdO1Sp9oUJGE+9cZVDr5pvOl6q7JRfzMP/YirFBzd6jNWErg==","shasum":"85d6ee5e3f613ae563168efb1f0ad37f06834f28","tarball":"https://registry.npmjs.org/@br-geo-kit/provider-viacep/-/provider-viacep-1.0.0.tgz","fileCount":10,"unpackedSize":31419,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICp5tEAjSeDlK7AnpHxJOni7n6Ad1aukAAKGb22K4WncAiEAi3QKikKDm6MlrZwV81od8+RPCMV35sILy4WNnJNgAzU="}]},"_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/provider-viacep_1.0.0_1789134627431_0.08308347189528908"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-11T13:50:27.323Z","1.0.0":"2026-09-11T13:50:27.556Z","modified":"2026-09-11T13:50:27.805Z"},"maintainers":[{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"}],"description":"ViaCEP provider for br-geo-kit, with reverse lookup","homepage":"https://github.com/arielff3/br-geo-kit/tree/main/providers/viacep#readme","keywords":["viacep","cep","endereco","brasil","br-geo-kit"],"repository":{"type":"git","url":"git+https://github.com/arielff3/br-geo-kit.git","directory":"providers/viacep"},"bugs":{"url":"https://github.com/arielff3/br-geo-kit/issues"},"license":"MIT","readme":"# @br-geo-kit/provider-viacep\n\n> ViaCEP for br-geo-kit. The only public service with a reverse lookup.\n\n```bash\npnpm add @br-geo-kit/cep @br-geo-kit/provider-viacep\n```\n\n```ts\nimport { createCep } from '@br-geo-kit/cep'\nimport { viacep } from '@br-geo-kit/provider-viacep'\n\nconst cep = createCep({ providers: [viacep()] })\nawait cep.lookup('01310-100')\n```\n\n---\n\n## What it returns\n\n| | |\n| --- | --- |\n| Street, neighbourhood, city, state | yes |\n| Correios side-of-street note (`complemento`) | **yes** — one of only two |\n| IBGE code | yes |\n| Area code | yes |\n| Coordinates | no |\n| Time zone | no |\n| Reverse lookup | **yes** — the only public service that has it |\n\n---\n\n## The trap this adapter closes\n\nViaCEP answers a CEP that does not exist with **HTTP 200** and a body of\n`{\"erro\": \"true\"}`. An integration that checks `response.ok` and parses\nthe body into its form gets an object whose every field is `undefined`,\nand shows the user a blank form with no error.\n\nWorse: when ViaCEP is rate-limiting it answers **HTTP 200 with an HTML\npage**. The same integration reads that as a successful lookup too.\n\nThis adapter reads the first as `null` — the CEP does not exist — and\n**throws** on the second, so the resolver falls through to the next\nprovider instead of telling the user their address is invalid.\n\nIt also turns ViaCEP's empty strings back into `null`. ViaCEP writes\n`\"\"` and never `null`, and a *CEP único* covering a whole small\nmunicipality legitimately has no street. `\"\"` and \"the source is\nsilent\" are different facts.\n\n---\n\n## Reverse lookup\n\n```ts\nawait cep.reverse({ state: 'SP', city: 'São Paulo', street: 'Paulista' })\n```\n\nViaCEP requires at least three characters in the city and the street and\nanswers 400 otherwise; the adapter returns `[]` for a shorter query\nrather than letting a predictable 400 abort the chain. A search with no\nmatch answers `[]`; a malformed one answers `{\"erro\": \"true\"}`, which is\nnot an array, and is also read as no match.\n\n---\n\n## Options\n\n```ts\nviacep({ baseUrl: 'https://my-proxy.example/ws' })\n```\n\n## Rate limits\n\nViaCEP publishes no documented rate limit and no SLA. Use a cache, and\nput a second provider behind it. See\n[caching](https://github.com/arielff3/br-geo-kit/blob/main/docs/caching.md)\nand [providers](https://github.com/arielff3/br-geo-kit/blob/main/docs/providers.md).\n\n## Licence\n\nMIT.\n\nThis package is an API client and redistributes no data. It is not\naffiliated with, endorsed by, or sponsored by ViaCEP; the name\nidentifies the service it connects to. ViaCEP has its own terms of\nuse, and calling it is your relationship with them.\n","readmeFilename":"README.md","_rev":"1-76498a5e3c0a571c7426dff6d58f5859"}