Exportaciones y la API de solo lectura

Para quién es: el analista que trabaja con los datos fuera de Nebli Environment, y el desarrollador que conecta un tablero o una plataforma de datos.

Antes de empezar:

• Las exportaciones de lecturas crudas requieren el rol Analista o uno superior (Personas y acceso).
• Las claves API las crea y las revoca un Administrador.

Exportar las lecturas crudas de un sitio

Exportar lecturas crudas, en la tabla, prepara todas las lecturas de un sitio en un período: las últimas 24 horas o los últimos 7, 30 o 90 días. Elija el Sitio y el Período, y luego Preparar. Exportar tabla, que descarga exactamente lo que ve en la tabla, se explica en Mapa, página del nodo y tabla.

La exportación se prepara en segundo plano. La encuentra en su menú, en Exportaciones, con su estado:

Una exportación lista se puede descargar durante 7 días.

Llega en dos archivos CSV:

• Lecturas (CSV). Todas las lecturas de todos los nodos del sitio en el período, incluidas las sospechosas, una por fila: node_id, node, channel, value, unit, device_time_utc, arrived_at_utc, quality. Las horas están en UTC con el desfase. quality es raw (cruda), corrected (corregida) o suspect (sospechosa). Un hueco es un hueco: no se rellena nada.
• % datos válidos (CSV). Para cada nodo, canal y día (en la zona horaria del sitio): cuántas lecturas se esperaban según el intervalo de reporte del nodo, cuántas llegaron sin ser sospechosas, y el porcentaje: node_id, node, channel, day_site_local, expected, valid, valid_percent.

La exportación contiene lo que había llegado cuando usted la pidió. Una celda que empieza como una fórmula de hoja de cálculo lleva delante una comilla simple, así que un nombre escrito nunca se ejecuta en su hoja de cálculo.

Límites:

• Puede tener una sola exportación en preparación a la vez: "Ya se está preparando una exportación suya; espere a que termine."
• Una organización puede pedir 5 exportaciones de lecturas crudas en cualquier período de 24 horas: "Su organización ya hizo sus exportaciones de hoy."

La API de solo lectura

La API lee los nodos y las lecturas de su organización en JSON. No puede cambiar nada.

Cree una clave

1. Vaya a Configuración › Claves API y elija Nueva clave.
2. Póngale un nombre, por ejemplo "Tablero Secretaría de Ambiente".
3. Copie la clave de la tarjeta. Se muestra solo esta vez.

Una clave lee toda su organización. Su tarjeta muestra Alcance: solo lectura, cuándo se creó y cuándo se usó por última vez. Revocar pide confirmación ("¿Revocar la clave {nombre}? Su siguiente solicitud será rechazada.") y se aplica desde la siguiente solicitud de la clave. Las claves revocadas siguen en la lista durante 30 días.

Haga una solicitud

Envíe la clave en el encabezado Authorization, nunca en la dirección:

curl -H "Authorization: Bearer $NEBLI_ENV_KEY" \
  "https://env.nebli.ai/api/v1/nodes?lang=es"

Solo existe GET. Hay tres rutas:

lang=es o lang=en define el idioma de los nombres y los mensajes.

Lecturas

GET /api/v1/nodes/{nodeId}/readings?channel=pm25&from=2026-10-01T00:00:00-05:00&to=2026-10-02T00:00:00-05:00

• channel, from y to son obligatorios. from y to son fechas y horas con su desfase horario. Un rango de más de 31 días se rechaza.
• Sin period, recibe puntos crudos, hasta 1.440 por página. Si hay más, la respuesta trae next; envíelo como cursor para pedir la página siguiente.
• Con period=1h, 8h o 24h, recibe puntos promediados en una sola página, cada uno con count, la cantidad de lecturas que promedia.
• quality=corrected devuelve la serie corregida, si existe; por defecto es raw. Una serie nunca mezcla las dos.
• Las lecturas sospechosas quedan fuera. Un período sin lecturas no devuelve puntos, nunca ceros.

Cada punto tiene time (la hora del dispositivo, o el inicio de un período promediado), value (o textValue en un canal que lleva palabras), unit y quality.

Límites y respuestas

• Cada clave puede hacer 60 solicitudes por minuto. Cada respuesta trae X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Pasado el límite, la respuesta es 429 con Retry-After.
• Una clave ausente, mal formada, desconocida o revocada recibe 401: "Clave de API no válida o revocada."
• Un nodo que no existe y un nodo de otra organización reciben el mismo 404.
• Una solicitud fuera de sus límites (un rango, un período o un cursor) recibe 400.
• 503 significa que debe intentarlo de nuevo.

Qué no incluye la API

• Las alertas. La API lee solo nodos y lecturas.
• Los índices de calidad del aire (ICA, IBOCA). Están en la consola y en Exportar tabla, no en la API.

Siguientes pasos

• Mapa, página del nodo y tabla: la exportación de exactamente lo que ve en la tabla.
• Conectar sensores: cómo entran las lecturas.