Cómo conectarse al pipeline de datos OSM

El sistema de inteligencia de ubicación de la plataforma ingesta datos de puntos de interés (POI) de OpenStreetMap a través de archivos de ingestión JSONL. Conectarse al pipeline de datos OSM significa escribir o adaptar un script de ingestión que consulte la API de Overpass, produciendo un archivo JSONL en el esquema de la plataforma y registrando la ingestión con la configuración de taxonomía. Esta guía cubre una ingestión de cadena única para una nueva categoría minorista o de servicios.

Para la arquitectura del motor GIS, véase pointsav-gis-engine. Para construir un mapa a partir de datos de clusters ingeridos, véase build-a-colocation-map.

[edit]Requisitos previos

• Acceso al directorio de trabajo app-orchestration-gis (los scripts de pipeline)
• Python 3.9+ con requests disponible
• Acceso de red a la API de Overpass (overpass-api.de o un espejo local)
• Un Q-ID de Wikidata para la cadena o categoría que se está ingestando (búsquelo en wikidata.org)

[edit]Paso 1: Identificar el Q-ID de Wikidata

Cada cadena en la taxonomía está anclada a un Q-ID de Wikidata. Esto proporciona un identificador estable e independiente del idioma para la entidad. Busque la cadena en Wikidata y registre el Q-ID (p.ej., Walmart: Q483551, IKEA: Q54078).

Si la categoría no tiene una entrada de Wikidata única, use una consulta basada en nombre (modo name_query) en lugar de una búsqueda por Q-ID.

[edit]Paso 2: Escribir el YAML de ingestión

Cree un archivo YAML de ingestión bajo service-business/ con el nombre <nombre-cadena>-<código-país>.yaml:

chain: walmart-us
wikidata_id: Q483551
query_mode: wikidata    # o: name_query
name_query: null         # usado solo cuando query_mode: name_query
country_code: US
bbox: [-125.0, 24.4, -66.9, 49.4]   # cuadro delimitador para el país
output: service-business/walmart-us.jsonl
taxonomy_family: ALPHA_HYPERMARKET
taxonomy_tier: 1

Para el modo name_query (cuando la cobertura de Wikidata es escasa), establezca query_mode: name_query y proporcione name_query: "Walmart". El script de ingestión realiza una búsqueda de nombre de texto libre en la API de Overpass.

[edit]Paso 3: Ejecutar el script de ingestión

Ejecute el script de ingestión existente con el nuevo YAML:

python3 app-orchestration-gis/ingest-chain.py service-business/walmart-us.yaml

El script consulta la API de Overpass, filtra los resultados por el cuadro delimitador y el código de país, y escribe registros JSONL en service-business/walmart-us.jsonl. Cada registro contiene: name, lat, lon, wikidata_id, chain, country, taxonomy_family, taxonomy_tier.

Recuentos de registros típicos: las cadenas urbanas densas producen 500–2.000 registros; las cadenas de hipermercados nacionales producen 100–500; los minoristas especializados producen 50–200.

[edit]Paso 4: Registrar la cadena en la taxonomía

Añada la nueva cadena a la configuración de taxonomía en app-orchestration-gis/taxonomy.py bajo el grupo de familia apropiado:

"walmart-us": TaxonomyEntry(
    family="ALPHA_HYPERMARKET",
    tier=1,
    jsonl_path="service-business/walmart-us.jsonl",
    wikidata_id="Q483551",
),

[edit]Paso 5: Reconstruir la capa de clusters

Después del registro, reconstruya la capa de clusters para incorporar los nuevos datos POI:

python3 app-orchestration-gis/build-geometric-ranking.py

La reconstrucción lee todos los archivos JSONL registrados, ejecuta el paso de agrupamiento DBSCAN y regenera clusters-meta.json. Verifique que la nueva cadena aparezca en la salida del cluster:

python3 -c "import json; d=json.load(open('gateway/www/data/clusters-meta.json')); print(sum(1 for c in d['clusters'] if 'walmart' in str(c)))"

[edit]Puntos clave

• Cada cadena requiere un descriptor YAML de ingestión y un archivo de salida JSONL en service-business/
• Los Q-IDs de Wikidata son preferibles a las consultas de nombre; recurra a consultas de nombre solo cuando la cobertura de Wikidata esté ausente
• El paso de registro de taxonomía vincula el archivo JSONL con el pipeline de agrupamiento
• Se requiere una reconstrucción completa del cluster después de añadir una nueva cadena — las actualizaciones incrementales no están soportadas en el pipeline actual

[edit]Véase también

• pointsav-gis-engine — la arquitectura del motor GIS y el pipeline de agrupamiento DBSCAN
• build-a-colocation-map — cómo mostrar los datos del cluster en una aplicación web MapLibre
• location-intelligence-archetypes — el modelo de arquetipos PRO/VWH/PKS que alimenta la taxonomía
• export-structured-data — exportar el GeoJSON resultante para uso externo