/ 
Business-ES-CodigoPostal-0.03
/ Business::ES::CodigoPostal

NAME

Business::ES::CodigoPostal - Validación de códigos postales españoles: provincia, comunidad, región y localidades

VERSION

version 0.03

SYNOPSIS

use Business::ES::CodigoPostal 'validate_cp';

# OO
$cp = Business::ES::CodigoPostal->new( codigo => '28001' );
$cp = Business::ES::CodigoPostal->new({ codigo => '28001' );

# function
$cp = validate_cp('18001');
$cp = validate_cp('18001', { strict => 0 }); # _normalize()

if ($cp->{valid}) {
    print $cp->{provincia}; # Granada
    print $cp->{region};    # Peninsula
    print $cp->{ca};        # Andalucia
} else {
    print $cp->{error};
}

# localidades (carga los datos solo al pedirlas)
my @m = Business::ES::CodigoPostal::municipios('28017');  # ('Madrid')
Business::ES::CodigoPostal::asignado('28107');            # 0 -- no existe

DESCRIPTION

Este módulo permite validar códigos postales de España y obtener su provincia asociada. El rango válido de códigos es de 01000 a 52999.

Por defecto devuelve código ISO 3166-2

NAME

Business::ES::CodigoPostal - Validación de códigos postales españoles: provincia, comunidad, región y localidades

SUBROUTINES/METHODS

codigo

Devuelve el código postal almacenado en el objeto.

my $codigo = $cp->codigo;

error

Devuelve el mensaje de error si el código postal no es válido.

my $error = $cp->error;
print "Error: $error" if defined $error;

iso_3166_2

Devuelve el código ISO 3166-2 de la provincia.

my $iso = $cp->iso_3166_2;

insular

Devuelve 1 si el código postal corresponde a territorio insular (Baleares o Canarias).

if ($cp->insular) {
    print "Este CP está en una isla";
}

strict

Controla el modo de validación, modo strict por defecto, no se normaliza la entrada.

$cp->strict(0);  # Permitir normalización
my $is_strict = $cp->strict;

provincia

Devuelve el nombre de la provincia correspondiente al código postal.

my $provincia = $cp->provincia;
print "Provincia: $provincia" if $cp->valid;

prov_code

Código de provincia los primeros 2 digitos

region

Región: Baleares, Las Palmas, Santa Cruz de Tenerife

my $region = $cp->region;

valid

Indica si el código postal es válido (1) o no (0).

my $es_valido = $cp->valid;

ca

Devuelve la comunidad autónoma correspondiente al código postal.

my $ccaa = $cp->ca;

_normalize

Limpia y agrupa el código postal, cuando se fija strict a 0

validate_cp

Función que valida un código postal y devuelve un hash con el resultado.

my $resultado = validate_cp('28001');

if ($resultado->{valid}) {
    print "Código:     " . $resultado->{codigo};
    print "Provincia:  " . $resultado->{provincia};
    print "ISO 3166-2: " . $resultado->{iso_3166_2};
} else {
    print "Error:      " . $resultado->{error};
}

Retorna un hash con las claves: - valid : 1 si es válido, 0 si no - codigo : código postal - provincia : nombre de la provincia (si es válido) - iso_3166_2 : código ISO 3166-2 de la provincia (si es válido) - error : mensaje de error (si no es válido)

new

Crea un nuevo objeto de código postal.

my $cp = Business::ES::CodigoPostal->new();
my $cp = Business::ES::CodigoPostal->new(codigo => '28001');
my $cp = Business::ES::CodigoPostal->new({ codigo => '28001', strict => 0, iso_3166_2 => 0 });

Parámetros: - codigo : Código postal a validar - strict : Modo strict (Por defecto), a 0 para normalizar la entrada - iso_3166_2: Incluir código ISO 3166-2 (Por defecto)

_set_error

Fija el error como argumento el texto a guardar

set

Fija nuevo código postal

my $res = $cp->set('08001');

unless ($res) {
    print "Error: " . $cp->error;
}

Retorna 1 si el código posta es válido o 0 si no.

municipios

Localidades de un código postal, ordenadas. Lista vacía si no consta.

my @m = $cp->municipios;                                 # OO
my @m = Business::ES::CodigoPostal::municipios('28017'); # función

Los datos viven en Business::ES::CodigoPostal::Municipios y se cargan solo al llamar aquí: validar un código postal o resolver su provincia no los toca. Cargarlos cuesta unos 20 ms y unos 4 MB, una sola vez por proceso.

Las localidades salen decodificadas (caracteres, no bytes), a diferencia de provincia y ca, que devuelven los literales del módulo tal cual.

asignado

Cierto si el código postal está asignado a alguna localidad.

Business::ES::CodigoPostal::asignado('28017');  # 1 -- Madrid
Business::ES::CodigoPostal::asignado('28107');  # 0 -- no existe

Es una comprobación distinta de valid, y más estrecha: valid mira que el código esté en el rango 01000-52999, así que da por bueno cualquier número con un prefijo de provincia real. 28107 pasa esa validación --prefijo 28, Madrid-- y sin embargo no existe: Alcobendas es 28100, 28108 y 28109. Un error de transposición dentro de la misma provincia solo se ve preguntando por la localidad.

Falso significa "no consta en los datos". Para España el volcado está prácticamente completo, pero no es lo mismo que "no existe".

AUTHOR

HDELGADO <hdelgado@cpan.org>

FUENTE DE LOS DATOS

Los nombres de provincia, comunidad autónoma y región son tablas propias del módulo.

Las localidades de Business::ES::CodigoPostal::Municipios proceden de GeoNames (volcado export/zip/ES.zip), bajo licencia Creative Commons Attribution 4.0: https://creativecommons.org/licenses/by/4.0/.

LICENCIA

Copyright 2025-2026 HDELGADO.

Este módulo es software libre; puede redistribuirse y modificarse bajo los mismos términos que Perl mismo. Los datos de localidades conservan su licencia propia (CC BY 4.0), indicada arriba.

AUTHOR

HDELGADO <hdelgado@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by HDELGADO.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.