Business-ES-CodigoPostal
========================

Validación de códigos postales españoles: formato, provincia, comunidad
autónoma, región y localidades.

    use Business::ES::CodigoPostal qw(validate_cp municipios asignado);

    my $cp = validate_cp('18001');

    if ($cp->{valid}) {
        print $cp->{provincia};   # Granada
        print $cp->{ca};          # Andalucía
        print $cp->{region};      # Peninsula
        print $cp->{iso_3166_2};  # ES-GR
    }
    else {
        print $cp->{error};
    }

    my @m = municipios('28017');   # ('Madrid')

También hay interfaz orientada a objetos:

    my $cp = Business::ES::CodigoPostal->new(codigo => '28001');
    $cp->provincia;  $cp->ca;  $cp->region;  $cp->insular;
    $cp->set('08001');


VALIDAR NO ES EXISTIR
---------------------

validate_cp comprueba que el código tenga cinco dígitos y caiga en el rango
01000-52999, es decir, que su prefijo sea un número de provincia real. Eso no
garantiza que el código esté asignado a algún sitio:

    validate_cp('28107')->{valid}   # 1 -- prefijo 28, Madrid
    asignado('28107')               # 0 -- no existe

Alcobendas es 28100, 28108 y 28109. Una transposición de dígitos dentro de la
misma provincia sólo se detecta preguntando por la localidad, y es un error
frecuente en direcciones tecleadas a mano.


NORMALIZACIÓN
-------------

Por defecto la validación es estricta. Con strict a 0 se limpia la entrada,
que es lo que hace falta al procesar hojas de cálculo, donde los ceros
iniciales desaparecen:

    validate_cp('8015', { strict => 0 })->{provincia}   # Barcelona


CODIFICACIÓN
------------

Desde la 0.03 el módulo devuelve CARACTERES en todas sus salidas de texto.
Hasta la 0.02 devolvía bytes UTF-8 crudos, y guardarlos en una base de datos
con la conexión en UTF-8 producía doble codificación. Si tu código
decodificaba la salida, deja de hacerlo.


INSTALACIÓN
-----------

    perl Makefile.PL
    make
    make test
    make install

O con cpanm:

    cpanm Business::ES::CodigoPostal


DATOS
-----

Las tablas de provincias, comunidades y regiones son propias del módulo.

Las localidades de Business::ES::CodigoPostal::Municipios proceden de GeoNames
(https://www.geonames.org/, volcado export/zip/ES.zip), bajo licencia Creative
Commons Attribution 4.0 (https://creativecommons.org/licenses/by/4.0/).
Se regeneran con maint/gen-municipios.pl.

Ese módulo pesa unos 650 KB y se carga sólo cuando se piden localidades:
validar un código o resolver su provincia no lo toca.


LICENCIA
--------

Copyright 2025-2026 HDELGADO.

Software libre bajo los mismos términos que Perl. Los datos de localidades
conservan su licencia propia (CC BY 4.0).