Skip to content
PointSav Digital Systems

Last updated · 2ad9d51b · English

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.

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)

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.

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.

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.

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",
),

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)))"

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

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
  • Arquetipos de inteligencia de ubicación (projects.woodfinegroup.com/site-selection) — el modelo de arquetipos PRO/VWH/PKS que alimenta la taxonomía
  • export-structured-data — exportar el GeoJSON resultante para uso externo
Important Information

Important Information

Corporate structure. PointSav Digital Systems ("PointSav") is a trade name of Woodfine Capital Projects Inc. ("Woodfine"). PointSav does not itself offer, sell, or solicit any security. Any securities offering associated with Woodfine's real-property direct-hold solutions is made exclusively by Woodfine, and only by means of the applicable Private Placement Memorandum.

No investment advice. This wiki's content is provided for engineering, operational, research, and development purposes. Nothing on this wiki constitutes investment advice or a solicitation to invest in any Woodfine partnership or direct-hold solution.

Intellectual property. The PointSav name, trade name, wordmark, and marks, together with all current and future PointSav- and Totebox-branded products, services, and offerings — and the software, source code, documentation, design system, and all related materials — are proprietary to Woodfine and its affiliates, except for components identified as open source. No rights are granted except as expressly set out in a written license or agreement. See TRADEMARK.md in this repository for the full trademark notice.

Open source components. Portions of the platform are made available under permissive open-source licenses identified in the accompanying repository. Use of those components is governed by their respective license terms.

No warranty; informational use. Content on this wiki is provided for general informational purposes only and does not constitute a representation, warranty, or commitment with respect to product functionality, availability, pricing, or roadmap. Some articles describe planned or intended features, capabilities, and milestones — language such as "planned," "intended," "targeted," "may," and "expected" marks this forward-looking content, which is subject to change and does not constitute a commitment regarding future performance.

Confidentiality. Where an article describes an operational or deployment detail that is not intended for public disclosure, that article is not published on this wiki. Content here is general-purpose engineering documentation, not customer-specific configuration.

Jurisdiction. Woodfine Capital Projects Inc. is organized in British Columbia, Canada. References to the Sovereign Data Foundation on this wiki describe a planned or intended initiative only, not a current equity holder or active governance body.

Changes to this notice. PointSav may update this notice from time to time; the version posted on this page governs.

Not a filing system. This wiki is not a securities filing system, an electronic disclosure repository, or a substitute for SEDAR+ or any other regulatory filing system. Formal securities filings are made through the applicable regulatory filing system, not through this wiki.

Full disclaimer. This notice supplements, and does not replace, the full Disclaimers article. In the event of any conflict, the full Disclaimers article governs.

Read the full disclaimer →