Metric Export API

La Metric Export API fornisce qualsiasi metrica dei tuoi impianti come serie temporale, in CSV o JSON, con una sola richiesta GET. Legge la stessa raccolta di metriche dei report, comprese le metriche che la tua organizzazione ha definito.

Ogni link mostrato dalla pagina Esportazione dati è una chiamata a questa API, quindi il modo più semplice per arrivare a una richiesta funzionante è costruirla lì e copiarla.

I link dell'esportazione precedente continuano a funzionare senza modifiche. Sono descritti nell'API di esportazione legacy; come passare dall'una all'altra è spiegato nella guida alla migrazione.

Route

Tutti i percorsi seguono https://service.mirox.io/api.

Autenticazione

Invia un token API del gruppo Metric Export nell'header Authorization:

Authorization: Bearer YOUR_API_TOKEN

Il token legge ogni route di esportazione di questa pagina e le route legacy. Non può creare, modificare o eliminare nulla. In un browser in cui hai effettuato l'accesso a Mirox, i link funzionano senza token.

Ricevi solo i dati degli impianti di cui puoi leggere le misure. Le metriche della tua organizzazione vengono esportate da ogni ruolo organizzativo tranne Esterno. Vedi Chi può esportare che cosa.

Esportare una serie temporale

GET /v1/export/series

Immissione in rete di un impianto nel mese precedente, per giorno:

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
...

Parametri

lane_limit e lane_page fuori dai loro limiti vengono portati al limite più vicino. Un parametro che la route non conosce viene ignorato.

Metriche e valori

Un ID di metrica ha la forma <prefisso>.<nome>, ad esempio plant.grid_feedin, inverter.ac_power o sensor.irradiance. Una metrica della tua organizzazione è organization.<ID della metrica>. Il catalogo le elenca tutte.

Ogni metrica ha una grandezza, che decide le modalità dei valori offerte:

Un suffisso imposta la modalità di una singola metrica e prevale su values:

metrics=plant.grid_feedin:cumulative,plant.grid_power

Una modalità che non si applica a una metrica non è mai un errore. La metrica viene esportata come native e la nota value_mode_ignored lo segnala. delta non viene mai applicato a una potenza.

La stessa metrica in due modalità dà due colonne. La stessa metrica due volte nella stessa modalità ne dà una.

Periodo

Indica il periodo in uno solo di tre modi. Due modi nella stessa richiesta rispondono 400 window_conflict.

Periodo libero. start ed end sono una data (2026-07-01) oppure una data con ora (2026-07-01T06:00, 2026-07-01T06:00:00Z, 2026-07-01T06:00:00+02:00). Un valore senza fuso orario viene letto nel fuso orario delle righe. Un end che è una data include quel giorno; un end con ora è il momento in cui il periodo finisce. Senza end, il periodo finisce adesso. end da solo, senza start, viene rifiutato.

Calendario. year dal 2020 al 2100, quarter da 1 a 4, month da 1 a 12, week da 1 a 53 (settimana ISO), day da 1 a 31. day richiede month. Senza year si intende l'anno corrente. day prevale su week, week su month, month su quarter.

Periodi predefiniti. today, yesterday, last_7_days, last_30_days, this_week, previous_week, this_month, previous_month, this_quarter, previous_quarter, this_year, previous_year. I periodi this_ arrivano fino ad adesso; last_7_days e last_30_days scorrono fino ad adesso con passi inferiori a un giorno (stessa ora 7 o 30 giorni prima); da day in su sono gli ultimi 7 o 30 giorni locali, oggi compreso. Da day in su ogni finestra viene estesa a giorni interi (settimane, mesi …) nel fuso orario dell'impianto e la risposta riporta la finestra effettiva.

Un periodo inizia al più presto nel 2020 e copre al massimo 1827 giorni (cinque anni). Un periodo che arriva nel futuro finisce adesso, con la nota end_clamped.

Passi

step=auto sceglie un passo che ogni metrica richiesta offre e che rispetta i limiti: 15min fino a due giorni, 1h fino a 62 giorni, day fino a tre anni, month oltre. Se quel passo non va bene, viene provato quello più grossolano successivo, poi quelli più fini. La nota step_auto e l'header X-Mirox-Step nominano il passo scelto.

Ogni metrica offre i propri passi. Il catalogo li elenca come export_steps:

La potenza è offerta solo a 15 minuti o più fine. Una potenza giornaliera o mensile è una media che nasconde ciò che è accaduto; la metrica di energia dà il valore che si intende.

Un passo non viene mai cambiato in silenzio. Con mismatch=refuse, il valore predefinito, un passo che una delle metriche non offre risponde 400 step_not_served con i passi di ogni metrica, e con step=auto le metriche che non hanno alcun passo in comune rispondono 400 no_common_step. Con mismatch=sparse, una richiesta del genere viene invece fornita — vedi Metriche con passi diversi.

I passi di un giorno o più coprono intervalli interi. Un periodo che inizia o finisce all'interno di uno di essi viene esteso verso l'esterno, con la nota window_aligned. Le settimane iniziano di lunedì.

Metriche con passi diversi

mismatch=sparse fornisce una richiesta le cui metriche non offrono tutte il passo, purché ciascuna offra un passo qualsiasi. La griglia del file è il passo richiesto; con step=auto è il passo che più metriche offrono così com'è, scelto in base al periodo e ai limiti come di consueto. Le posizioni delle colonne e la forma della risposta CSV e JSON non cambiano.

Due casi vengono rifiutati in entrambe le modalità, con 400 step_not_served: un valore per mese, trimestre o anno in un file per week, perché il suo primo giorno non è quasi mai un lunedì; e un valore mensile come il Marktwert in un file per quarter o year, perché una somma o una media di mesi non è quel valore. In un file per month viene letto così com'è; in uno più fine è sparso.

La stima elenca le stesse note, conta le letture al passo proprio di ogni metrica e segna un passo in per_step come entro i limiti anche quando non tutte le metriche lo offrono. La pagina Esportazione dati chiede sempre con mismatch=sparse; un modello porta il proprio mismatch nella sua spec.

Griglia temporale

Con tz=local, le righe seguono l'ora locale dell'impianto, ora legale compresa: un giorno è un giorno locale di 23, 24 o 25 ore, un mese è un mese locale. Con tz=utc, le righe seguono il calendario UTC.

• Con passi più brevi di un giorno nell'ora locale, la colonna Scostamento UTC segue la colonna temporale (+02:00). Nel giorno in cui l'orologio torna indietro, un'ora compare due volte; lo scostamento le distingue. offset_column=false omette la colonna.
• Impianti in fusi orari diversi condividono una sola colonna temporale. Una richiesta di questo tipo riceve risposta sul calendario UTC, con la nota merged_on_utc, sia che gli impianti siano riuniti sia che siano divisi.
• Con tz=utc e un passo di un giorno o più, una metrica che esiste solo per giorno locale non ha un valore UTC. La sua colonna resta vuota, con la nota utc_calendar_unsupported.

L'header X-Mirox-Grid nomina il calendario usato: local:Europe/Berlin oppure utc.

Più impianti

Con multi_park_agg=merge, ogni metrica è una colonna per tutti gli impianti, riunita secondo la regola della metrica. Il catalogo elenca la regola come merge:

Una metrica che non si può riunire viene esportata per impianto, con la nota merge_not_meaningful. Questo vale anche per un rapporto a un passo in cui le sue due metà non sono disponibili, e per i prezzi di impianti in zone di mercato diverse.

Con multi_park_agg=split, ogni metrica è una colonna per impianto. Con un solo impianto, entrambe danno lo stesso file.

Le metriche dei componenti sono sempre per impianto (nota components_split_by_park).

Componenti

Una metrica di un livello di componente dà una colonna per componente. I livelli sono inverter, gak (quadro di campo), string, turbine, sensor, meter, battery_box (container), battery_storage (rack), battery_module, battery_cell e battery_pcs (convertitore).

Senza components, l'esportazione contiene tutti i componenti visibili degli impianti, lane_limit per metrica e pagina. Se ce ne sono di più, la nota lanes_truncated ne indica il totale; richiedi la pagina successiva con lane_page.

components limita l'esportazione ai componenti che nomini. Un riferimento ha la forma <livello>:<id>, ad esempio inverter:1043. Un sensore o un contatore che Mirox misura ma che non ha una voce nei componenti dell'impianto ha un riferimento della forma sensor:h3f9c2a71b04e6d5. La route dei componenti elenca i riferimenti di un impianto. Un riferimento che non appartiene a nessuno degli impianti scelti risponde 400 unknown_lane.

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

Query MetricsQL grezze

expr aggiunge a un'esportazione una query grezza in MetricsQL, il linguaggio di interrogazione del database delle serie temporali della piattaforma — per una serie per cui la raccolta non ha una metrica. Il parametro può essere ripetuto fino a cinque volte; ogni espressione può avere fino a 4 000 caratteri. Una richiesta può portare solo expr, oppure metrics ed expr insieme; le colonne delle metriche vengono prima.

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

Un'espressione viene valutata per impianto, come la valuta una dashboard: sui dati dell'impianto stesso, al passo richiesto, come campioni grezzi — ogni passo è ammesso, values e le regole di aggregazione delle metriche non si applicano. Mirox aggiunge l'impianto a ogni selettore dell'espressione; un'espressione che nomina essa stessa un'etichetta park, organization o plant viene rifiutata con 400 expr_forbidden_label.

Quando un'espressione restituisce più serie su uno qualsiasi dei suoi impianti, le colonne di quell'espressione su ogni impianto portano le etichette delle serie, così un file ha una sola nomenclatura per espressione. Un'intestazione più lunga di 1 000 caratteri viene tagliata con … dentro l'espressione, mai nel testo della serie. Nella risposta JSON, columns[].key è il testo di header=id e columns[].metric è l'ID dell'espressione, expr.e1, expr.e2, …, che note e rifiuti usano. Un impianto su cui l'espressione non restituisce nulla mantiene una colonna vuota, con la nota expr_no_series; con più impianti, ogni impianto riceve le proprie colonne, con la nota expr_split_by_park.

Un'espressione può restituire al massimo 500 serie su un impianto (400 expr_too_many_series); aggregala, ad esempio con sum by (…). Le serie contano nelle stesse 400 colonne e 1 800 000 valori di ogni esportazione: la prima lettura di ogni espressione su ogni impianto è una breve sonda, le larghezze vengono sommate sull'intera richiesta, e una richiesta che supera i limiti viene rifiutata con 400 over_budget e params.series prima di qualsiasi lettura completa di qualsiasi espressione. Un'espressione che non si può analizzare, è vuota, è troppo lunga o che il database rifiuta risponde 400 expr_invalid con il reason.

La stima conta un'espressione come una colonna per impianto, perché le sue serie si conoscono solo alla lettura. Le espressioni non vengono salvate nei modelli.

Risposta CSV

La risposta è in UTF-8, con il nome di file series_export_<primo giorno>_<ultimo giorno>_<passo>.csv. Una risposta più grande di circa 1 MB viene compressa quando la richiesta contiene Accept-Encoding: gzip (curl: --compressed).

Le colonne sono, in questo ordine: il tempo, lo Scostamento UTC dove si applica, poi le metriche nell'ordine di metrics.

La colonna temporale è formattata secondo il passo, a meno che non sia indicato datetime_format:

Ogni riga porta l'inizio del suo intervallo. Un valore mancante è una cella vuota, così «nessun dato» e «zero» si possono distinguere; empty=zero scrive invece 0.

Quattro header della risposta ripetono ciò che è stato risolto:

Risposta JSON

format=json restituisce la stessa tabella come dati strutturati:

Note

Una nota ti dice che cosa Mirox ha fatto di propria iniziativa. Non fa mai fallire un'esportazione. Le note fanno parte della risposta JSON e dell'header X-Mirox-Notes. L'header contiene fino a 1 KB di note, scritte come code:key=value,key=value e separate da ;. Se non ci stanno tutte, l'header termina con notes_omitted:count=<n>; la risposta JSON le contiene tutte.

Una colonna vuota viene sempre mantenuta. Una metrica che non si applica a uno degli impianti, o una metrica monetaria senza il permesso di contabilità, lascia la sua colonna al suo posto, così le posizioni delle altre colonne non si spostano mai.

Stimare prima di esportare

GET /v1/export/series/estimate

La route accetta i parametri dell'esportazione, senza il formato del file, e risponde che cosa sarebbe l'esportazione — senza leggere dati e senza incidere sul limite orario.

Un rifiuto non fa mai fallire la stima: risponde 200 ed elenca il rifiuto. La stima conta, non genera nulla: le etichette delle righe e le intestazioni sono quelle dell'esportazione. Una query grezza conta come una colonna per impianto, e con mismatch=sparse le note nominano le colonne riunite e sparse.

Il catalogo delle metriche

GET /v1/export/series/catalog

Ogni metrica porta, accanto a ID, nome, descrizione, unità e livello:

Fino a 10 impianti, per ogni impianto viene verificata l'apparecchiatura di cui una metrica ha bisogno. Oltre, gli impianti vengono valutati solo in base al loro tipo; ciò che manca a un singolo impianto compare al momento dell'esportazione come nota metric_unavailable.

Glossario. format=csv restituisce l'intero elenco filtrato come file, metric_catalog_<language>.csv, con le colonne ID, livello, nome, unità, descrizione, grandezza, modalità dei valori, passi, intervallo di misura, combinazione tra impianti, nota e ID precedenti. page e limit non si applicano.

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

Metriche disponibili

La raccolta è ordinata per livello. Il prefisso di un ID dice a che cosa appartiene una metrica.

L'elenco completo con nomi, unità e descrizioni nella tua lingua è il catalogo, il file del glossario, oppure Spiegazioni nella scheda Metriche. I valori delle previsioni meteo dell'esportazione precedente non fanno parte della raccolta; vedi la guida alla migrazione.

Componenti di un impianto

GET /v1/export/series/lanes

Ogni voce ha il riferimento ref per il parametro components, il name, il level, il componente superiore (parent_ref, parent_name — l'inverter di una stringa, ad esempio), attributes (role di un contatore, position di un sensore di irraggiamento, vendor), hidden, e source: db per una voce dei componenti dell'impianto, store per una serie misurata che non ha una voce di questo tipo.

Un impianto che non esiste e un impianto che non puoi leggere rispondono entrambi 404 park_not_found.

Sistema dei modelli

Un modello è un elenco salvato di metriche con impostazioni predefinite per passo, periodo, valori, fuso orario, combinazione degli impianti, dimensione della pagina dei componenti e intestazioni di colonna. A che cosa servono i modelli e come gestirli nell'app è descritto nella guida al Metric Export.

Esportare un modello

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

La route accetta i parametri dell'esportazione tranne metrics, components e values, che sono fissati dal modello. Ogni parametro che ometti assume il valore predefinito del modello; ogni parametro che indichi prevale su di esso.

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 modello di un'altra organizzazione risponde 404 template_not_found.
• Un modello legacy risponde 400 template_is_legacy; params.legacy_url è il link che lo esporta.
• Una colonna la cui metrica non è più disponibile viene esportata vuota sotto la sua intestazione, con la nota metric_unavailable. Lo stesso vale per una metrica della tua organizzazione quando esporti come Esterno (reason not_permitted).

Modelli di sistema

I primi cinque succedono a CAFE0000CAFE, CAFE0001CAFE, CAFE0002CAFE, CAFE0003CAFE e ABCD12340001, che continuano a funzionare sulla route legacy. Le loro colonne sono elencate nella guida alla migrazione. Offrono i passi day, week, month, quarter e year; i quattro modelli di esportazione anche 15min e 1h.

Gestire i modelli

I modelli vengono elencati, letti, creati, modificati ed eliminati sotto /v1/export/template. La lettura funziona con un token Metric Export. La scrittura richiede il ruolo organizzativo Admin, Moderatore, Asset Manager (tecnico) o Asset Manager (commerciale) e un accesso oppure un token Full Access.

Lo spec di un modello:

label è il testo di intestazione della colonna con header=name. Una metrica può comparire una sola volta, e un modello non contiene query grezze. Quando un modello viene salvato, ogni metrica deve essere esportabile e le metriche devono avere un passo in comune — con mismatch=sparse, ciascuna deve offrire un passo qualsiasi; altrimenti la risposta è 422 spec_invalid e params.problems nomina la metrica e il motivo. Un modello viene eseguito con il proprio mismatch (l'app lo mostra come Metriche con un altro passo: Rigoroso o Tollerante); il parametro nel link di esportazione prevale.

Convertire un modello legacy

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

La risposta elenca mapped (legacy_id, metric, values, exactness: exact o approximate) e unmapped (legacy_id, reason: formula, no_equivalent, report_value o instant, e fino a tre suggestions), e, a meno che non fosse una prova, il nuovo template. Una prova risponde 200, una conversione 201.

Il nuovo modello esporta giorni sul mese precedente. Il modello legacy non viene mai modificato. Due colonne legacy che leggono lo stesso contatore diventano una sola colonna. 422 nothing_to_convert significa che nessuna colonna ha un equivalente, oppure che il modello non è un modello legacy.

Limiti

Un'esportazione riceve risposta all'interno di una sola richiesta, quindi la sua dimensione è limitata. Ogni limite viene controllato prima di leggere i dati; una richiesta troppo grande viene rifiutata subito e ti dice che cosa ci starebbe.

Dividere un'esportazione grande

400 over_budget indica in params che cosa serviva e che cosa è consentito, e in hint la via d'uscita: step, il passo più grossolano successivo che ci sta, e max_days, il periodo più lungo che ci sta con il passo richiesto. Se costruisci le richieste in uno script, interroga prima la stima; il suo per_step elenca la dimensione per ogni passo.

Se non vuoi né un passo più grossolano né un periodo più breve, dividi l'esportazione:

Alcune metriche vengono ricavate da più fonti per ogni giorno, prima fra tutte plant.production_reported (Produzione, risolta). Richiedono molte più letture dell'archivio delle misure rispetto a una lettura del contatore, a ogni passo. Una richiesta o un modello che contiene una metrica di questo tipo raggiunge attualmente circa nove mesi-impianto: un impianto su nove mesi, oppure nove impianti su un mese. Un passo di una settimana o più lungo estende il periodo a intervalli interi, e conta il periodo esteso. Dividi queste esportazioni per tempo o per impianto, oppure esporta la metrica in una richiesta a parte.

429 busy e 429 rate_limited portano l'header Retry-After con i secondi da attendere.

Errori

Un errore delle route di questa pagina ha questa forma:

{
  "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 è stabile e pensato per i programmi. message è un testo in inglese per le persone. params dice che cosa non andava, hint che cosa funzionerebbe.

401 significa che il token manca, è scaduto o è stato revocato.

ID dell'esportazione precedente

Il parametro metrics accetta anche gli ID dell'esportazione precedente, come energy_grid_daily o raw_grid_power. Un ID con un equivalente viene tradotto nella sua metrica, nella modalità dei valori che più si avvicina al numero precedente, e la nota legacy_id_mapped dice quale metrica ha risposto e se il numero è lo stesso (exact) o la stessa grandezza letta in modo migliore (approximate).

Un ID senza equivalente risponde 400 legacy_metric_id. hint.reason dice perché, hint.closest nomina la metrica più vicina dove ce n'è una, hint.pending nomina la metrica prevista per fornirlo, e legacy_url è il link dell'esportazione precedente che fornisce ancora l'ID. Con più impianti di quanti un link possa nominarne, legacy_url nomina il primo impianto e params.legacy_url_scope è first. Un ID di componente di un livello di batteria non ha un link dell'esportazione precedente; in tal caso hint.legacy_route è none. La guida alla migrazione elenca ogni ID.

Excel e script

• Metric Export per Excel — ricette e la connessione Power Query con l'header Authorization
• Generatore di report esterni — un esempio completo in Python

Funzionalità correlate

• Metric Export — la pagina Esportazione dati
• Migrare al Metric Export — vecchi ID, nuove metriche e che cosa cambia
• API di esportazione legacy — i link di esportazione precedenti
• Metriche — definisci metriche tue ed esportale
• Token API — crea il token Metric Export
• Panoramica delle API — il riferimento interattivo di tutte le route