@br-geo-kit/provider-awesomeapi

AwesomeAPI for br-geo-kit. The fullest single response of the free services.

pnpm add @br-geo-kit/cep @br-geo-kit/provider-awesomeapi

import { createCep } from '@br-geo-kit/cep'
import { awesomeapi } from '@br-geo-kit/provider-awesomeapi'

const cep = createCep({ providers: [awesomeapi()] })

What it returns

| | | | --- | --- | | Street, neighbourhood, city, state | yes | | Correios side-of-street note | no | | IBGE code | yes | | Area code | yes | | Coordinates | yes | | Reverse lookup | no |

It is the only free service that returns an area code and coordinates and an IBGE code in one call, which makes it a good chain leader when you want a complete record without the offline dataset.

It also splits the street into its type and its name. The kit uses the joined form and falls back to rebuilding it from the halves.

Its failure modes are the ordinary ones

AwesomeAPI is the only one of the four that answers a missing CEP with a real 404 and a JSON error body, rather than a 200 with a flag buried in it. That is worth something: the things that can go wrong are the things you already know how to handle.

It answers 400 for a CEP outside the allocated space, which the adapter also reads as an absence — the kit normalizes the format before calling, so the format is not what is in question.

Coordinates arrive as strings and are parsed rather than cast, because Number('') is 0 and a silent (0, 0) is worse than no location at all.

Options

awesomeapi({ baseUrl: 'https://cep.awesomeapi.com.br/json' })

Rate limits

AwesomeAPI publishes no documented rate limit on this endpoint and no SLA. Use a cache, and put a second provider behind it. See caching and providers.

Licence

MIT.

This package is an API client and redistributes no data. It is not affiliated with, endorsed by, or sponsored by AwesomeAPI; the name identifies the service it connects to. AwesomeAPI has its own terms of use, and calling it is your relationship with them.