Librería escrita en Python 3 para la identificación de componentes de direcciones argentinas.
El objetivo de la librería georef-ar-address
es, dada una dirección en forma de string como entrada, extraer todas las componentes que la componen. Todo el procesamiento se hace de forma local, sin consultar recursos externos. Con la librería se intenta cubrir la mayor cantidad de tipos de direcciones posibles, teniendo en cuenta las distintas estructuras que pueden tomar las mismas, así también como errores comunes de escritura, presencia de datos innecesarios y ambigüedades.
Como ejemplo, utilizar la librería sobre la dirección:
Av. Libertador N1331 2ndo A e/25 de Mayo y Bartolomé Mitre
Resultaría en la siguiente extracción de componentes:
street_names: ["Av. Libertador", "25 de Mayo", "Bartolomé Mitre"]
door_number.value: "1331"
door_number.unit: "N"
floor: "2ndo A"
type: "between"
La librería se encuentra publicada en PyPI
, y puede ser instalada utilizando pip
:
$ pip3 install georef-ar-address
Para probar ejemplos de extracción de componentes de forma interactiva, utilizar el siguiente comando:
$ python -m georef_ar_address
Una vez ejecutado el comando se puede escribir una dirección y presionar ENTER para obtener las componentes de la misma.
Para utilizar la librería desde Python, se debe instanciar un objeto de tipo AddressParser
y utilizar su método parse
, pasando una dirección como argumento:
>>> from georef_ar_address import AddressParser
>>> parser = AddressParser()
>>> parser.parse('Sarmiento N° 1100')
AddressData({
"street_names": [
"Sarmiento"
],
"door_number": {
"value": "1100",
"unit": "N°"
},
"floor": None,
"type": "simple"
})
El valor de retorno de parse
es una instancia de AddressData
conteniendo cada componente de la dirección, en caso de una extracción exitosa. Los campos del objeto AddressData
son los siguientes:
.street_names
(list): Lista de nombres de calles contenidos en la dirección (e.g.Santa Fe
,Ruta 4
)..door_number_value
(str): Valor de la altura de la dirección (e.g.132
,400/401
,S/N
).door_number_unit
(str): Unidad de la altura de la dirección (e.g.N°
,nro.
,Km
)..floor
(str): Piso de la dirección (e.g.2ndo B
,PB
)..type
(str): Tipo de dirección detectado. Los valores posibles son:simple
: Dirección compuesta de un nombre de calle y una altura opcional.intersection
: Dirección compuesta de dos nombres de calles en forma de intersección, con altura opcional.between
: Dirección compuesta de tres nombres de calles, especificando una posición sobre una entre otras dos, con altura opcional.
El inicializador de la clase AddressParser
acepta un parámetro cache
de tipo dict
(o equivalente), que le permite cachear internamente resultados de parseos para acelerar el procesamiento de direcciónes con estructuras similares.
La librería georef-ar-address
(versión 0.0.5
) fue utilizada sobre varios listados de direcciones para poder estimar su precisión al momento de extraer componentes. A continuación, se explica el origen de cada listado y la fidelidad de los datos devueltos por la libería en cada caso:
El primer listado de direcciones que se construyó utiliza varias fuentes provenientes de distintos portales de datos abiertos del país, incluyendo el Portal Nacional de Datos Abiertos. Se verificó que cada archivo utilizado posea un solo campo de dirección, sin tener la calle separada de la altura.
El listado construido tiene aproximadamente 91000 direcciones. Se utilizó la librería sobre cada una, y los resultados fueron los siguientes:
- Direcciones categorizadas (no
None
): 95.1% - Aproximado de categorizaciones correctas: 88%
Para calcular el aproximado de categorizaciones correctas, se tomaron tres muestras de cien direcciones cada una, y se inspeccionó manualmente el resultado brindado por la librería para comprobar que la extración de datos fue correcta. El porcentaje aproximado de 88% categorizaciones correctas es esperado ya que el listado de direcciones construido es muy irregular y contiene grandes cantidades de direcciones escritas de formas impredecibles (es poco uniforme). Esto se debe a que el listado se construyó a partir de datos provenientes de más de 60 archivos distintos, cada uno potencialmente de una fuente distinta.
El segundo listado de direcciones probado fue el archivo carrefour.csv, que contiene la dirección de 325 sucursales del supermercado Carrefour. Los resultados fueron los siguientes:
- Direcciones categorizadas (no
None
): 99.3% - Categorizaciones correctas: 97.5%
En este caso, se categorizaron correctamente el 97.5% de las direcciones. El resultado fue comprobado manualmente.
El tercer listado de direcciones probado fue el de las sucursales del Banco de la Nación Argentina, con 617 elementos. Los resultados fueron los siguientes:
- Direcciones categorizadas (no
None
): 100% - Categorizaciones correctas: 97.7%
En este caso, se categorizaron correctamente el 97.7% de las direcciones. El resultado fue comprobado manualmente.
Para leer sobre las desiciones de diseño y funcionamiento de georef-ar-address
, ver el archivo design.md.
Para consultar el historial de versiones de georef-ar-address
, ver el archivo history.md.
En caso de que encuentres algún bug, tengas problemas con la instalación, o tengas comentarios de alguna parte de georef-ar-address
, podés mandarnos un mail a datosargentina@jefatura.gob.ar o crear un issue.