1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
package Cepis::Faixa;
use strict;
use warnings;
use Scalar::Util ();
our $VERSION = '0.2.0';
sub from_json {
my ( $class, $data ) = @_;
return undef unless ref $data eq 'HASH';
for my $key (qw(localidade cep_ini cep_fim ceps)) {
return undef unless defined $data->{$key};
return undef if ref $data->{$key};
}
return undef unless length "$data->{localidade}";
for my $key (qw(cep_ini cep_fim)) {
return undef unless "$data->{$key}" =~ /\A[0-9]{8}\z/;
}
return undef unless Scalar::Util::looks_like_number( $data->{ceps} );
return bless {
localidade => "$data->{localidade}",
uf => _string( $data->{uf} ),
estado => _string( $data->{estado} ),
regiao => _string( $data->{regiao} ),
ibge => _string( $data->{ibge} ),
cep_ini => "$data->{cep_ini}",
cep_fim => "$data->{cep_fim}",
ceps => int( 0 + $data->{ceps} ),
}, $class;
}
sub localidade { return $_[0]->{localidade} }
sub uf { return $_[0]->{uf} }
sub estado { return $_[0]->{estado} }
sub regiao { return $_[0]->{regiao} }
sub ibge { return $_[0]->{ibge} }
sub cep_ini { return $_[0]->{cep_ini} }
sub cep_fim { return $_[0]->{cep_fim} }
sub ceps { return $_[0]->{ceps} }
sub label {
my ($self) = @_;
return length $self->{uf}
? "$self->{localidade}/$self->{uf}"
: $self->{localidade};
}
sub to_hash {
my ($self) = @_;
return {
localidade => $self->{localidade},
uf => $self->{uf},
estado => $self->{estado},
regiao => $self->{regiao},
ibge => $self->{ibge},
cep_ini => $self->{cep_ini},
cep_fim => $self->{cep_fim},
ceps => $self->{ceps},
};
}
sub _string {
my ($value) = @_;
return '' unless defined $value;
return '' if ref $value;
return "$value";
}
1;
__END__
=encoding UTF-8
=head1 NAME
Cepis::Faixa - the municipality a CEP that does not exist would belong to
=head1 SYNOPSIS
my $address = eval { Cepis::lookup('25845000') };
if ( !$address && ref $@ && $@->isa('Cepis::Error::CEPNotFound') ) {
if ( my $faixa = $@->faixa ) {
print $faixa->localidade, "\n"; # "Areal"
print $faixa->uf, "\n"; # "RJ"
print $faixa->ceps, "\n"; # 118
printf "%s..%s\n", $faixa->cep_ini, $faixa->cep_fim;
# 25845001..25849899
}
}
=head1 DESCRIPTION
B<This is context for an error, not an address.> The lookup still failed, the
CEP still does not exist, and L<Cepis::Client/lookup> still throws
L<Cepis::Error::CEPNotFound>. What this object adds is I<which municipality
owns the band the CEP fell into> — enough to tell the user "25845000 does not
exist in Areal/RJ" instead of "not found".
That matters because a failing CEP is rarely random: it is usually someone who
knows the city and guessed the number, and the classic guess is the C<-000>
that 957 municipalities never received.
The object is reachable as C<< $err->faixa >> on L<Cepis::Error::CEPNotFound>,
and is C<undef> whenever the API sent no C<faixa> — the API B<omits> the field
rather than sending null when the CEP falls in a band no municipality owns.
=head2 The range is not a list of valid CEPs
L</cep_ini> and L</cep_fim> are the B<smallest and the largest CEP that actually
exist> in that municipality. They are not the bounds the Correios publish: the
DNE's own start for Areal is C<25845000> — exactly the CEP that just failed.
The range is also B<sparse>. Areal's 118 CEPs are scattered across the roughly
4,900 numbers between C<25845001> and C<25849899>. Iterating the interval, or
presenting it as "the valid CEPs for this city", produces mostly numbers that do
not exist. L</ceps> is there precisely so that cannot pass unnoticed: it says how
many of them are real.
Field names are the API's own, in Portuguese. See L<Cepis::Address> for why.
=head1 CONSTRUCTOR
=head2 from_json
my $faixa = Cepis::Faixa->from_json( $hashref );
Builds from the C<faixa> block of a 404 body. Returns C<undef> when the block is
missing, empty, not a hash, or malformed.
Parsing here is deliberately forgiving: a bad C<faixa> must never turn a clean
not-found into a parse failure. The caller still gets its
L<Cepis::Error::CEPNotFound>, just without the extra context.
=head1 ACCESSORS
=head2 localidade
Municipality name. Always present and non-empty — a block without it does not
build.
=head2 uf
Two-letter state code.
=head2 estado
Full state name.
=head2 regiao
Region of the country, such as C<"Sudeste">.
=head2 ibge
IBGE municipality code. The stable way to identify the municipality; the name
alone is not unique across states.
=head2 cep_ini
The smallest CEP that exists in the municipality, unmasked. Read the warning
above before treating it as a lower bound.
=head2 cep_fim
The largest CEP that exists in the municipality, unmasked.
=head2 ceps
How many CEPs the municipality actually has, as an integer. Compare it with the
span between L</cep_ini> and L</cep_fim> to see how sparse the range is.
=head2 label
C<"Areal/RJ">: the municipality and its state, ready to put in a message. Falls
back to the municipality alone when the API sent no C<uf>.
=head2 to_hash
The eight fields as a plain hashref.
=head1 SEE ALSO
L<Cepis>, L<Cepis::Error>, L<Cepis::Client>
=head1 LICENCE
ISC. Copyright (c) 2026 Murilo Ijanc E<lt>[email protected]<gt>.
=cut
|