API d'export de métriques

Extrayez des données chronologiques traitées et prêtes pour le reporting depuis vos centrales en un seul appel — sur un parc, plusieurs parcs ou des portefeuilles entiers. Le système d'export est construit autour de modèles qui définissent quelles métriques exporter et dans quel ordre, de sorte que les chiffres que vous voyez dans un rapport généré soient exactement ceux que vous extrayez via l'API.

Le téléchargement CSV de référence est GET /v1/export/metrics/template/{template_uid}. Une variante JSON et un export distinct de séries temporelles brutes couvrent les graphiques intégrés à l'application et les courbes de puissance haute résolution ; les trois sont décrits ci-dessous.

Ouvrir dans Mirox

Construisez et exécutez un export de manière interactive depuis Export de données ▸ Constructeur, ou gérez vos modèles depuis Export de données ▸ Modèles. Les mêmes modèles et métriques décrits ici alimentent à la fois le constructeur intégré à l'application et l'API.

Comprendre les types de métriques

La plateforme Mirox fonctionne avec deux types distincts de métriques qui répondent à des objectifs différents :

Collecte de métriques brutes

Les métriques brutes constituent le fondement de l'infrastructure de données de la plateforme. Ces métriques sont :

Collectées directement depuis le matériel : extraites des onduleurs, capteurs et data loggers
Stockées telles quelles dans la base de données chronologique : préservent la granularité et la structure d'origine
Optimisées pour le monitoring en temps réel : permettent des tableaux de bord en direct et des requêtes instantanées
Multi-dimensionnelles : utilisent des labels pour répartir les données par composant, emplacement ou type
Compteurs cumulatifs : stockent souvent des valeurs d'énergie totales qui augmentent au fil du temps
Haute fréquence : peuvent être collectées toutes les quelques secondes ou minutes

Les métriques brutes sont essentielles au fonctionnement du système mais ne sont pas optimisées pour un export de données convivial. Elles nécessitent transformation, agrégation et interprétation pour devenir des métriques métier exploitables.

Pour des informations détaillées sur la collecte de métriques brutes, voir Architecture de collecte de métriques.

Métriques d'export

Les métriques d'export sont des métriques traitées et conviviales, conçues spécifiquement pour l'export de données et le reporting :

Pré-agrégées : calculées sur une base quotidienne par défaut
Nettoyées et validées : contrôles de qualité des données appliqués
Nommage convivial : identifiants clairs et descriptifs
Unités cohérentes : standardisées sur toutes les métriques
Prêtes pour l'analyse : aucune transformation supplémentaire requise
Orientées métier : centrées sur les KPI et les besoins de reporting

Les métriques d'export sont identifiées par des chaînes metric_id (par exemple energy_grid_daily, availability_technical) et constituent le fondement du système d'export.

Conseil

Lorsque vous utilisez l'API d'export de métriques, vous travaillez toujours avec des métriques d'export. La collecte de métriques brutes est automatiquement transformée dans ces formats prêts à l'export par la plateforme.

Fonctionnalités clés

Exports basés sur des modèles : définissez des configurations de métriques réutilisables
Prise en charge multi-parcs : exportez des données agrégées de plusieurs parcs ou portefeuilles en une seule requête
Plusieurs formats d'export : CSV avec séparateurs configurables pour la compatibilité internationale, plus une variante JSON pour les graphiques intégrés à l'application
Plages temporelles flexibles : exportez par année, trimestre, mois, semaine ou journée unique
Options d'agrégation : agrégation quotidienne, hebdomadaire, mensuelle, trimestrielle ou annuelle
Prise en charge internationale : formats de date et séparateurs décimaux personnalisables
Métriques personnalisées : définissez vos propres métriques à l'aide de formules MiroxQL

Choisir le bon export

La plateforme propose trois chemins d'export distincts. Choisissez celui qui correspond à votre objectif :

Export	Endpoint	Sortie	Idéal pour
CSV par modèle	`GET /v1/export/metrics/template/{template_uid}`	Téléchargement CSV	Rapports, tableurs, facturation — colonnes prédéfinies, agrégées et tenant compte des formules, sur un ou plusieurs parcs
JSON par modèle	`POST /v1/export/metrics/query`	JSON	Graphiques et aperçus dans votre propre application — même moteur d'agrégation, renvoie des lignes de valeurs datées
Séries temporelles brutes	`POST /v1/export/raw/query`	JSON	Courbes de puissance haute résolution au pas de votre choix (5m, 15m, 1h, 1d) — requêtes brutes arbitraires, non agrégées

La route CSV par modèle est l'export de métriques de référence et l'objet de ce guide. Pour un accès programmatique et piloté par formules à vos données, voir Langage de requête MiroxQL — la méthode prise en charge pour interroger et façonner des chiffres bruts en métriques personnalisées.

Multi-parcs en un seul appel

Les exports CSV et JSON par modèle acceptent des paramètres de requête park et portfolio séparés par des virgules, ce qui vous permet d'extraire une agrégation à l'échelle d'un portefeuille en une seule requête. Lorsque les deux sont fournis, les parcs de chaque portefeuille sont réunis avec les parcs explicitement listés.

Système de modèles

Que sont les modèles d'export ?

Les modèles d'export sont des configurations prédéfinies ou personnalisées qui précisent :

Quelles métriques inclure dans l'export
L'ordre des métriques dans la sortie
Les métadonnées de chaque métrique (nom, unité, catégorie, description)

Les modèles permettent des exports cohérents et reproductibles, et peuvent être partagés au sein d'une organisation. Pour créer, modifier ou partager des modèles sans écrire de code, ouvrez Export de données ▸ Modèles dans Mirox.

Modèle système prédéfini

Le système fournit un modèle par défaut complet qui inclut toutes les métriques essentielles pour le monitoring et le reporting des parcs solaires.

Modèle Report Technical v1 (UID : ABCD12340001) :

Ce modèle complet est utilisé à la fois pour la génération de rapports PDF et les exports CSV. Il comprend :

Métriques chronologiques :

Production d'énergie (kWh) - energy_grid_daily
Énergie de rayonnement totale (kWh) - energy_radiation_daily
Capteur GTI (kWh/m²) - gti_sensor_daily
GTI météo (kWh/m²) - gti_weather_daily
Heures d'ensoleillement (h) - sunhours_daily
Disponibilité onduleur (%) - availability_inverter
Disponibilité énergie (%) - availability_energy
Disponibilité données (%) - availability_data
Disponibilité capteur (%) - availability_sensor
Énergie perdue par coupure réseau (kWh) - energy_shutdown_grid_daily
Énergie perdue par coupure externe (kWh) - energy_shutdown_external_daily

Métriques de configuration de rapport :

Énergie de rapport (kWh) - energy_report
GTI rapport incident (kWh/m²) - gti_report
GTI rapport effectif (kWh/m²) - gti_report_eff
PR rapport cible (%) - pr_report

Métriques calculées (avec MiroxQL) :

Analyse d'irradiance (réelle, utilisation météo, écart capteur-météo)
Cibles de production (basée météo, basée capteur, réelle, corrigée)
Performance ratios (météo, capteur, réel, corrigé)
Rendement spécifique (Wh/W)
Analyse des pertes (pertes non compensables)

Données cohérentes entre rapports et exports

Ce modèle est utilisé à la fois pour la génération de rapports PDF et les exports API, garantissant que les rapports générés en interne et les données exportées par l'utilisateur contiennent exactement les mêmes métriques et calculs. Cette cohérence est une fonctionnalité fondamentale de la plateforme, permettant une validation et une comparaison fiables des données.

Pour des informations sur les métriques calculées personnalisées, voir Langage de requête MiroxQL.

Métriques d'export disponibles

Toutes les métriques sont calculées sur une base quotidienne et peuvent être agrégées à des intervalles hebdomadaires, mensuels, trimestriels ou annuels. Chaque métrique inclut une formule simplifiée montrant comment la valeur est dérivée des métriques brutes.

Métriques de production d'énergie

Metric ID	Nom	Unité	Description	Formule
`energy_grid_daily`	Production d'énergie	kWh	Énergie quotidienne injectée dans le réseau	`sum(delta(grid_energy_total))` par composant
`energy_ac_daily`	Production AC	kWh	Production quotidienne d'énergie AC	`sum(delta(ac_energy_total))` par composant
`energy_inverter_daily`	Production onduleur	kWh	Production quotidienne d'énergie des onduleurs	`sum(delta(inverter_ac_energy_total))` par onduleur
`energy_radiation_daily`	Énergie de rayonnement totale	kWh	Énergie de rayonnement totale quotidienne	`sum(delta(radiation_energy_total))` par composant

Métriques de coupure/perte

Metric ID	Nom	Unité	Description	Formule
`energy_shutdown_grid_daily`	Énergie perdue par coupure réseau	kWh	Perte d'énergie quotidienne due aux contraintes réseau	`sum(delta(energy_loss_total))` où type='grid', par composant
`energy_shutdown_external_daily`	Énergie perdue par coupure externe	kWh	Perte d'énergie quotidienne due à un contrôle externe	`sum(delta(energy_loss_total))` où type='external', par composant

Métriques d'irradiance

Les métriques d'irradiance globale inclinée (GTI) sont comparables et mesurent le rayonnement solaire sur le plan incliné des modules solaires.

Metric ID	Nom	Unité	Description	Formule
`gti_sensor_daily`	Capteur GTI	kWh/m²	Irradiation globale inclinée quotidienne issue des capteurs	`avg(delta(irradiation_total))` où position='module-level' ou repli
`gti_weather_daily`	GTI météo	kWh/m²	Irradiation globale inclinée quotidienne issue des prévisions météo	`sum(weather_gti) / 4`, échantillonnage : intervalles de 15 min
`gti_report`	GTI rapport	kWh/m²	Cible GTI issue de la configuration du parc	valeur issue de la configuration du parc

Métriques météo

Metric ID	Nom	Unité	Description	Formule
`solar_radiation_daily`	Rayonnement solaire	Wh	Rayonnement solaire quotidien moyen	`avg(solar_radiation)` sur 24h
`sunhours_daily`	Heures d'ensoleillement	h	Heures d'ensoleillement quotidiennes	`count(weather_gti > 0) / 4`, échantillonnage : 15 min

Métriques environnementales

Metric ID	Nom	Unité	Description	Formule
`temperature_ambient_avg`	Température ambiante	°C	Température ambiante quotidienne moyenne	`avg(ambient_temperature)` sur 24h
`temperature_module_avg`	Température module	°C	Température de module quotidienne moyenne	`avg(module_temperature)` sur 24h
`wind_speed_avg`	Vitesse du vent	m/s	Vitesse du vent quotidienne moyenne	`avg(wind_speed)` sur 24h
`humidity_avg`	Humidité	%	Humidité quotidienne moyenne	`avg(humidity)` sur 24h

Métriques de disponibilité

Metric ID	Nom	Unité	Description	Formule
`availability_inverter`	Disponibilité onduleur	%	Disponibilité de l'onduleur basée sur la puissance de sortie et les conditions GTI	`avg(1 - count(inverter_power ≤ 0 AND weather_gti > 100))`, échantillonnage : 15 min
`availability_technical`	Disponibilité technique	%	Disponibilité technique du système	`avg(sum(scraper_health == 1) / count(scraper_health))` par source, échantillonnage : 15 min
`availability_data`	Disponibilité données	%	Disponibilité des données issues de la centrale	`1 - avg(count(grid_energy_total))` lorsque absentes, échantillonnage : 15 min
`availability_sensor`	Disponibilité capteur	%	Disponibilité du capteur	`1 - avg(count(solar_radiation))` lorsque absentes, échantillonnage : 15 min
`availability_energy`	Disponibilité énergie	%	Approximation de disponibilité basée sur l'énergie	`1 - (sum(energy_loss_total) / (sum(grid_energy_total) + sum(energy_loss_total)))`

La disponibilité technique évolue dans le temps

La portée de la métrique availability_technical s'élargit à mesure que de nouvelles fonctionnalités de la plateforme sont ajoutées. Cela peut faire diminuer la valeur lorsque de nouvelles fonctionnalités sont déployées, même si les systèmes existants fonctionnent normalement. Pour des comparaisons historiques stables, utilisez des métriques spécifiques comme availability_inverter, availability_data ou availability_sensor.

Métriques de batterie

Les agrégations de batterie opèrent au niveau du boîtier de la hiérarchie BESS — la vue canonique « BESS complet » définie par l'énumération BATTERY. Voir la page Collecte de métriques pour la hiérarchie complète des composants (environnement / boîtier / stockage / module / cellule).

Metric ID	Nom	Unité	Description	Formule
`battery_energy_in_daily`	Énergie chargée dans la batterie	kWh	Énergie DC quotidienne chargée dans la batterie	`sum(delta(battery_box_energy_dc_in_total))` par boîtier
`battery_energy_out_daily`	Énergie déchargée de la batterie	kWh	Énergie DC quotidienne déchargée de la batterie	`sum(delta(battery_box_energy_dc_out_total))` par boîtier
`battery_soc_avg`	État de charge de la batterie	%	État de charge quotidien moyen au niveau du boîtier	`avg(battery_box_soc)` sur 24h
`battery_soh_avg`	État de santé de la batterie	%	État de santé quotidien moyen au niveau du boîtier	`avg(battery_box_soh)` sur 24h
`battery_energy_charged_avg`	Énergie stockée dans la batterie	kWh	Énergie actuellement stockée, moyenne quotidienne	`avg(sum(battery_box_energy_charged))` sur 24h
`temperature_battery_avg`	Température de la batterie	°C	Température de batterie quotidienne moyenne au niveau du boîtier	`avg(battery_box_temperature)` sur 24h

Métriques de rapport

Metric ID	Nom	Unité	Description	Formule
`energy_report`	Énergie de rapport	kWh	Cible d'énergie issue de la configuration du parc	`value from park configuration`

Plage temporelle et agrégation

Sélection de la plage temporelle

Choisissez la tranche d'historique à exporter avec ces sélecteurs :

Année : une année civile complète
Trimestre : un trimestre d'une année donnée
Mois : un seul mois civil
Semaine : une seule semaine civile
Jour : une seule journée (nécessite qu'un mois soit défini)

Résolution d'agrégation

Au sein de la plage sélectionnée, les valeurs quotidiennes sont regroupées à la résolution de votre choix. Les métriques d'énergie et basées sur les heures sont sommées ; toutes les autres métriques sont moyennées.

Agrégation quotidienne

Valeurs quotidiennes brutes issues du stockage chronologique de la plateforme
Granularité la plus élevée disponible
Idéale pour l'analyse détaillée et le diagnostic
Taille de fichier : grande

Agrégation hebdomadaire

Données agrégées par semaine ISO (du lundi au dimanche)
Inclut le numéro de semaine et les colonnes de semaine civile
Une option full_week étend les premières et dernières semaines partielles en semaines ISO complètes
Convient à l'analyse de tendances
Taille de fichier : moyenne

Agrégation mensuelle

Données agrégées par mois civil
Inclut une colonne « Jours dans le mois » pour la normalisation
Idéale pour le reporting et les tendances à long terme
Taille de fichier : petite

Agrégation trimestrielle et annuelle

Données regroupées en trimestres civils ou années complètes
Idéale pour les synthèses de direction et la comparaison d'une année sur l'autre
Taille de fichier : la plus petite

Prise en charge des formats internationaux

Séparateurs CSV

L'API prend en charge plusieurs séparateurs CSV pour la compatibilité régionale :

Virgule (,) : standard aux États-Unis/Royaume-Uni
Point-virgule (;) : standard en Allemagne et dans de nombreux pays européens
Tabulation (\t) : universel, adapté à l'import Excel
Barre verticale (|) : alternative pour les cas particuliers

Séparateurs décimaux

Point (.) : standard aux États-Unis/Royaume-Uni (par exemple 1234.56)
Virgule (,) : standard en Allemagne et dans de nombreux pays européens (par exemple 1234,56)

Attention

Le séparateur CSV et le séparateur décimal doivent être différents pour éviter les problèmes d'analyse.

Formats de date

Des formats de date/heure personnalisés peuvent être spécifiés avec la syntaxe Python strftime :

Formats courants :

%Y-%m-%d : format ISO (2025-03-15)
%d/%m/%Y : format européen (15/03/2025)
%m/%d/%Y : format américain (03/15/2025)
%d.%m.%Y : format allemand (15.03.2025)
%Y-%m : mois uniquement (2025-03)
%Y-W%W : format de semaine ISO (2025-W11)

Format de sortie CSV

Les fichiers CSV exportés incluent des en-têtes avec les noms et unités des métriques. La structure varie selon l'intervalle d'agrégation :

Export mensuel

Inclut une colonne « Jours dans le mois » pour la normalisation.

Export hebdomadaire

Inclut à la fois les colonnes « Date » (format de semaine ISO) et « Semaine civile » (numéro de semaine).

Export quotidien

Une ligne par jour avec la date au format spécifié.

Cas d'usage

Reporting personnalisé

Créez des modèles d'export spécialisés pour :

Rapports de performance mensuels
Mises à jour trimestrielles pour les parties prenantes
Reporting de conformité annuel
Suivi de KPI personnalisés

Intégration tierce

Exportez des données pour l'intégration avec :

Systèmes de gestion de l'énergie
Plateformes de business intelligence
Logiciels de comptabilité carbone
Outils de gestion de portefeuille

Analyse de données

Alimentez vos propres analyses avec les chiffres exportés :

Benchmarking de performance
Analyse des tendances saisonnières
Alimentation des pipelines de business intelligence et de reporting

Authentification et autorisations

Tous les endpoints d'export nécessitent une session authentifiée. Vous pouvez les piloter depuis une session de navigateur ou avec un jeton d'API portant le groupe d'autorisations reporting.

Ce dont vous avez besoin :

Gestion des modèles : droits de lecture, création, modification ou suppression des modèles d'export au sein de votre organisation. Les modèles système sont en lecture seule pour tout le monde.
Export de métriques : accès en lecture pour exporter des rapports.
Accès aux parcs : vous ne recevez jamais que les données des parcs et portefeuilles que vous êtes autorisé à voir. Les parcs demandés auxquels vous n'avez pas accès sont silencieusement filtrés — et s'il n'en reste aucun accessible, la requête est rejetée.

Bonnes pratiques

Choisissez les bons modèles : utilisez les modèles prédéfinis quand c'est possible, créez-en des personnalisés pour des besoins spécifiques
Sélectionnez la bonne agrégation : utilisez le mensuel pour les rapports, le quotidien pour l'analyse détaillée
Définissez les bons séparateurs : adaptez-les à vos paramètres Excel/CSV locaux
Exports multi-parcs : tirez parti des capacités multi-parcs pour l'analyse au niveau du portefeuille
Réutilisabilité des modèles : créez des modèles à l'échelle de l'organisation pour un reporting cohérent
Utilisez MiroxQL : définissez des métriques calculées personnalisées pour une analyse avancée

Exemple pratique

Pour un exemple d'implémentation complet de génération de rapports personnalisés à l'aide de l'API d'export de métriques, voir l'Exemple de générateur de rapports. Cet exemple montre comment récupérer des données depuis l'API, les traiter et générer des rapports personnalisés avec des visualisations.

Gestion des erreurs

Réponses d'erreur courantes :

404 Not Found : le modèle, le parc ou le portefeuille n'existe pas
403 Forbidden : autorisations insuffisantes ou aucun parc accessible
422 Validation Error : paramètres invalides (par exemple, metric ID invalides)
400 Bad Request : combinaisons de paramètres invalides (par exemple, séparateur CSV et décimal identiques)
409 Conflict : le nom du modèle existe déjà dans l'organisation

Fonctionnalités associées

Langage de requête MiroxQL — définissez des métriques calculées personnalisées pour vos modèles
Génération de rapports externe — automatisez les exports CSV par modèle dans votre propre flux de reporting
Exemple de générateur de rapports — un exemple Python exécutable de bout en bout
Rapports — génération automatisée de rapports PDF à partir des mêmes modèles
Guide des jetons d'API — configurez un jeton d'API pour authentifier les exports