API Metric Export

L'API Metric Export fournit n'importe quel indicateur de vos centrales sous forme de série temporelle, en CSV ou en JSON, avec une seule requête GET. Elle lit la même collection d'indicateurs que les rapports, y compris les indicateurs que votre organisation a définis elle-même.

Chaque lien affiché par la page Export de données est un appel de cette API : le moyen le plus simple d'obtenir une requête qui fonctionne est donc de la construire là et de la copier.

Les liens d'export de l'export précédent continuent de fonctionner sans changement. Ils sont décrits dans l'API de l'ancien export ; le passage de l'un à l'autre est expliqué dans le guide de migration.

Routes

Tous les chemins suivent https://service.mirox.io/api.

Authentification

Envoyez un jeton d'API du groupe Metric Export dans l'en-tête Authorization :

Authorization: Bearer YOUR_API_TOKEN

Le jeton lit chaque route d'export de cette page ainsi que les anciennes routes. Il ne peut rien créer, modifier ni supprimer. Dans un navigateur où vous êtes connecté à Mirox, les liens fonctionnent sans jeton.

Vous ne recevez que les données des centrales dont vous pouvez lire les mesures. Les indicateurs de votre organisation sont exportés par chaque rôle d'organisation sauf Externe. Voir Qui peut exporter quoi.

Exporter une série temporelle

GET /v1/export/series

Injection réseau d'une centrale sur le mois précédent, par jour :

curl --compressed "https://service.mirox.io/api/v1/export/series?park=ABC123DEF456&metrics=plant.grid_feedin&window=previous_month&step=day" \
  -H "Authorization: Bearer YOUR_API_TOKEN" -o feedin.csv

Date;Grid feed-in (kWh)
2026-08-01;5321,4
2026-08-02;4980,2
...

Paramètres

lane_limit et lane_page hors de leurs bornes sont ramenés à la borne la plus proche. Un paramètre que la route ne connaît pas est ignoré.

Indicateurs et valeurs

Un identifiant d'indicateur a la forme <préfixe>.<nom>, par exemple plant.grid_feedin, inverter.ac_power ou sensor.irradiance. Un indicateur de votre organisation s'écrit organization.<id de l'indicateur>. Le catalogue les liste tous.

Chaque indicateur a une grandeur, qui décide des modes de valeurs qu'il propose :

Un suffixe fixe le mode d'un seul indicateur et l'emporte sur values :

metrics=plant.grid_feedin:cumulative,plant.grid_power

Un mode qui ne s'applique pas à un indicateur n'est jamais une erreur. L'indicateur est exporté en native, et la remarque value_mode_ignored le signale. delta n'est jamais appliqué à une puissance.

Le même indicateur dans deux modes donne deux colonnes. Le même indicateur deux fois dans le même mode en donne une.

Période

Indiquez la période de l'une des trois façons suivantes. Deux façons dans une même requête répondent 400 window_conflict.

Période libre. start et end sont une date (2026-07-01) ou une date avec heure (2026-07-01T06:00, 2026-07-01T06:00:00Z, 2026-07-01T06:00:00+02:00). Une valeur sans fuseau horaire est lue dans le fuseau horaire des lignes. Un end qui est une date inclut ce jour ; un end avec heure est l'instant où la période se termine. Sans end, la période se termine maintenant. end seul, sans start, est refusé.

Calendrier. year de 2020 à 2100, quarter de 1 à 4, month de 1 à 12, week de 1 à 53 (semaine ISO), day de 1 à 31. day exige month. Sans year, il s'agit de l'année en cours. day l'emporte sur week, week sur month, month sur quarter.

Périodes prédéfinies. today, yesterday, last_7_days, last_30_days, this_week, previous_week, this_month, previous_month, this_quarter, previous_quarter, this_year, previous_year. Les périodes this_ courent jusqu'à maintenant ; last_7_days et last_30_days glissent jusqu'à maintenant pour les pas inférieurs à un jour (même heure 7 ou 30 jours plus tôt) ; à partir de day, ce sont les 7 ou 30 derniers jours locaux, aujourd'hui compris. À partir de day, chaque fenêtre est élargie à des jours entiers (semaines, mois …) dans le fuseau de la centrale, et la réponse renvoie la fenêtre effective.

Une période commence au plus tôt en 2020 et couvre au plus 1827 jours (cinq ans). Une période qui s'étend dans le futur se termine maintenant, avec la remarque end_clamped.

Pas

step=auto choisit un pas que chaque indicateur demandé propose et qui respecte les limites : 15min jusqu'à deux jours, 1h jusqu'à 62 jours, day jusqu'à trois ans, month au-delà. Si ce pas ne convient pas, le pas immédiatement plus grossier est essayé, puis les pas plus fins. La remarque step_auto et l'en-tête X-Mirox-Step nomment le pas choisi.

Chaque indicateur propose ses propres pas. Le catalogue les liste sous export_steps :

La puissance n'est proposée qu'à 15 minutes ou plus fin. Une puissance journalière ou mensuelle est une moyenne qui masque ce qui s'est passé ; l'indicateur d'énergie donne la valeur recherchée.

Un pas n'est jamais modifié en silence. Avec mismatch=refuse, la valeur par défaut, un pas que l'un des indicateurs ne propose pas répond 400 step_not_served avec les pas de chaque indicateur, et avec step=auto, des indicateurs qui n'ont aucun pas en commun répondent 400 no_common_step. Avec mismatch=sparse, une telle requête est fournie malgré tout — voir Indicateurs à pas différents.

Les pas d'un jour ou plus couvrent des intervalles entiers. Une période qui commence ou se termine à l'intérieur de l'un d'eux est élargie vers l'extérieur, avec la remarque window_aligned. Les semaines commencent le lundi.

Indicateurs à pas différents

mismatch=sparse fournit une requête dont les indicateurs ne proposent pas tous le pas, pourvu que chacun propose un pas quelconque. La grille du fichier est le pas demandé ; avec step=auto, c'est le pas que le plus grand nombre d'indicateurs proposent tel quel, choisi selon la période et les limites comme d'habitude. Les positions des colonnes et la forme de la réponse CSV et JSON ne changent pas.

Deux cas sont refusés dans les deux modes, avec 400 step_not_served : une valeur par mois, trimestre ou année dans un fichier par week, car son premier jour n'est presque jamais un lundi ; et une valeur mensuelle comme le Marktwert dans un fichier par quarter ou year, car une somme ou une moyenne de mois n'est pas cette valeur. Dans un fichier par month, elle est lue telle quelle ; dans un fichier plus fin, elle est clairsemée.

L'estimation liste les mêmes remarques, compte les lectures au pas propre de chaque indicateur et marque un pas dans per_step comme dans les limites même si tous les indicateurs ne le proposent pas. La page Export de données demande toujours avec mismatch=sparse ; un modèle porte son propre mismatch dans sa spec.

Grille temporelle

Avec tz=local, les lignes suivent l'heure locale de la centrale, heure d'été comprise : un jour est un jour local de 23, 24 ou 25 heures, un mois est un mois local. Avec tz=utc, les lignes suivent le calendrier UTC.

• Aux pas inférieurs à un jour en heure locale, la colonne Décalage UTC (UTC offset avec language=en) suit la colonne de temps (+02:00). Le jour du passage à l'heure d'hiver, une heure apparaît deux fois ; le décalage permet de les distinguer. offset_column=false supprime la colonne.
• Des centrales situées dans des fuseaux horaires différents partagent une seule colonne de temps. Une telle requête est servie sur le calendrier UTC, avec la remarque merged_on_utc, que les centrales soient regroupées ou séparées.
• Avec tz=utc et un pas d'un jour ou plus, un indicateur qui n'existe que par jour local n'a pas de valeur UTC. Sa colonne reste vide, avec la remarque utc_calendar_unsupported.

L'en-tête X-Mirox-Grid nomme le calendrier utilisé : local:Europe/Berlin ou utc.

Plusieurs centrales

Avec multi_park_agg=merge, chaque indicateur est une colonne pour toutes les centrales, regroupée selon la règle de l'indicateur. Le catalogue liste la règle sous merge :

Un indicateur qui ne peut pas être regroupé est exporté par centrale, avec la remarque merge_not_meaningful. Cela vaut aussi pour un ratio à un pas auquel ses deux moitiés ne sont pas disponibles, et pour les prix de centrales situées dans des zones de marché différentes.

Avec multi_park_agg=split, chaque indicateur est une colonne par centrale. Avec une seule centrale, les deux donnent le même fichier.

Les indicateurs par composant sont toujours par centrale (remarque components_split_by_park).

Composants

Un indicateur d'un niveau de composant donne une colonne par composant. Les niveaux sont inverter, gak (boîte de jonction), string, turbine, sensor, meter, battery_box (conteneur), battery_storage (rack), battery_module, battery_cell et battery_pcs (convertisseur).

Sans components, l'export contient tous les composants visibles des centrales, lane_limit par indicateur et par page. S'il y en a davantage, la remarque lanes_truncated en indique le total ; demandez la page suivante avec lane_page.

components restreint l'export aux composants que vous nommez. Une référence a la forme <niveau>:<id>, par exemple inverter:1043. Un capteur ou un compteur que Mirox mesure mais qui n'a pas d'entrée dans les composants de la centrale a une référence de la forme sensor:h3f9c2a71b04e6d5. La route des composants liste les références d'une centrale. Une référence qui n'appartient à aucune des centrales choisies répond 400 unknown_lane.

metrics=inverter.ac_power&components=inverter:1043,inverter:1044

Requêtes MetricsQL brutes

expr ajoute à un export une requête brute en MetricsQL, le langage de requête de la base de séries temporelles de la plateforme — pour une série pour laquelle la collection n'a pas d'indicateur. Le paramètre peut être répété jusqu'à cinq fois ; chaque expression peut compter jusqu'à 4 000 caractères. Une requête peut porter expr seul, ou metrics et expr ensemble ; les colonnes des indicateurs viennent en premier.

expr=sum by (inverter_id) (powerplant_inverter_power_ac)&park=ABC123DEF456&window=yesterday&step=15min

Une expression est évaluée par centrale, comme un tableau de bord l'évalue : sur les données de la centrale elle-même, au pas demandé, en échantillons bruts — tout pas est permis, values et les règles de regroupement des indicateurs ne s'appliquent pas. Mirox ajoute la centrale à chaque sélecteur de l'expression ; une expression qui nomme elle-même un label park, organization ou plant est refusée avec 400 expr_forbidden_label.

Lorsqu'une expression renvoie plusieurs séries sur l'une de ses centrales, les colonnes de cette expression sur toutes les centrales portent les labels de série, de sorte qu'un fichier n'a qu'une nomenclature par expression. Un en-tête de plus de 1 000 caractères est coupé avec … dans l'expression, jamais dans le texte de la série. Dans la réponse JSON, columns[].key est le texte de header=id et columns[].metric l'identifiant de l'expression, expr.e1, expr.e2, …, qu'utilisent les remarques et les refus. Une centrale sur laquelle l'expression ne renvoie rien garde une colonne vide, avec la remarque expr_no_series ; avec plusieurs centrales, chaque centrale reçoit ses propres colonnes, avec la remarque expr_split_by_park.

Une expression peut renvoyer au plus 500 séries sur une centrale (400 expr_too_many_series) ; agrégez-la, avec sum by (…) par exemple. Les séries comptent dans les mêmes 400 colonnes et 1 800 000 valeurs que tout export : la première lecture de chaque expression sur chaque centrale est une courte sonde, les largeurs sont additionnées sur toute la requête, et une requête qui dépasse les limites est refusée avec 400 over_budget et params.series avant toute lecture complète d'une expression. Une expression qui ne s'analyse pas, est vide, trop longue, ou que la base refuse répond 400 expr_invalid avec la reason.

L'estimation compte une expression comme une colonne par centrale, car ses séries ne sont connues qu'à la lecture. Les expressions ne sont pas enregistrées dans les modèles.

Réponse CSV

La réponse est en UTF-8, avec le nom de fichier series_export_<premier jour>_<dernier jour>_<pas>.csv. Une réponse de plus de 1 Mo environ est compressée lorsque la requête porte Accept-Encoding: gzip (curl : --compressed).

Les colonnes sont, dans cet ordre : le temps, le Décalage UTC lorsqu'il s'applique, puis les indicateurs dans l'ordre de metrics.

La colonne de temps est formatée selon le pas, sauf si datetime_format est indiqué :

Chaque ligne est horodatée au début de son intervalle. Une valeur manquante est une cellule vide, de sorte que « pas de données » et « zéro » se distinguent ; empty=zero écrit 0 à la place.

Quatre en-têtes de la réponse reprennent ce qui a été résolu :

Réponse JSON

format=json fournit le même tableau sous forme de données structurées :

Remarques

Une remarque vous dit ce que Mirox a fait de lui-même. Elle ne fait jamais échouer un export. Les remarques font partie de la réponse JSON et de l'en-tête X-Mirox-Notes. L'en-tête contient jusqu'à 1 ko de remarques, écrites sous la forme code:clé=valeur,clé=valeur et séparées par ;. Si elles n'y tiennent pas toutes, l'en-tête se termine par notes_omitted:count=<n> ; la réponse JSON les contient toutes.

Une colonne vide est toujours conservée. Un indicateur qui ne s'applique pas à l'une des centrales, ou un indicateur de montant sans accès à la comptabilité, laisse sa colonne en place : la position des autres colonnes ne change donc jamais.

Estimer avant d'exporter

GET /v1/export/series/estimate

La route prend les paramètres de l'export, sans le format de fichier, et répond ce que serait l'export — sans lire de données et sans être décomptée du quota horaire.

Un refus ne fait jamais échouer l'estimation : elle répond 200 et liste le refus. L'estimation compte, elle ne produit rien : les libellés de ligne et les en-têtes sont ceux de l'export. Une requête brute compte comme une colonne par centrale, et avec mismatch=sparse les remarques nomment les colonnes regroupées et clairsemées.

Le catalogue des indicateurs

GET /v1/export/series/catalog

Chaque indicateur porte, à côté de son identifiant, de son nom, de sa description, de son unité et de son niveau :

Jusqu'à 10 centrales, chaque centrale est vérifiée quant à l'équipement dont un indicateur a besoin. Au-delà, les centrales ne sont évaluées que par leur type ; ce qui manque à une centrale donnée apparaît au moment de l'export sous forme de remarque metric_unavailable.

Glossaire. format=csv fournit toute la liste filtrée sous forme de fichier, metric_catalog_<langue>.csv, avec les colonnes identifiant, niveau, nom, unité, description, grandeur, modes de valeurs, pas, intervalle de mesure, regroupement sur les centrales, remarque et identifiants précédents. page et limit ne s'appliquent pas.

curl "https://service.mirox.io/api/v1/export/series/catalog?format=csv&language=en" \
  -H "Authorization: Bearer YOUR_API_TOKEN" -o metric_catalog_en.csv

Indicateurs disponibles

La collection est classée par niveau. Le préfixe d'un identifiant indique où se situe un indicateur.

La liste complète avec noms, unités et descriptions dans votre langue se trouve dans le catalogue, dans le fichier de glossaire ou sous Explications dans l'onglet Métriques. Les valeurs de prévision météo de l'export précédent ne font pas partie de la collection ; voir le guide de migration.

Composants d'une centrale

GET /v1/export/series/lanes

Chaque entrée comporte la référence ref pour le paramètre components, le name, le level, le parent (parent_ref, parent_name — l'onduleur d'un string, par exemple), des attributes (role d'un compteur, position d'un capteur d'irradiance, vendor), hidden, et source : db pour une entrée des composants de la centrale, store pour une série mesurée mais sans entrée de ce type.

Une centrale qui n'existe pas et une centrale que vous ne pouvez pas lire répondent toutes deux 404 park_not_found.

Système de modèles

Un modèle est une liste d'indicateurs enregistrée, avec des valeurs par défaut pour le pas, la période, les valeurs, le fuseau horaire, le regroupement des centrales, la taille de page des composants et les en-têtes de colonne. À quoi servent les modèles et comment les gérer dans l'application est expliqué dans le guide Metric Export.

Exporter un modèle

GET /v1/export/series/template/{template_uid}

La route prend les paramètres de l'export sauf metrics, components et values, que le modèle fixe. Chaque paramètre que vous omettez prend la valeur par défaut du modèle ; chaque paramètre que vous indiquez l'emporte sur elle.

curl --compressed "https://service.mirox.io/api/v1/export/series/template/CAFE1000CAFE?park=ABC123DEF456&window=previous_month&header=id" \
  -H "Authorization: Bearer YOUR_API_TOKEN" -o standard.csv

• Un modèle d'une autre organisation répond 404 template_not_found.
• Un ancien modèle répond 400 template_is_legacy ; params.legacy_url est le lien qui l'exporte.
• Une colonne dont l'indicateur n'est plus disponible est exportée vide sous son en-tête, avec la remarque metric_unavailable. Il en va de même pour un indicateur de votre organisation lorsque vous exportez en tant qu'Externe (reason not_permitted).

Modèles système

Les cinq premiers succèdent à CAFE0000CAFE, CAFE0001CAFE, CAFE0002CAFE, CAFE0003CAFE et ABCD12340001, qui continuent de fonctionner sur l'ancienne route. Leurs colonnes sont listées dans le guide de migration. Ils proposent les pas day, week, month, quarter et year ; les quatre premiers proposent en plus 15min et 1h.

Gérer les modèles

Les modèles sont listés, lus, créés, modifiés et supprimés sous /v1/export/template. La lecture fonctionne avec un jeton Metric Export. L'écriture exige le rôle d'organisation Admin, Modérateur, Gestionnaire d’actifs (technique) ou Gestionnaire d’actifs (commercial) et une connexion ou un jeton Accès complet.

Le spec d'un modèle :

label est le texte d'en-tête de la colonne avec header=name. Un indicateur ne peut apparaître qu'une fois, et un modèle ne contient pas de requêtes brutes. À l'enregistrement d'un modèle, chaque indicateur doit être exportable et les indicateurs doivent avoir un pas en commun — sous mismatch=sparse, chacun doit proposer un pas quelconque ; sinon la réponse est 422 spec_invalid, et params.problems nomme l'indicateur et la raison. Un modèle s'exécute avec son propre mismatch (l'application l'affiche comme Métriques d'un autre pas : Strict ou Souple) ; le paramètre du lien d'export l'emporte.

Convertir un ancien modèle

POST /v1/export/template/{template_uid}/convert

La réponse liste mapped (legacy_id, metric, values, exactness : exact ou approximate) et unmapped (legacy_id, reason : formula, no_equivalent, report_value ou instant, et jusqu'à trois suggestions), ainsi que, sauf s'il s'agissait d'un essai à blanc, le nouveau template. Un essai à blanc répond 200, une conversion 201.

Le nouveau modèle exporte des jours sur le mois précédent. L'ancien modèle n'est jamais modifié. Deux anciennes colonnes qui lisent le même compteur deviennent une seule colonne. 422 nothing_to_convert signifie qu'aucune colonne n'a d'équivalent, ou que le modèle n'est pas un ancien modèle.

Limites

Un export est servi en une seule requête ; sa taille est donc bornée. Chaque limite est vérifiée avant la lecture des données ; une requête trop volumineuse est refusée immédiatement et vous indique ce qui conviendrait.

Scinder un export volumineux

400 over_budget nomme dans params ce qui était nécessaire et ce qui est autorisé, et dans hint l'issue : step, le pas immédiatement plus grossier qui convient, et max_days, la période la plus longue qui convient au pas demandé. Interrogez d'abord l'estimation si vous construisez des requêtes dans un script ; son per_step liste la taille pour chaque pas.

Si ni un pas plus grossier ni une période plus courte ne vous conviennent, scindez l'export :

Certains indicateurs sont déterminés à partir de plusieurs sources pour chaque jour, avant tout plant.production_reported (Production, résolue). Ils exigent bien plus de lectures de la base de mesures qu'un relevé de compteur, à chaque pas. Une requête ou un modèle qui porte un tel indicateur couvre actuellement environ neuf mois-centrale : une centrale sur neuf mois, ou neuf centrales sur un mois. Un pas d'une semaine ou plus élargit la période à des intervalles entiers, et c'est la période élargie qui compte. Scindez de tels exports par période ou par centrale, ou exportez l'indicateur dans une requête à part.

429 busy et 429 rate_limited portent l'en-tête Retry-After avec le nombre de secondes à attendre.

Erreurs

Une erreur des routes de cette page a la forme suivante :

{
  "detail": {
    "code": "step_not_served",
    "message": "The step is not served by every requested metric.",
    "params": {"step": "1h", "metrics": {"plant.grid_power": ["1min", "5min", "15min"]}},
    "hint": {"offered_common": ["1min", "5min", "15min"]}
  }
}

code est stable et destiné aux programmes. message est un texte en anglais destiné aux personnes. params indique ce qui n'allait pas, hint ce qui fonctionnerait.

401 signifie que le jeton est absent, expiré ou révoqué.

Identifiants de l'export précédent

Le paramètre metrics accepte aussi les identifiants de l'export précédent, comme energy_grid_daily ou raw_grid_power. Un identifiant qui a un équivalent est traduit en son indicateur, dans le mode de valeurs le plus proche du nombre précédent, et la remarque legacy_id_mapped indique quel indicateur a répondu et si le nombre est le même (exact) ou s'il s'agit de la même grandeur lue d'une meilleure façon (approximate).

Un identifiant sans équivalent répond 400 legacy_metric_id. hint.reason indique pourquoi, hint.closest nomme l'indicateur le plus proche lorsqu'il y en a un, hint.pending nomme l'indicateur prévu pour le reprendre, et legacy_url est le lien de l'export précédent qui fournit toujours l'identifiant. Avec plus de centrales qu'un lien ne peut en nommer, legacy_url nomme la première centrale et params.legacy_url_scope vaut first. Un identifiant de composant d'un niveau de batterie n'a pas de lien de l'export précédent ; hint.legacy_route vaut alors none. Le guide de migration liste chaque identifiant.

Excel et scripts

• Metric Export pour Excel — des recettes, et la connexion Power Query avec l'en-tête Authorization
• Générateur de rapports externe — un exemple Python complet

Fonctionnalités associées

• Metric Export — la page Export de données
• Migrer vers le Metric Export — anciens identifiants, nouveaux indicateurs et ce qui change
• API de l'ancien export — les liens d'export précédents
• Indicateurs — définissez vos propres indicateurs et exportez-les
• Jetons d'API — créez le jeton Metric Export
• Aperçu de l'API — la référence interactive de toutes les routes