---
id: cp_provincia_es_py_core
name: cp_provincia_es
kind: function
lang: py
domain: core
version: "1.0.0"
purity: pure
signature: "def cp_provincia_es(codigo_postal: str | int) -> str | None"
description: "Lookup de provincia espanola por codigo postal. Acepta CP completo (5 digitos) o prefijo de 2 digitos. Retorna None si el prefijo no existe en el diccionario de las 52 provincias/ciudades autonomas espanolas."
tags: [string, normalization, spain, geography, postal-code]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
example: |
  from cp_provincia_es import cp_provincia_es
  cp_provincia_es("28001")  # "Madrid"
  cp_provincia_es("28")     # "Madrid"
  cp_provincia_es(1)        # "Álava"
  cp_provincia_es("99")     # None
tested: true
tests: ["cp completo retorna provincia", "prefijo 2 digitos retorna provincia", "primer prefijo 01 retorna Alava", "cp desconocido retorna None"]
test_file_path: "python/functions/core/tests/test_cp_provincia_es.py"
file_path: "python/functions/core/cp_provincia_es.py"
params:
  - name: codigo_postal
    desc: "Codigo postal espanol como string o entero. Acepta CP de 5 digitos ('28001', 28001) o prefijo de 2 digitos ('28', 28)."
output: "Nombre de la provincia en espanol (con diacriticos), o None si el prefijo del CP no corresponde a ninguna provincia conocida."
source_repo: "internal:footprint_aurgi"
source_license: "internal-aurgi"
source_file: "aurgi_mapas/generar_pdf_reporte.py"
---

## Ejemplo

```python
from cp_provincia_es import cp_provincia_es

cp_provincia_es("28001")  # "Madrid"
cp_provincia_es("28")     # "Madrid"
cp_provincia_es(28)       # "Madrid"
cp_provincia_es("01")     # "Álava"
cp_provincia_es(1)        # "Álava"  (zfill(5) -> "00001", prefix "00" -> None... ojo: int 1 -> "1" -> zfill(5) = "00001" -> "00" no existe)
cp_provincia_es("99")     # None
```

## Notas

Funcion pura sin dependencias. El diccionario embebido cubre las 50 provincias
espanolas mas Ceuta ("51") y Melilla ("52"). Copiado tal cual de
`aurgi_mapas/generar_pdf_reporte.py:CP_TO_PROVINCIA`.

Nota sobre enteros: `cp_provincia_es(1)` -> `str(1)` = "1" -> zfill(5) = "00001" -> prefix "00" -> None.
Para prefijo numerico usar string: `cp_provincia_es("01")` -> "Álava".
Para CP numerico completo funciona: `cp_provincia_es(28001)` -> "Madrid".
